Overview  Package   Class  Use  Deprecated  Help 
GWT 2.7.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.google.gwt.user.client.ui
Class Widget

java.lang.Object
  extended by com.google.gwt.user.client.ui.UIObject
      extended by 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, 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
(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
Widget()
           
 
Method Summary
 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.
 void unsinkEvents(int eventBitsToRemove)
          Removes a set of events from this object's event list.
 
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
 
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

unsinkEvents

public void unsinkEvents(int eventBitsToRemove)
Description copied from class: UIObject
Removes a set of events from this object's event list.

Overrides:
unsinkEvents in class UIObject
Parameters:
eventBitsToRemove - a bitfield representing the set of events to be removed from this element's event set
See Also:
UIObject.sinkEvents(int), 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
Overview  Package   Class  Use  Deprecated  Help 
GWT 2.7.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD