Google Web Toolkit
Search Google Code:

# Class ComplexPanel

public class ComplexPanel
extends Panel
implements IndexedPanel
// Superclass of `AbsolutePanel`, `CellPanel`, `DeckPanel`, `FlowPanel`, `HTMLPanel`, `StackPanel`
Abstract base class for panels that can contain multiple child widgets.

## Methods

add(Widget, Element) | Adds a new child widget to the panel, attaching its Element to the specified container Element.
adjustIndex(Widget, int) | Adjusts beforeIndex to account for the possibility that the given widget is already a child of this panel.
checkIndexBoundsForAccess(int) | Checks that `index` is in the range [0, getWidgetCount()), which is the valid range on accessible indexes.
checkIndexBoundsForInsertion(int) | Checks that `index` is in the range [0, getWidgetCount()], which is the valid range for indexes on an insertion.
getChildren() | Gets the list of children contained in this panel.
getWidget(int) | Gets the child widget at the specified index.
getWidgetCount() | Gets the number of child widgets in this panel.
getWidgetIndex(Widget) | Gets the index of the specified child widget.
insert(Widget, Element, int) | This method was used by subclasses to insert a new child Widget.
insert(Widget, Element, int, boolean) | Insert a new child Widget into this Panel at a specified index, attaching its Element to the specified container Element.
iterator() | Gets an iterator for the contained widgets.
remove(int) | Removes the widget at the specified index.
remove(Widget) | Removes a child widget.

## Method Detail

### add

protected void add(Widget child, Element container)
Adds a new child widget to the panel, attaching its Element to the specified container Element.

#### Parameters

child
  the child widget to be added
container
  the element within which the child will be contained

### adjustIndex

protected int adjustIndex(Widget child, int beforeIndex)
Adjusts beforeIndex to account for the possibility that the given widget is already a child of this panel.

#### Parameters

child
  the widget that might be an existing child
beforeIndex
  the index at which it will be added to this panel

#### Return Value

the modified index

### checkIndexBoundsForAccess

protected void checkIndexBoundsForAccess(int index)
Checks that `index` is in the range [0, getWidgetCount()), which is the valid range on accessible indexes.

#### Parameters

index
  the index being accessed

### checkIndexBoundsForInsertion

protected void checkIndexBoundsForInsertion(int index)
Checks that `index` is in the range [0, getWidgetCount()], which is the valid range for indexes on an insertion.

#### Parameters

index
  the index where insertion will occur

### getChildren

protected WidgetCollection getChildren()
Gets the list of children contained in this panel.

#### Return Value

a collection of child widgets

### getWidget

public Widget getWidget(int index)
Gets the child widget at the specified index.

#### Parameters

index
  the child widget's index

#### Return Value

the child widget

### getWidgetCount

public int getWidgetCount()
Gets the number of child widgets in this panel.

#### Return Value

the number of children

### getWidgetIndex

public int getWidgetIndex(Widget child)
Gets the index of the specified child widget.

#### Parameters

child
  the widget to be found

#### Return Value

the widget's index, or `-1` if it is not a child of this panel

### insert

protected void insert(Widget child, Element container, int beforeIndex)
This method was used by subclasses to insert a new child Widget. It is now deprecated because it was ambiguous whether the `child` should be appended to `container` element versus inserted into `container` at `beforeIndex`. Use insert(Widget, Element, int, boolean), which clarifies this ambiguity.

#### Parameters

child
container
beforeIndex

### insert

protected void insert(Widget child, Element container, int beforeIndex, boolean domInsert)
Insert a new child Widget into this Panel at a specified index, attaching its Element to the specified container Element. The child Element will either be attached to the container at the same index, or simply appended to the container, depending on the value of `domInsert`.

#### Parameters

child
  the child Widget to be added
container
  the Element within which `child` will be contained
beforeIndex
  the index before which `child` will be inserted
domInsert
  if `true`, insert `child` into `container` at `beforeIndex`; otherwise append `child` to the end of `container`.

### iterator

public Iterator iterator()
Gets an iterator for the contained widgets. This iterator is required to implement Iterator.remove().

### remove

public boolean remove(int index)
Removes the widget at the specified index.

#### Parameters

index
  the index of the widget to be removed

#### Return Value

`false` if the widget is not present

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

#### Parameters

child
  the widget to be removed

#### Return Value

`true` if the child was present