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

java.lang.Object
  extended by com.google.gwt.user.client.ui.UIObject
      extended by com.google.gwt.user.client.ui.Widget
          extended by com.google.gwt.user.client.ui.Panel
              extended by com.google.gwt.user.client.ui.ComplexPanel
                  extended by com.google.gwt.user.client.ui.LayoutPanel
All Implemented Interfaces:
HasHandlers, EventListener, AnimatedLayout, HasWidgets, IndexedPanel, ProvidesResize, RequiresResize, java.lang.Iterable<Widget>
Direct Known Subclasses:
RootLayoutPanel

public class LayoutPanel
extends ComplexPanel
implements AnimatedLayout, RequiresResize, ProvidesResize

A panel that lays its children out in arbitrary layers using the Layout class.

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

public class LayoutPanelExample implements EntryPoint {

  public void onModuleLoad() {
    // Attach two child widgets to a LayoutPanel, laying them out horizontally,
    // splitting at 50%.
    Widget childOne = new HTML("left"), childTwo = new HTML("right");
    LayoutPanel p = new LayoutPanel();
    p.add(childOne);
    p.add(childTwo);

    p.setWidgetLeftWidth(childOne, 0, PCT, 50, PCT);
    p.setWidgetRightWidth(childTwo, 0, PCT, 50, PCT);

    // Attach the LayoutPanel to the RootLayoutPanel. The latter will listen for
    // resize events on the window to ensure that its children are informed of
    // possible size changes.
    RootLayoutPanel rp = RootLayoutPanel.get();
    rp.add(p);
  }
}

Use in UiBinder Templates

LayoutPanel elements in UiBinder templates lay out their children with arbitrary constraints, using <g:layer> elements. Each layer may have any of the following constraint attributes specified as CSS length attributes: left, top, right, bottom, width , and height.

Precisely zero or two constraints are required for each axis (horizontal and vertial). Specifying no constraints implies that the child should fill that axis completely.

The valid sets of horizontal constraints are:

(none)
Fill the parent's horizontal axis
left, width
Fixed width, positioned from parent's left edge
right, width
Fixed width, positioned from parent's right edge
left, right
Width implied by fixed distance from parent's left and right edges

The valid sets of vertical constraints are:

(none)
Fill the parent's vertical axis
top, height
Fixed height, positioned from parent's top edge
bottom, height
Fixed height, positioned from parent's bottom edge
top, bottom
Height implied by fixed distance from parent's top and bottom edges

The values of constraint attributes can be any valid CSS length, such as 1px, 3em, or 0 (zero lengths require no units).

For example:

 <g:LayoutPanel>
   <!-- No constraints causes the layer to fill the parent -->
   <g:layer>
     <g:Label>Lorem ipsum...</g:Label>
   </g:layer>
   <!-- Position horizontally 25% from each edge;
        Vertically 4px from the top and 10em tall. -->
   <g:layer left='25%' right='25%' top='4px' height='10em'>
     <g:Label>Header</g:Label>
   </g:layer>
 </g:LayoutPanel>
 


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.UIObject
DEBUG_ID_PREFIX
 
Constructor Summary
LayoutPanel()
          Creates an empty layout panel.
 
Method Summary
 void add(Widget widget)
          Adds a widget to this panel.
 void animate(int duration)
          Layout children, animating over the specified period of time.
 void animate(int duration, com.google.gwt.layout.client.Layout.AnimationCallback callback)
          Layout children, animating over the specified period of time.
 void forceLayout()
          Layout children immediately.
 Element getWidgetContainerElement(Widget child)
          Gets the container element wrapping the given child widget.
 void insert(Widget widget, int beforeIndex)
          Inserts a widget before the specified index.
protected  void onLoad()
          A Panel's onLoad method will be called after all of its children are attached.
 void onResize()
          This method must be called whenever the implementor's size has been modified.
protected  void onUnload()
          A Panel's onUnload method will be called before its children become detached themselves.
 boolean remove(Widget w)
          Removes a child widget.
 void setWidgetBottomHeight(Widget child, double bottom, Style.Unit bottomUnit, double height, Style.Unit heightUnit)
          Sets the child widget's bottom and height values.
 void setWidgetHorizontalPosition(Widget child, com.google.gwt.layout.client.Layout.Alignment position)
          Sets the child widget's horizontal position within its layer.
 void setWidgetLeftRight(Widget child, double left, Style.Unit leftUnit, double right, Style.Unit rightUnit)
          Sets the child widget's left and right values.
 void setWidgetLeftWidth(Widget child, double left, Style.Unit leftUnit, double width, Style.Unit widthUnit)
          Sets the child widget's left and width values.
 void setWidgetRightWidth(Widget child, double right, Style.Unit rightUnit, double width, Style.Unit widthUnit)
          Sets the child widget's right and width values.
 void setWidgetTopBottom(Widget child, double top, Style.Unit topUnit, double bottom, Style.Unit bottomUnit)
          Sets the child widget's top and bottom values.
 void setWidgetTopHeight(Widget child, double top, Style.Unit topUnit, double height, Style.Unit heightUnit)
          Sets the child widget's top and height values.
 void setWidgetVerticalPosition(Widget child, com.google.gwt.layout.client.Layout.Alignment position)
          Sets the child widget's vertical position within its layer.
 
Methods inherited from class com.google.gwt.user.client.ui.ComplexPanel
add, adjustIndex, checkIndexBoundsForAccess, checkIndexBoundsForInsertion, getChildren, getWidget, getWidgetCount, getWidgetIndex, insert, insert, iterator, remove
 
Methods inherited from class com.google.gwt.user.client.ui.Panel
adopt, adopt, clear, disown, doAttachChildren, doDetachChildren, orphan
 
Methods inherited from class com.google.gwt.user.client.ui.Widget
addDomHandler, addHandler, delegateEvent, fireEvent, getHandlerCount, getLayoutData, getParent, isAttached, isOrWasAttached, onAttach, onBrowserEvent, onDetach, removeFromParent, setLayoutData, 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, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setTitle, setVisible, setVisible, setWidth, toString, unsinkEvents
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

LayoutPanel

public LayoutPanel()
Creates an empty layout panel.

Method Detail

add

public void add(Widget widget)
Adds a widget to this panel.

By default, each child will fill the panel. To build more interesting layouts, set child widgets' layout constraints using #setWidgetLeftRight(Widget, double, Unit, double, Unit) and related methods.

Specified by:
add in interface HasWidgets
Overrides:
add in class Panel
Parameters:
widget - the widget to be added
See Also:
HasWidgets.add(Widget)

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,
                    com.google.gwt.layout.client.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), #animate(int, AnimationCallback)

getWidgetContainerElement

public Element getWidgetContainerElement(Widget child)
Gets the container element wrapping the given child widget.

Parameters:
child -
Returns:
the widget's container element

insert

public void insert(Widget widget,
                   int beforeIndex)
Inserts a widget before the specified index.

By default, each child will fill the panel. To build more interesting layouts, set child widgets' layout constraints using #setWidgetLeftRight(Widget, double, Unit, double, Unit) and related methods.

Inserting a widget in this way has no effect on the DOM structure, but can be useful for other panels that wrap LayoutPanel to maintain insertion order.

Parameters:
widget - the widget to be inserted
beforeIndex - the index before which it will be inserted
Throws:
java.lang.IndexOutOfBoundsException - if beforeIndex is out of range

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

setWidgetBottomHeight

public void setWidgetBottomHeight(Widget child,
                                  double bottom,
                                  Style.Unit bottomUnit,
                                  double height,
                                  Style.Unit heightUnit)
Sets the child widget's bottom and height values.

Parameters:
child -
bottom -
bottomUnit -
height -
heightUnit -

setWidgetHorizontalPosition

public void setWidgetHorizontalPosition(Widget child,
                                        com.google.gwt.layout.client.Layout.Alignment position)
Sets the child widget's horizontal position within its layer.

Parameters:
child -
position -

setWidgetLeftRight

public void setWidgetLeftRight(Widget child,
                               double left,
                               Style.Unit leftUnit,
                               double right,
                               Style.Unit rightUnit)
Sets the child widget's left and right values.

Parameters:
child -
left -
leftUnit -
right -
rightUnit -

setWidgetLeftWidth

public void setWidgetLeftWidth(Widget child,
                               double left,
                               Style.Unit leftUnit,
                               double width,
                               Style.Unit widthUnit)
Sets the child widget's left and width values.

Parameters:
child -
left -
leftUnit -
width -
widthUnit -

setWidgetRightWidth

public void setWidgetRightWidth(Widget child,
                                double right,
                                Style.Unit rightUnit,
                                double width,
                                Style.Unit widthUnit)
Sets the child widget's right and width values.

Parameters:
child -
right -
rightUnit -
width -
widthUnit -

setWidgetTopBottom

public void setWidgetTopBottom(Widget child,
                               double top,
                               Style.Unit topUnit,
                               double bottom,
                               Style.Unit bottomUnit)
Sets the child widget's top and bottom values.

Parameters:
child -
top -
topUnit -
bottom -
bottomUnit -

setWidgetTopHeight

public void setWidgetTopHeight(Widget child,
                               double top,
                               Style.Unit topUnit,
                               double height,
                               Style.Unit heightUnit)
Sets the child widget's top and height values.

Parameters:
child -
top -
topUnit -
height -
heightUnit -

setWidgetVerticalPosition

public void setWidgetVerticalPosition(Widget child,
                                      com.google.gwt.layout.client.Layout.Alignment position)
Sets the child widget's vertical position within its layer.

Parameters:
child -
position -

onLoad

protected void onLoad()
Description copied from class: Panel
A Panel's onLoad method will be called after all of its children are attached.

Overrides:
onLoad in class Panel
See Also:
Widget.onLoad()

onUnload

protected void onUnload()
Description copied from class: Panel
A Panel's onUnload method will be called before its children become detached themselves.

Overrides:
onUnload in class Panel
See Also:
Widget.onLoad()