com.google.gwt.user.client.ui

## Class Widget

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

- All Implemented Interfaces:
    HasAttachHandlers, HasHandlers, EventListener, HasVisibility, IsWidget
  Direct Known Subclasses:
    AbstractNativeScrollbar, CellGridImpl.Cell, CellWidget, Composite, DataGrid.TableWidget, FileUpload, FocusWidget, Frame, Hidden, Hyperlink, Image, LabelBase, MenuBar, Panel, SplitLayoutPanel.Splitter, Tree

      public class Widget
      extends UIObject
      implements EventListener, HasAttachHandlers, IsWidget

  The base class for the majority of user-interface objects. Widget adds support for receiving events from the browser and being added directly to `panels`.

- - ### Nested Class Summary

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

      `UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) int` | `eventsToSink` A bit-map of the events that should be sunk when the widget is attached to the DOM.

    - ### 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
    `Widget()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `HandlerRegistration` | `addAttachHandler(AttachEvent.Handler handler)` Adds an `AttachEvent` handler.
    `<H extends EventHandler> HandlerRegistration` | `addBitlessDomHandler(H handler, DomEvent.Type<H> type)` For browsers which do not leak, adds a native event handler to the widget.
    `<H extends EventHandler> HandlerRegistration` | `addDomHandler(H handler, DomEvent.Type<H> type)` Adds a native event handler to the widget and sinks the corresponding native event.
    `<H extends EventHandler> HandlerRegistration` | `addHandler(H handler, GwtEvent.Type<H> type)` Adds this handler to the widget.
    `Widget` | `asWidget()` Returns the `Widget` aspect of the receiver.
    `static Widget` | `asWidgetOrNull(IsWidget w)` This convenience method makes a null-safe call to `IsWidget.asWidget()`.
    `protected HandlerManager` | `createHandlerManager()` Creates the `HandlerManager` used by this Widget.
    `protected void` | `delegateEvent(Widget target, GwtEvent<?> event)` Fires an event on a child widget.
    `protected void` | `doAttachChildren()` If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call `onAttach()` for each of its child widgets.
    `protected void` | `doDetachChildren()` If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call `onDetach()` for each of its child widgets.
    `(package private) HandlerManager` | `ensureHandlers()` Ensures the existence of the handler manager.
    `void` | `fireEvent(GwtEvent<?> event)` Fires the given event to the handlers listening to the event's type.
    `protected int` | `getHandlerCount(GwtEvent.Type<?> type)` Gets the number of handlers listening to the event type.
    `(package private) HandlerManager` | `getHandlerManager()`
    `java.lang.Object` | `getLayoutData()` Gets the panel-defined layout data associated with this widget.
    `Widget` | `getParent()` Gets this widget's parent panel.
    `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 boolean` | `isOrWasAttached()` Has this widget ever been attached?
    `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.
    `protected void` | `onLoad()` This method is called immediately after a widget becomes attached to the browser's document.
    `protected void` | `onUnload()` This method is called immediately before a widget will be detached from the browser's document.
    `void` | `removeFromParent()` Removes this widget from its parent widget, if one exists.
    `(package private) void` | `replaceElement(Element elem)` Replaces this object's browser element.
    `void` | `setLayoutData(java.lang.Object layoutData)` Sets the panel-defined layout data associated with this widget.
    `(package private) void` | `setParent(Widget parent)` Sets this widget's parent.
    `void` | `sinkEvents(int eventBitsToAdd)` Overridden to defer the call to super.sinkEvents until the first time this widget is attached to the dom, as a performance enhancement.

    - ### 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, resolvePotentialElement, 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`

- - ### Field Detail

    - #### eventsToSink

          int eventsToSink

      A bit-map of the events that should be sunk when the widget is attached to the DOM. (We delay the sinking of events to improve startup performance.) When the widget is attached, this is set to -1

      Package protected to allow Composite to see it.

  - ### Constructor Detail

    - #### Widget

          public Widget()

  - ### Method Detail

    - #### asWidgetOrNull

          public static Widget asWidgetOrNull(IsWidget w)

      This convenience method makes a null-safe call to `IsWidget.asWidget()`.
      Returns:
        the widget aspect, or `null` if w is null

    - #### addAttachHandler

          public HandlerRegistration addAttachHandler(AttachEvent.Handler handler)

      Description copied from interface: `HasAttachHandlers`
      Adds an `AttachEvent` handler.
      Specified by:
        `addAttachHandler` in interface `HasAttachHandlers`
      Parameters:
        `handler` - the handler
      Returns:
        the handler registration

    - #### addBitlessDomHandler

          public final <H extends EventHandler> HandlerRegistration addBitlessDomHandler(H handler,
                                                                          DomEvent.Type<H> type)

      For browsers which do not leak, adds a native event handler to the widget. Note that, unlike the `addDomHandler(EventHandler, com.google.gwt.event.dom.client.DomEvent.Type)` implementation, there is no need to attach the widget to the DOM in order to cause the event handlers to be attached.
      Type Parameters:
        `H` - the type of handler to add
      Parameters:
        `type` - the event key
        `handler` - the handler
      Returns:
        `HandlerRegistration` used to remove the handler

    - #### addDomHandler

          public final <H extends EventHandler> HandlerRegistration addDomHandler(H handler,
                                                                   DomEvent.Type<H> type)

      Adds a native event handler to the widget and sinks the corresponding native event. If you do not want to sink the native event, use the generic addHandler method instead.
      Type Parameters:
        `H` - the type of handler to add
      Parameters:
        `type` - the event key
        `handler` - the handler
      Returns:
        `HandlerRegistration` used to remove the handler

    - #### addHandler

          public final <H extends EventHandler> HandlerRegistration addHandler(H handler,
                                                                GwtEvent.Type<H> type)

      Adds this handler to the widget.
      Type Parameters:
        `H` - the type of handler to add
      Parameters:
        `type` - the event type
        `handler` - the handler
      Returns:
        `HandlerRegistration` used to remove the handler

    - #### asWidget

          public Widget asWidget()

      Description copied from interface: `IsWidget`
      Returns the `Widget` aspect of the receiver.
      Specified by:
        `asWidget` in interface `IsWidget`

    - #### fireEvent

          public void fireEvent(GwtEvent<?> event)

      Description copied from interface: `HasHandlers`
      Fires the given event to the handlers listening to the event's type.

      Any exceptions thrown by handlers will be bundled into a `UmbrellaException` and then re-thrown after all handlers have completed. An exception thrown by a handler will not prevent other handlers from executing.

      Specified by:
        `fireEvent` in interface `HasHandlers`
      Parameters:
        `event` - the event

    - #### getLayoutData

          public java.lang.Object getLayoutData()

      Gets the panel-defined layout data associated with this widget.
      Returns:
        the widget's layout data
      See Also:
        `setLayoutData(java.lang.Object)`

    - #### getParent

          public Widget getParent()

      Gets this widget's parent panel.
      Returns:
        the widget's parent panel

    - #### isAttached

          public 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).
      Specified by:
        `isAttached` in interface `HasAttachHandlers`
      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`
      Parameters:
        `event` - the event received

    - #### removeFromParent

          public void removeFromParent()

      Removes this widget from its parent widget, if one exists.

      If it has no parent, this method does nothing. If it is a "root" widget (meaning it's been added to the detach list via `RootPanel.detachOnWindowClose(Widget)`), it will be removed from the detached immediately. This makes it possible for Composites and Panels to adopt root widgets.

      Throws:
        `java.lang.IllegalStateException` - if this widget's parent does not support removal (e.g. `Composite`)

    - #### setLayoutData

          public void setLayoutData(java.lang.Object layoutData)

      Sets the panel-defined layout data associated with this widget. Only the panel that currently contains a widget should ever set this value. It serves as a place to store layout bookkeeping data associated with a widget.
      Parameters:
        `layoutData` - the widget's layout data

    - #### sinkEvents

          public void sinkEvents(int eventBitsToAdd)

      Overridden to defer the call to super.sinkEvents until the first time this widget is attached to the dom, as a performance enhancement. Subclasses wishing to customize sinkEvents can preserve this deferred sink behavior by putting their implementation behind a check of `isOrWasAttached()`:

           @Override
           public void sinkEvents(int eventBitsToAdd) {
             if (isOrWasAttached()) {
               /* customized sink code goes here */
             } else {
               super.sinkEvents(eventBitsToAdd);
            }
          }

      Overrides:
        `sinkEvents` in class `UIObject`
      Parameters:
        `eventBitsToAdd` - a bitfield representing the set of events to be added to this element's event set
      See Also:
        `Event`

    - #### createHandlerManager

          protected HandlerManager createHandlerManager()

      Creates the `HandlerManager` used by this Widget. You can override this method to create a custom `HandlerManager`.
      Returns:
        the `HandlerManager` you want to use

    - #### delegateEvent

          protected void delegateEvent(Widget target,
                           GwtEvent<?> event)

      Fires an event on a child widget. Used to delegate the handling of an event from one widget to another.
      Parameters:
        `event` - the event
        `target` - fire the event on the given target

    - #### doAttachChildren

          protected void doAttachChildren()

      If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call `onAttach()` for each of its child widgets.
      See Also:
        `onAttach()`

    - #### doDetachChildren

          protected void doDetachChildren()

      If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call `onDetach()` for each of its child widgets.
      See Also:
        `onDetach()`

    - #### getHandlerCount

          protected int getHandlerCount(GwtEvent.Type<?> type)

      Gets the number of handlers listening to the event type.
      Parameters:
        `type` - the event type
      Returns:
        the number of registered handlers

    - #### isOrWasAttached

          protected final boolean isOrWasAttached()

      Has this widget ever been attached?
      Returns:
        true if this widget ever been attached to the DOM, false otherwise

    - #### onAttach

          protected void onAttach()

      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 `onLoad()` method or use `addAttachHandler(com.google.gwt.event.logical.shared.AttachEvent.Handler)`.

      It is strongly recommended that you override `onLoad()` or `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.

      Throws:
        `java.lang.IllegalStateException` - if this widget is already attached
      See Also:
        `onLoad()`, `doAttachChildren()`

    - #### onDetach

          protected void onDetach()

      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 `onUnload()` method or use `addAttachHandler(com.google.gwt.event.logical.shared.AttachEvent.Handler)`.

      It is strongly recommended that you override `onUnload()` or `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.

      Throws:
        `java.lang.IllegalStateException` - if this widget is already detached
      See Also:
        `onUnload()`, `doDetachChildren()`

    - #### onLoad

          protected void onLoad()

      This method is called immediately after a widget becomes attached to the browser's document.

    - #### onUnload

          protected void onUnload()

      This method is called immediately before a widget will be detached from the browser's document.

    - #### ensureHandlers

          HandlerManager ensureHandlers()

      Ensures the existence of the handler manager.
      Returns:
        the handler manager

    - #### getHandlerManager

          HandlerManager getHandlerManager()

    - #### replaceElement

          void replaceElement(Element elem)

      Description copied from class: `UIObject`
      Replaces this object's browser element. This method exists only to support a specific use-case in Image, and should not be used by other classes.
      Overrides:
        `replaceElement` in class `UIObject`
      Parameters:
        `elem` - the object's new element

    - #### setParent

          void setParent(Widget parent)

      Sets this widget's parent. This method should only be called by `Panel` and `Composite`.
      Parameters:
        `parent` - the widget's new parent
      Throws:
        `java.lang.IllegalStateException` - if `parent` is non-null and the widget already has a parent