com.google.gwt.user.client.ui

Class Panel

java.lang.Object

com.google.gwt.user.client.ui.UIObject

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

com.google.gwt.user.client.ui.Panel

All Implemented Interfaces:

HasAttachHandlers, HasHandlers, EventListener, HasVisibility, HasWidgets, HasWidgets.ForIsWidget, IsWidget, java.lang.Iterable<Widget>

Direct Known Subclasses:

ComplexPanel, HeaderPanel, HTMLTable, SimplePanel, SplitPanel

public abstract class Panel
extends Widget
implements HasWidgets.ForIsWidget

Abstract base class for all panels, which are widgets that can contain other widgets.

Nested Class Summary

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

UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled

Nested classes/interfaces inherited from interface com.google.gwt.user.client.ui.HasWidgets

HasWidgets.ForIsWidget

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
Panel()

Method Summary

Modifier and Type	Method and Description
void	add(IsWidget child)
void	add(Widget child) Adds a child widget.
protected void	adopt(Widget child) Finalize the attachment of a Widget to this Panel.
void	clear() Removes all child widgets.
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 Widget.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 Widget.onDetach() for each of its child widgets.
protected void	orphan(Widget child) This method must be called as part of the remove method of any Panel.
boolean	remove(IsWidget child)
abstract boolean	remove(Widget child) Removes a child widget.

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

addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isAttached, isOrWasAttached, onAttach, onBrowserEvent, onDetach, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents, unsinkEvents

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

Methods inherited from interface com.google.gwt.user.client.ui.HasWidgets

iterator

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

Panel

public Panel()

Method Detail

add

public void add(Widget child)

Adds a child widget.

How to Override this Method

There are several important things that must take place in the correct order to properly add or insert a Widget to a Panel. Not all of these steps will be relevant to every Panel, but all of the steps must be considered.

1. Validate: Perform any sanity checks to ensure the Panel can accept a new Widget. Examples: checking for a valid index on insertion; checking that the Panel is not full if there is a max capacity.
2. Adjust for Reinsertion: Some Panels need to handle the case where the Widget is already a child of this Panel. Example: when performing a reinsert, the index might need to be adjusted to account for the Widget's removal. See ComplexPanel.adjustIndex(Widget, int).
3. Detach Child: Remove the Widget from its existing parent, if any. Most Panels will simply call Widget.removeFromParent() on the Widget.
4. Logical Attach: Any state variables of the Panel should be updated to reflect the addition of the new Widget. Example: the Widget is added to the Panel's WidgetCollection at the appropriate index.
5. Physical Attach: The Widget's Element must be physically attached to the Panel's Element, either directly or indirectly.
6. Adopt: Call adopt(Widget) to finalize the add as the very last step.

Specified by:

add in interface HasWidgets

Parameters:

child - the widget to be added

Throws:

java.lang.UnsupportedOperationException - if this method is not supported (most often this means that a specific overload must be called)

See Also:

HasWidgets.add(Widget)

add

public void add(IsWidget child)

Specified by:

add in interface HasWidgets.ForIsWidget

clear

public void clear()

Description copied from interface: HasWidgets

Removes all child widgets.

Specified by:

clear in interface HasWidgets

remove

public abstract boolean remove(Widget child)

Removes a child widget.

How to Override this Method

There are several important things that must take place in the correct order to properly remove a Widget from a Panel. Not all of these steps will be relevant to every Panel, but all of the steps must be considered.

1. Validate: Make sure this Panel is actually the parent of the child Widget; return false if it is not.
2. Orphan: Call orphan(Widget) first while the child Widget is still attached.
3. Physical Detach: Adjust the DOM to account for the removal of the child Widget. The Widget's Element must be physically removed from the DOM.
4. Logical Detach: Update the Panel's state variables to reflect the removal of the child Widget. Example: the Widget is removed from the Panel's WidgetCollection.

Specified by:

remove in interface HasWidgets

Parameters:

child - the widget to be removed

Returns:

true if the child was present

remove

public boolean remove(IsWidget child)

Specified by:

remove in interface HasWidgets.ForIsWidget

adopt

protected final void adopt(Widget child)

Finalize the attachment of a Widget to this Panel. This method is the last step in adding or inserting a Widget into a Panel, and should be called after physical attachment in the DOM is complete. This Panel becomes the parent of the child Widget, and the child will now fire its Widget.onAttach() event if this Panel is currently attached.

Parameters:

child - the widget to be adopted

See Also:

add(Widget)

doAttachChildren

protected void doAttachChildren()

Description copied from class: Widget

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 Widget.onAttach() for each of its child widgets.

Overrides:

doAttachChildren in class Widget

See Also:

Widget.onAttach()

doDetachChildren

protected void doDetachChildren()

Description copied from class: Widget

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 Widget.onDetach() for each of its child widgets.

Overrides:

doDetachChildren in class Widget

See Also:

Widget.onDetach()

orphan

protected final void orphan(Widget child)

This method must be called as part of the remove method of any Panel. It ensures that the Widget's parent is cleared. This method should be called after verifying that the child Widget is an existing child of the Panel, but before physically removing the child Widget from the DOM. The child will now fire its Widget.onDetach() event if this Panel is currently attached.

Calls to orphan(Widget) should be wrapped in a try/finally block to ensure that the widget is physically detached even if orphan throws an exception.

Parameters:

child - the widget to be disowned

See Also:

add(Widget)