com.google.gwt.user.client.ui

## Class DockPanel

- 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.CellPanel
          - - com.google.gwt.user.client.ui.DockPanel

- All Implemented Interfaces:
    HasAttachHandlers, HasHandlers, EventListener, HasAlignment, HasHorizontalAlignment, HasVerticalAlignment, HasVisibility, HasWidgets, HasWidgets.ForIsWidget, IndexedPanel, IndexedPanel.ForIsWidget, IsWidget, java.lang.Iterable<Widget>

      public class DockPanel
      extends CellPanel
      implements HasAlignment

  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 has limitations in standards mode that did not exist in quirks mode. The child Widgets contained within a DockPanel cannot be sized using percentages. Setting a child widget's height to `100%` will NOT cause the child to fill the available height.

  If you need to work around these limitations, use `DockLayoutPanel` instead, but understand that it is not a drop in replacement for this class. It requires standards mode, and is most easily used under a `RootLayoutPanel` (as opposed to a `RootPanel`).

  See Also:
    `DockLayoutPanel`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DockPanel.DockLayoutConstant` DockPanel layout constant, used in `add(Widget, DockPanel.DockLayoutConstant)`.
    `(package private) static class` | `DockPanel.LayoutData`

    - ### 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.HasHorizontalAlignment

      `HasHorizontalAlignment.AutoHorizontalAlignmentConstant, HasHorizontalAlignment.HorizontalAlignmentConstant`

    - ### Nested classes/interfaces inherited from interface com.google.gwt.user.client.ui.HasVerticalAlignment

      `HasVerticalAlignment.VerticalAlignmentConstant`

    - ### 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
    Modifier and Type | Field and Description
    --- | ---
    `static DockPanel.DockLayoutConstant` | `CENTER` Specifies that a widget be added at the center of the dock.
    `static DockPanel.DockLayoutConstant` | `EAST` Specifies that a widget be added at the east edge of the dock.
    `static DockPanel.DockLayoutConstant` | `LINE_END` Specifies that a widget be added at the end of the line direction for the layout.
    `static DockPanel.DockLayoutConstant` | `LINE_START` Specifies that a widget be added at the beginning of the line direction for the layout.
    `static DockPanel.DockLayoutConstant` | `NORTH` Specifies that a widget be added at the north edge of the dock.
    `static DockPanel.DockLayoutConstant` | `SOUTH` Specifies that a widget be added at the south edge of the dock.
    `static DockPanel.DockLayoutConstant` | `WEST` Specifies that a widget be added at the west edge of the dock.

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

    - ### Fields inherited from interface com.google.gwt.user.client.ui.HasHorizontalAlignment

      `ALIGN_CENTER, ALIGN_DEFAULT, ALIGN_JUSTIFY, ALIGN_LEFT, ALIGN_LOCALE_END, ALIGN_LOCALE_START, ALIGN_RIGHT`

    - ### Fields inherited from interface com.google.gwt.user.client.ui.HasVerticalAlignment

      `ALIGN_BOTTOM, ALIGN_MIDDLE, ALIGN_TOP`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DockPanel()` Creates an empty dock panel.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `add(IsWidget widget, DockPanel.DockLayoutConstant direction)` Overloaded version for IsWidget.
    `void` | `add(Widget widget, DockPanel.DockLayoutConstant direction)` Adds a widget to the specified edge of the dock.
    `HasHorizontalAlignment.HorizontalAlignmentConstant` | `getHorizontalAlignment()` Gets the horizontal alignment.
    `HasVerticalAlignment.VerticalAlignmentConstant` | `getVerticalAlignment()` Gets the vertical alignment.
    `DockPanel.DockLayoutConstant` | `getWidgetDirection(Widget w)` Gets the layout direction of the given child widget.
    `protected void` | `onEnsureDebugId(java.lang.String baseID)` `DockPanel` supports adding more than one cell in a direction, so an integer will be appended to the end of the debug id.
    `boolean` | `remove(Widget w)` Removes a child widget.
    `void` | `setCellHeight(Widget w, java.lang.String height)` Sets the height of the cell associated with the given widget, related to the panel as a whole.
    `void` | `setCellHorizontalAlignment(Widget w, HasHorizontalAlignment.HorizontalAlignmentConstant align)` Sets the horizontal alignment of the given widget within its cell.
    `void` | `setCellVerticalAlignment(Widget w, HasVerticalAlignment.VerticalAlignmentConstant align)` Sets the vertical alignment of the given widget within its cell.
    `void` | `setCellWidth(Widget w, java.lang.String width)` Sets the width of the cell associated with the given widget, related to the panel as a whole.
    `void` | `setHorizontalAlignment(HasHorizontalAlignment.HorizontalAlignmentConstant align)` Sets the default horizontal alignment to be used for widgets added to this panel.
    `void` | `setVerticalAlignment(HasVerticalAlignment.VerticalAlignmentConstant align)` Sets the default vertical alignment to be used for widgets added to this panel.

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

      `getBody, getSpacing, getTable, getWidgetTd, setBorderWidth, setCellHeight, setCellHorizontalAlignment, setCellHorizontalAlignment, setCellVerticalAlignment, setCellVerticalAlignment, setCellWidth, setSpacing`

    - ### 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, 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, onAttach, onBrowserEvent, onDetach, 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, 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`

- - ### Field Detail

    - #### CENTER

          public static final DockPanel.DockLayoutConstant CENTER

      Specifies that a widget be added at the center of the dock.

    - #### LINE_START

          public static final DockPanel.DockLayoutConstant LINE_START

      Specifies that a widget be added at the beginning of the line direction for the layout.

    - #### LINE_END

          public static final DockPanel.DockLayoutConstant LINE_END

      Specifies that a widget be added at the end of the line direction for the layout.

    - #### EAST

          public static final DockPanel.DockLayoutConstant EAST

      Specifies that a widget be added at the east edge of the dock.

    - #### NORTH

          public static final DockPanel.DockLayoutConstant NORTH

      Specifies that a widget be added at the north edge of the dock.

    - #### SOUTH

          public static final DockPanel.DockLayoutConstant SOUTH

      Specifies that a widget be added at the south edge of the dock.

    - #### WEST

          public static final DockPanel.DockLayoutConstant WEST

      Specifies that a widget be added at the west edge of the dock.

  - ### Constructor Detail

    - #### DockPanel

          public DockPanel()

      Creates an empty dock panel.

  - ### Method Detail

    - #### add

          public void add(Widget widget,
                 DockPanel.DockLayoutConstant direction)

      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
      Throws:
        `java.lang.IllegalArgumentException` - when adding to the `CENTER` and there is already a different widget there

    - #### add

          public void add(IsWidget widget,
                 DockPanel.DockLayoutConstant direction)

      Overloaded version for IsWidget.
      See Also:
        `add(Widget,DockLayoutConstant)`

    - #### getHorizontalAlignment

          public HasHorizontalAlignment.HorizontalAlignmentConstant getHorizontalAlignment()

      Description copied from interface: `HasHorizontalAlignment`
      Gets the horizontal alignment.
      Specified by:
        `getHorizontalAlignment` in interface `HasHorizontalAlignment`
      Returns:
        the current horizontal alignment ( `HasHorizontalAlignment.ALIGN_LEFT`, `HasHorizontalAlignment.ALIGN_CENTER`, `HasHorizontalAlignment.ALIGN_RIGHT`, `HasHorizontalAlignment.ALIGN_JUSTIFY`, or null).

    - #### getVerticalAlignment

          public HasVerticalAlignment.VerticalAlignmentConstant getVerticalAlignment()

      Description copied from interface: `HasVerticalAlignment`
      Gets the vertical alignment.
      Specified by:
        `getVerticalAlignment` in interface `HasVerticalAlignment`
      Returns:
        the current vertical alignment.

    - #### getWidgetDirection

          public DockPanel.DockLayoutConstant getWidgetDirection(Widget w)

      Gets the layout direction of the given child widget.
      Parameters:
        `w` - the widget to be queried
      Returns:
        the widget's layout direction, or `null` if it is not a child of this panel

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

    - #### setCellHeight

          public void setCellHeight(Widget w,
                           java.lang.String height)

      Description copied from class: `CellPanel`
      Sets the height of the cell associated with the given widget, related to the panel as a whole.
      Overrides:
        `setCellHeight` in class `CellPanel`
      Parameters:
        `w` - the widget whose cell height is to be set
        `height` - the cell's height, in CSS units

    - #### setCellHorizontalAlignment

          public void setCellHorizontalAlignment(Widget w,
                                        HasHorizontalAlignment.HorizontalAlignmentConstant align)

      Description copied from class: `CellPanel`
      Sets the horizontal alignment of the given widget within its cell.
      Overrides:
        `setCellHorizontalAlignment` in class `CellPanel`
      Parameters:
        `w` - the widget whose horizontal alignment is to be set
        `align` - the widget's horizontal alignment, as defined in `HasHorizontalAlignment`.

    - #### setCellVerticalAlignment

          public void setCellVerticalAlignment(Widget w,
                                      HasVerticalAlignment.VerticalAlignmentConstant align)

      Description copied from class: `CellPanel`
      Sets the vertical alignment of the given widget within its cell.
      Overrides:
        `setCellVerticalAlignment` in class `CellPanel`
      Parameters:
        `w` - the widget whose vertical alignment is to be set
        `align` - the widget's vertical alignment, as defined in `HasVerticalAlignment`.

    - #### setCellWidth

          public void setCellWidth(Widget w,
                          java.lang.String width)

      Description copied from class: `CellPanel`
      Sets the width of the cell associated with the given widget, related to the panel as a whole.
      Overrides:
        `setCellWidth` in class `CellPanel`
      Parameters:
        `w` - the widget whose cell width is to be set
        `width` - the cell's width, in CSS units

    - #### setHorizontalAlignment

          public void setHorizontalAlignment(HasHorizontalAlignment.HorizontalAlignmentConstant align)

      Sets the default horizontal alignment to be used for widgets added to this panel. It only applies to widgets added after this property is set.
      Specified by:
        `setHorizontalAlignment` in interface `HasHorizontalAlignment`
      Parameters:
        `align` - the horizontal alignment ( `HasHorizontalAlignment.ALIGN_LEFT`, `HasHorizontalAlignment.ALIGN_CENTER`, `HasHorizontalAlignment.ALIGN_RIGHT`, `HasHorizontalAlignment.ALIGN_JUSTIFY`, `HasHorizontalAlignment.ALIGN_LOCALE_START`, or `HasHorizontalAlignment.ALIGN_LOCALE_END`).
      See Also:
        `HasHorizontalAlignment.setHorizontalAlignment(HasHorizontalAlignment.HorizontalAlignmentConstant)`

    - #### setVerticalAlignment

          public void setVerticalAlignment(HasVerticalAlignment.VerticalAlignmentConstant align)

      Sets the default vertical alignment to be used for widgets added to this panel. It only applies to widgets added after this property is set.
      Specified by:
        `setVerticalAlignment` in interface `HasVerticalAlignment`
      Parameters:
        `align` - the vertical alignment ( `HasVerticalAlignment.ALIGN_TOP`, `HasVerticalAlignment.ALIGN_MIDDLE`, or `HasVerticalAlignment.ALIGN_BOTTOM`).
      See Also:
        `HasVerticalAlignment.setVerticalAlignment(HasVerticalAlignment.VerticalAlignmentConstant)`

    - #### onEnsureDebugId

          protected void onEnsureDebugId(java.lang.String baseID)

      `DockPanel` supports adding more than one cell in a direction, so an integer will be appended to the end of the debug id. For example, the first north cell is labeled "north1", the second is "north2", and the third is "north3". This widget recreates its structure every time a `Widget` is added, so you must call this method after adding a new `Widget` or all debug IDs will be lost.

      Affected Elements:

      - -center = the center cell.
      - -north# = the northern cell.
      - -south# = the southern cell.
      - -east# = the eastern cell.
      - -west# = the western cell.
      Overrides:
        `onEnsureDebugId` in class `UIObject`
      Parameters:
        `baseID` - the base ID used by the main element
      See Also:
        `UIObject.onEnsureDebugId(String)`