com.google.gwt.user.client.ui

## Class LayoutPanel

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

- All Implemented Interfaces:
    HasAttachHandlers, HasHandlers, EventListener, AnimatedLayout, HasVisibility, HasWidgets, HasWidgets.ForIsWidget, IndexedPanel, IndexedPanel.ForIsWidget, IsWidget, 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 vertical). 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`

    - ### 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.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
    `LayoutPanel()` Creates an empty layout panel.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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, Layout.AnimationCallback callback)` Layout children, animating over the specified period of time.
    `void` | `forceLayout()` Layout children immediately.
    `(package private) Layout` | `getLayout()` Gets the `Layout` instance associated with this widget.
    `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` | `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` | `setWidgetBottomHeight(IsWidget child, double bottom, Style.Unit bottomUnit, double height, Style.Unit heightUnit)` Overloaded version for IsWidget.
    `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, Layout.Alignment position)` Sets the child widget's horizontal position within its layer.
    `void` | `setWidgetLeftRight(IsWidget child, double left, Style.Unit leftUnit, double right, Style.Unit rightUnit)` Overloaded version for IsWidget.
    `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(IsWidget child, double left, Style.Unit leftUnit, double width, Style.Unit widthUnit)` Overloaded version for IsWidget.
    `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(IsWidget child, double right, Style.Unit rightUnit, double width, Style.Unit widthUnit)` Overloaded version for IsWidget.
    `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(IsWidget child, double top, Style.Unit topUnit, double bottom, Style.Unit bottomUnit)` Overloaded version for IsWidget.
    `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(IsWidget child, double top, Style.Unit topUnit, double height, Style.Unit heightUnit)` Overloaded version for IsWidget.
    `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, Layout.Alignment position)` Sets the child widget's vertical position within its layer.
    `void` | `setWidgetVisible(Widget child, boolean visible)` Shows or hides the given widget and its layer.

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

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

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

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

    - ### 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, onBrowserEvent, onLoad, onUnload, removeFromParent, replaceElement, setLayoutData, setParent, 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, 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`

- - ### 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, Style.Unit, double, Style.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,
                     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

    - #### 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, Style.Unit, double, Style.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` -

    - #### setWidgetBottomHeight

          public void setWidgetBottomHeight(IsWidget child,
                                   double bottom,
                                   Style.Unit bottomUnit,
                                   double height,
                                   Style.Unit heightUnit)

      Overloaded version for IsWidget.
      See Also:
        `setWidgetBottomHeight(Widget,double, Style.Unit, double, Style.Unit)`

    - #### setWidgetHorizontalPosition

          public void setWidgetHorizontalPosition(Widget child,
                                         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` -

    - #### setWidgetLeftRight

          public void setWidgetLeftRight(IsWidget child,
                                double left,
                                Style.Unit leftUnit,
                                double right,
                                Style.Unit rightUnit)

      Overloaded version for IsWidget.
      See Also:
        `setWidgetLeftRight(Widget,double, Style.Unit, double, Style.Unit)`

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

    - #### setWidgetLeftWidth

          public void setWidgetLeftWidth(IsWidget child,
                                double left,
                                Style.Unit leftUnit,
                                double width,
                                Style.Unit widthUnit)

      Overloaded version for IsWidget.
      See Also:
        `setWidgetLeftWidth(Widget,double, Style.Unit, double, Style.Unit)`

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

    - #### setWidgetRightWidth

          public void setWidgetRightWidth(IsWidget child,
                                 double right,
                                 Style.Unit rightUnit,
                                 double width,
                                 Style.Unit widthUnit)

      Overloaded version for IsWidget.
      See Also:
        `setWidgetRightWidth(Widget,double, Style.Unit, double, Style.Unit)`

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

    - #### setWidgetTopBottom

          public void setWidgetTopBottom(IsWidget child,
                                double top,
                                Style.Unit topUnit,
                                double bottom,
                                Style.Unit bottomUnit)

      Overloaded version for IsWidget.
      See Also:
        `setWidgetTopBottom(Widget,double, Style.Unit, double, Style.Unit)`

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

    - #### setWidgetTopHeight

          public void setWidgetTopHeight(IsWidget child,
                                double top,
                                Style.Unit topUnit,
                                double height,
                                Style.Unit heightUnit)

      Overloaded version for IsWidget.
      See Also:
        `setWidgetTopHeight(Widget,double, Style.Unit, double, Style.Unit)`

    - #### setWidgetVerticalPosition

          public void setWidgetVerticalPosition(Widget child,
                                       Layout.Alignment position)

      Sets the child widget's vertical position within its layer.
      Parameters:
        `child` -
        `position` -

    - #### setWidgetVisible

          public void setWidgetVisible(Widget child,
                              boolean visible)

      Shows or hides the given widget and its layer. This method explicitly calls `UIObject.setVisible(boolean)` on the child widget and ensures that its associated layer is shown/hidden.
      Parameters:
        `child` -
        `visible` -

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

    - #### getLayout

          Layout getLayout()

      Gets the `Layout` instance associated with this widget. This is made package-protected for use by `RootLayoutPanel`.
      Returns:
        this widget's layout instance