com.google.gwt.user.client.ui

Class DockLayoutPanel

java.lang.Object

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

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

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

com.google.gwt.user.client.ui.ComplexPanel

com.google.gwt.user.client.ui.DockLayoutPanel

All Implemented Interfaces:

HasAttachHandlers, HasHandlers, EventListener, AnimatedLayout, HasVisibility, HasWidgets, HasWidgets.ForIsWidget, IndexedPanel, IndexedPanel.ForIsWidget, IsWidget, ProvidesResize, RequiresResize, Iterable<Widget>

Direct Known Subclasses:

SplitLayoutPanel

public class DockLayoutPanel
extends ComplexPanel
implements AnimatedLayout, RequiresResize, ProvidesResize

A panel that lays its child widgets out "docked" at its outer edges, and allows its last widget to take up the remaining space in its center.

This widget will only work in standards mode, which requires that the HTML page in which it is run have an explicit <!DOCTYPE> declaration.

Example

Use in UiBinder Templates

DockLayoutPanel elements in UiBinder templates lay out their children in elements tagged with the cardinal directions, and center:

<g:center>

<g:north>

<g:south>

<g:west>

<g:east>

Each child can hold only widget, and there can be only one <g:center>. However, there can be any number of the directional children.

(Note that the tags of the child elements are not capitalized. This is meant to signal that they are not runtime objects, and so cannot have a ui:field attribute.)

For example:

 <g:DockLayoutPanel unit='EM'>
   <g:north size='5'>
     <g:Label>Top</g:Label>
   </g:north>
   <g:center>
     <g:Label>Body</g:Label>
   </g:center>
   <g:west size='192'>
     <g:HTML>
       <ul>
         <li>Sidebar</li>
         <li>Sidebar</li>
         <li>Sidebar</li>
       </ul>
     </g:HTML>
   </g:west>
 </g:DockLayoutPanel>
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DockLayoutPanel.Direction Used in addEast(Widget, double) et al to specify the direction in which a child widget will be added.
protected static class	DockLayoutPanel.LayoutData Layout data associated with each widget.

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.IndexedPanel

IndexedPanel.ForIsWidget

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.UIObject

DEBUG_ID_PREFIX

Constructor Summary

Constructors

Constructor and Description
DockLayoutPanel(Style.Unit unit) Creates an empty dock panel.

Method Summary

Methods

Modifier and Type	Method and Description
void	add(Widget widget) Adds a widget at the center of the dock.
void	addEast(IsWidget widget, double size) Overloaded version for IsWidget.
void	addEast(Widget widget, double size) Adds a widget to the east edge of the dock.
void	addLineEnd(Widget widget, double size) Adds a widget to the end of the line.
void	addLineStart(Widget widget, double size) Adds a widget to the start of the line.
void	addNorth(IsWidget widget, double size) Overloaded version for IsWidget.
void	addNorth(Widget widget, double size) Adds a widget to the north edge of the dock.
void	addSouth(IsWidget widget, double size) Overloaded version for IsWidget.
void	addSouth(Widget widget, double size) Adds a widget to the south edge of the dock.
void	addWest(IsWidget widget, double size) Overloaded version for IsWidget.
void	addWest(Widget widget, double size) Adds a widget to the west edge of the dock.
void	animate(int duration) Layout children, animating over the specified period of time.
void	animate(int duration, Layout.AnimationCallback callback) Layout children, animating over the specified period of time.
void	forceLayout() Layout children immediately.
protected Widget	getCenter()
protected double	getCenterHeight()
protected double	getCenterWidth()
protected DockLayoutPanel.Direction	getResolvedDirection(DockLayoutPanel.Direction direction) Resolve the specified direction based on the current locale.
protected Style.Unit	getUnit()
Element	getWidgetContainerElement(Widget child) Gets the container element wrapping the given child widget.
DockLayoutPanel.Direction	getWidgetDirection(Widget child) Gets the layout direction of the given child widget.
Double	getWidgetSize(Widget child) Gets the layout size of the given child widget.
protected void	insert(Widget widget, DockLayoutPanel.Direction direction, double size, Widget before) Adds a widget to the specified edge of the dock.
void	insertEast(Widget widget, double size, Widget before) Adds a widget to the east edge of the dock, inserting it before an existing widget.
void	insertLineEnd(Widget widget, double size, Widget before) Adds a widget to the start of the line, inserting it before an existing widget.
void	insertLineStart(Widget widget, double size, Widget before) Adds a widget to the end of the line, inserting it before an existing widget.
void	insertNorth(Widget widget, double size, Widget before) Adds a widget to the north edge of the dock, inserting it before an existing widget.
void	insertSouth(Widget widget, double size, Widget before) Adds a widget to the south edge of the dock, inserting it before an existing widget.
void	insertWest(Widget widget, double size, Widget before) Adds a widget to the west edge of the dock, inserting it before an existing widget.
protected void	onAttach() This method is called when a widget is attached to the browser's document.
protected void	onDetach() This method is called when a widget is detached from the browser's document.
void	onResize() This method must be called whenever the implementor's size has been modified.
boolean	remove(Widget w) Removes a child widget.
void	setWidgetHidden(Widget widget, boolean hidden) Sets whether or not the given widget should be hidden.
void	setWidgetSize(Widget widget, double size) Updates the size of the widget passed in as long as it is not the center widget and updates the layout of the dock.

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

add, add, adjustIndex, checkIndexBoundsForAccess, checkIndexBoundsForInsertion, getChildren, getWidget, getWidgetCount, getWidgetIndex, getWidgetIndex, insert, insert, iterator, remove

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

add, adopt, clear, doAttachChildren, doDetachChildren, orphan, remove

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

addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, fireEvent, getHandlerCount, getLayoutData, getParent, isAttached, isOrWasAttached, onBrowserEvent, onLoad, onUnload, removeFromParent, setLayoutData, 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

equals, finalize, getClass, hashCode

Constructor Detail

DockLayoutPanel

public DockLayoutPanel(Style.Unit unit)

Creates an empty dock panel.

Parameters:

unit - the unit to be used for layout

Method Detail

add

public void add(Widget widget)

Adds a widget at the center of the dock. No further widgets may be added after this one.

Specified by:

add in interface HasWidgets

Overrides:

add in class Panel

Parameters:

widget - the widget to be added

See Also:

HasWidgets.add(Widget)

addEast

public void addEast(Widget widget,
           double size)

Adds a widget to the east edge of the dock.

Parameters:

widget - the widget to be added

size - the child widget's size

addEast

public void addEast(IsWidget widget,
           double size)

Overloaded version for IsWidget.

See Also:

addEast(Widget,double)

addLineEnd

public void addLineEnd(Widget widget,
              double size)

Adds a widget to the end of the line. In LTR mode, the widget is added to the east. In RTL mode, the widget is added to the west.

Parameters:

widget - the widget to be added

size - the child widget's size

addLineStart

public void addLineStart(Widget widget,
                double size)

Adds a widget to the start of the line. In LTR mode, the widget is added to the west. In RTL mode, the widget is added to the east.

Parameters:

widget - the widget to be added

size - the child widget's size

addNorth

public void addNorth(Widget widget,
            double size)

Adds a widget to the north edge of the dock.

Parameters:

widget - the widget to be added

size - the child widget's size

addNorth

public void addNorth(IsWidget widget,
            double size)

Overloaded version for IsWidget.

See Also:

addNorth(Widget,double)

addSouth

public void addSouth(Widget widget,
            double size)

Adds a widget to the south edge of the dock.

Parameters:

widget - the widget to be added

size - the child widget's size

addSouth

public void addSouth(IsWidget widget,
            double size)

Overloaded version for IsWidget.

See Also:

addSouth(Widget,double)

addWest

public void addWest(Widget widget,
           double size)

Adds a widget to the west edge of the dock.

Parameters:

widget - the widget to be added

size - the child widget's size

addWest

public void addWest(IsWidget widget,
           double size)

Overloaded version for IsWidget.

See Also:

addWest(Widget,double)

animate

public void animate(int duration)

Description copied from interface: AnimatedLayout

Layout children, animating over the specified period of time.

Specified by:

animate in interface AnimatedLayout

Parameters:

duration - the animation duration, in milliseconds

animate

public void animate(int duration,
           Layout.AnimationCallback callback)

Description copied from interface: AnimatedLayout

Layout children, animating over the specified period of time.

This method provides a callback that will be informed of animation updates. This can be used to create more complex animation effects.

Specified by:

animate in interface AnimatedLayout

Parameters:

duration - the animation duration, in milliseconds

callback - the animation callback

forceLayout

public void forceLayout()

Description copied from interface: AnimatedLayout

Layout children immediately.

This is not normally necessary, unless you want to update child widgets' positions explicitly to create a starting point for a subsequent call to AnimatedLayout.animate(int).

Specified by:

forceLayout in interface AnimatedLayout

See Also:

AnimatedLayout.animate(int), AnimatedLayout.animate(int, Layout.AnimationCallback)

getWidgetContainerElement

public Element getWidgetContainerElement(Widget child)

Gets the container element wrapping the given child widget.

Parameters:

child -

Returns:

the widget's container element

getWidgetDirection

public DockLayoutPanel.Direction getWidgetDirection(Widget child)

Gets the layout direction of the given child widget.

Parameters:

child - the widget to be queried

Returns:

the widget's layout direction, or null if it is not a child of this panel

Throws:

AssertionError - if the widget is not a child and assertions are enabled

getWidgetSize

public Double getWidgetSize(Widget child)

Gets the layout size of the given child widget.

Parameters:

child - the widget to be queried

Returns:

the widget's layout size, or null if it is not a child of this panel

Throws:

AssertionError - if the widget is not a child and assertions are enabled

insertEast

public void insertEast(Widget widget,
              double size,
              Widget before)

Adds a widget to the east edge of the dock, inserting it before an existing widget.

Parameters:

widget - the widget to be added

size - the child widget's size

before - the widget before which to insert the new child, or null to append

insertLineEnd

public void insertLineEnd(Widget widget,
                 double size,
                 Widget before)

Adds a widget to the start of the line, inserting it before an existing widget. In LTR mode, the widget is added to the east. In RTL mode, the widget is added to the west.

Parameters:

widget - the widget to be added

size - the child widget's size

before - the widget before which to insert the new child, or null to append

insertLineStart

public void insertLineStart(Widget widget,
                   double size,
                   Widget before)

Adds a widget to the end of the line, inserting it before an existing widget. In LTR mode, the widget is added to the west. In RTL mode, the widget is added to the east.

Parameters:

widget - the widget to be added

size - the child widget's size

before - the widget before which to insert the new child, or null to append

insertNorth

public void insertNorth(Widget widget,
               double size,
               Widget before)

Adds a widget to the north edge of the dock, inserting it before an existing widget.

Parameters:

widget - the widget to be added

size - the child widget's size

before - the widget before which to insert the new child, or null to append

insertSouth

public void insertSouth(Widget widget,
               double size,
               Widget before)

Adds a widget to the south edge of the dock, inserting it before an existing widget.

Parameters:

widget - the widget to be added

size - the child widget's size

before - the widget before which to insert the new child, or null to append

insertWest

public void insertWest(Widget widget,
              double size,
              Widget before)

Adds a widget to the west edge of the dock, inserting it before an existing widget.

Parameters:

widget - the widget to be added

size - the child widget's size

before - the widget before which to insert the new child, or null to append

onResize

public void onResize()

Description copied from interface: RequiresResize

This method must be called whenever the implementor's size has been modified.

Specified by:

onResize in interface RequiresResize

remove

public boolean remove(Widget w)

Description copied from class: Panel

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 Panel.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

Overrides:

remove in class ComplexPanel

Parameters:

w - the widget to be removed

Returns:

true if the child was present

setWidgetHidden

public void setWidgetHidden(Widget widget,
                   boolean hidden)

Sets whether or not the given widget should be hidden.

Parameters:

widget - the widget to hide or display

hidden - true to hide the widget, false to display it

setWidgetSize

public void setWidgetSize(Widget widget,
                 double size)

Updates the size of the widget passed in as long as it is not the center widget and updates the layout of the dock.

Parameters:

widget - the widget that needs to update its size

size - the size to update the widget to

getCenter

protected Widget getCenter()

getCenterHeight

protected double getCenterHeight()

getCenterWidth

protected double getCenterWidth()

getResolvedDirection

protected DockLayoutPanel.Direction getResolvedDirection(DockLayoutPanel.Direction direction)

Resolve the specified direction based on the current locale. If the direction is DockLayoutPanel.Direction.LINE_START or DockLayoutPanel.Direction.LINE_END, the return value will be one of DockLayoutPanel.Direction.EAST or DockLayoutPanel.Direction.WEST depending on the RTL mode of the locale. For all other directions, the specified value is returned.

Parameters:

direction - the specified direction

Returns:

the locale

getUnit

protected Style.Unit getUnit()

insert

protected void insert(Widget widget,
          DockLayoutPanel.Direction direction,
          double size,
          Widget before)

Adds a widget to the specified edge of the dock. If the widget is already a child of this panel, this method behaves as though remove(Widget) had already been called.

Parameters:

widget - the widget to be added

direction - the widget's direction in the dock

before - the widget before which to insert the new child, or null to append

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