com.google.gwt.user.client.ui

## Class Composite

- java.lang.Object
- - com.google.gwt.user.client.ui.UIObject
  - - com.google.gwt.user.client.ui.Widget
    - - com.google.gwt.user.client.ui.Composite

- All Implemented Interfaces:
    HasAttachHandlers, HasHandlers, EventListener, HasVisibility, IsRenderable, IsWidget
  Direct Known Subclasses:
    AbstractCellTree, AbstractHasData, AbstractPager, CaptionPanel, DateBox, DatePicker, DatePickerComponent, DisclosurePanel, NotificationMole, ResizeComposite, SuggestBox, TabBar, TabPanel, ValueBoxEditorDecorator, ValueListBox, ValuePicker

      public abstract class Composite
      extends Widget
      implements IsRenderable

  A type of widget that can wrap another widget, hiding the wrapped widget's methods. When added to a panel, a composite behaves exactly as if the widget it wraps had been added.

  The composite is useful for creating a single widget out of an aggregate of multiple other widgets contained in a single panel.

  ### Example

  >     public class CompositeExample implements EntryPoint {

  >       /**
  >        * A composite of a TextBox and a CheckBox that optionally enables it.
  >        */
  >       private static class OptionalTextBox extends Composite implements
  >           ClickHandler {

  >         private TextBox textBox = new TextBox();
  >         private CheckBox checkBox = new CheckBox();

  >         /**
  >          * Constructs an OptionalTextBox with the given caption on the check.
  >          *
  >          * @param caption the caption to be displayed with the check box
  >          */
  >         public OptionalTextBox(String caption) {
  >           // Place the check above the text box using a vertical panel.
  >           VerticalPanel panel = new VerticalPanel();
  >           panel.add(checkBox);
  >           panel.add(textBox);

  >           // Set the check box's caption, and check it by default.
  >           checkBox.setText(caption);
  >           checkBox.setChecked(true);
  >           checkBox.addClickHandler(this);

  >           // All composites must call initWidget() in their constructors.
  >           initWidget(panel);

  >           // Give the overall composite a style name.
  >           setStyleName("example-OptionalCheckBox");
  >         }

  >         public void onClick(ClickEvent event) {
  >           if (event.getSource() == checkBox) {
  >             // When the check box is clicked, update the text box's enabled state.
  >             textBox.setEnabled(checkBox.isChecked());
  >           }
  >         }

  >         /**
  >          * Sets the caption associated with the check box.
  >          *
  >          * @param caption the check box's caption
  >          */
  >         public void setCaption(String caption) {
  >           // Note how we use the use composition of the contained widgets to provide
  >           // only the methods that we want to.
  >           checkBox.setText(caption);
  >         }

  >         /**
  >          * Gets the caption associated with the check box.
  >          *
  >          * @return the check box's caption
  >          */
  >         public String getCaption() {
  >           return checkBox.getText();
  >         }
  >       }

  >       public void onModuleLoad() {
  >         // Create an optional text box and add it to the root panel.
  >         OptionalTextBox otb = new OptionalTextBox("Check this to enable me");
  >         RootPanel.get().add(otb);
  >       }
  >     }

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

      `UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

  - ### Field Summary

    - ### Fields inherited from class com.google.gwt.user.client.ui.Widget

      `eventsToSink`

    - ### Fields inherited from class com.google.gwt.user.client.ui.UIObject

      `DEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Composite()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `claimElement(Element element)` Replace the previous contents of the receiver with the given element, presumed to have been created and stamped via a previous call to `IsRenderable.render(com.google.gwt.user.client.ui.RenderableStamper)`.
    `protected Widget` | `getWidget()` Provides subclasses access to the topmost widget that defines this composite.
    `void` | `initializeClaimedElement()` Perform any initialization needed when the widget is not attached to the document.
    `protected void` | `initWidget(Widget widget)` Sets the widget to be wrapped by the composite.
    `boolean` | `isAttached()` Determines whether this widget is currently attached to the browser's document (i.e., there is an unbroken chain of widgets between this widget and the underlying browser document).
    `protected void` | `onAttach()` This method is called when a widget is attached to the browser's document.
    `void` | `onBrowserEvent(Event event)` Fired whenever a browser event is received.
    `protected void` | `onDetach()` This method is called when a widget is detached from the browser's document.
    `SafeHtml` | `render(RenderableStamper stamper)`
    `void` | `render(RenderableStamper stamper, SafeHtmlBuilder builder)` Tells this object to render itself as HTML and append it to the given builder.
    `protected Element` | `resolvePotentialElement()` EXPERIMENTAL and subject to change.
    `protected void` | `setWidget(Widget widget)` Deprecated. Use `initWidget(Widget)` instead

    - ### Methods inherited from class com.google.gwt.user.client.ui.Widget

      `addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, doAttachChildren, doDetachChildren, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isOrWasAttached, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents`

    - ### Methods inherited from class com.google.gwt.user.client.ui.UIObject

      `addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getOffsetHeight, getOffsetWidth, getStyleElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, getTitle, isVisible, isVisible, onEnsureDebugId, removeStyleDependentName, removeStyleName, setElement, setElement, setHeight, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, sinkBitlessEvent, toString, unsinkEvents`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Composite

          public Composite()

  - ### Method Detail

    - #### claimElement

          public void claimElement(Element element)

      Description copied from interface: `IsRenderable`
      Replace the previous contents of the receiver with the given element, presumed to have been created and stamped via a previous call to `IsRenderable.render(com.google.gwt.user.client.ui.RenderableStamper)`.
      Specified by:
        `claimElement` in interface `IsRenderable`

    - #### initializeClaimedElement

          public void initializeClaimedElement()

      Description copied from interface: `IsRenderable`
      Perform any initialization needed when the widget is not attached to the document. Assumed to be called after `IsRenderable.claimElement(com.google.gwt.dom.client.Element)`.
      Specified by:
        `initializeClaimedElement` in interface `IsRenderable`

    - #### isAttached

          public boolean isAttached()

      Description copied from class: `Widget`
      Determines whether this widget is currently attached to the browser's document (i.e., there is an unbroken chain of widgets between this widget and the underlying browser document).
      Specified by:
        `isAttached` in interface `HasAttachHandlers`
      Overrides:
        `isAttached` in class `Widget`
      Returns:
        `true` if the widget is attached

    - #### onBrowserEvent

          public void onBrowserEvent(Event event)

      Description copied from interface: `EventListener`
      Fired whenever a browser event is received.
      Specified by:
        `onBrowserEvent` in interface `EventListener`
      Overrides:
        `onBrowserEvent` in class `Widget`
      Parameters:
        `event` - the event received

    - #### render

          public SafeHtml render(RenderableStamper stamper)

      Specified by:
        `render` in interface `IsRenderable`
      See Also:
        `TODO(rdcastro): Remove this once UiBinder doesn't rely on it anymore.`

    - #### render

          public void render(RenderableStamper stamper,
                    SafeHtmlBuilder builder)

      Description copied from interface: `IsRenderable`
      Tells this object to render itself as HTML and append it to the given builder. If the implementation expects to be able to claim an element later, it must be marked by the given stamper.
      Specified by:
        `render` in interface `IsRenderable`

    - #### getWidget

          protected Widget getWidget()

      Provides subclasses access to the topmost widget that defines this composite.
      Returns:
        the widget

    - #### initWidget

          protected void initWidget(Widget widget)

      Sets the widget to be wrapped by the composite. The wrapped widget must be set before calling any `Widget` methods on this object, or adding it to a panel. This method may only be called once for a given composite.
      Parameters:
        `widget` - the widget to be wrapped

    - #### onAttach

          protected void onAttach()

      Description copied from class: `Widget`

      This method is called when a widget is attached to the browser's document. To receive notification after a Widget has been added to the document, override the `Widget.onLoad()` method or use `Widget.addAttachHandler(com.google.gwt.event.logical.shared.AttachEvent.Handler)`.

      It is strongly recommended that you override `Widget.onLoad()` or `Widget.doAttachChildren()` instead of this method to avoid inconsistencies between logical and physical attachment states.

      Subclasses that override this method must call `super.onAttach()` to ensure that the Widget has been attached to its underlying Element.

      Overrides:
        `onAttach` in class `Widget`
      See Also:
        `Widget.onLoad()`, `Widget.doAttachChildren()`

    - #### onDetach

          protected void onDetach()

      Description copied from class: `Widget`

      This method is called when a widget is detached from the browser's document. To receive notification before a Widget is removed from the document, override the `Widget.onUnload()` method or use `Widget.addAttachHandler(com.google.gwt.event.logical.shared.AttachEvent.Handler)`.

      It is strongly recommended that you override `Widget.onUnload()` or `Widget.doDetachChildren()` instead of this method to avoid inconsistencies between logical and physical attachment states.

      Subclasses that override this method must call `super.onDetach()` to ensure that the Widget has been detached from the underlying Element. Failure to do so will result in application memory leaks due to circular references between DOM Elements and JavaScript objects.

      Overrides:
        `onDetach` in class `Widget`
      See Also:
        `Widget.onUnload()`, `Widget.doDetachChildren()`

    - #### resolvePotentialElement

          protected Element resolvePotentialElement()

      Description copied from class: `UIObject`
      EXPERIMENTAL and subject to change. Do not use this in production code.

      To be overridden by `IsRenderable` subclasses that initialize themselves by by calling `setElement(PotentialElement.build(this))`.

      The receiver must:

      - create a real `Element` to replace its `PotentialElement`
      - call `#setElement()` with the new Element
      - and return the new Element

      This method is called when the receiver's element is about to be added to a parent node, as a side effect of `DOM.appendChild(com.google.gwt.user.client.Element, com.google.gwt.user.client.Element)`.

      Note that this method is normally called only on the top element of an IsRenderable tree. Children instead will receive `IsRenderable.render(com.google.gwt.user.client.ui.RenderableStamper)` and `IsRenderable.claimElement(Element)`.

      Overrides:
        `resolvePotentialElement` in class `UIObject`
      See Also:
        `PotentialElement`, `IsRenderable`

    - #### setWidget

          @Deprecated
          protected void setWidget(Widget widget)

      Deprecated. Use `initWidget(Widget)` instead
      This method was for initializing the Widget to be wrapped by this Composite, but has been deprecated in favor of `initWidget(Widget)`.