public class Layout
extends java.lang.Object
This class is typically used by higher-level widgets to implement layout on their behalf. It is intended to wrap an element (usually a <div>), and lay its children out in a predictable fashion, automatically accounting for changes to the parent's size, and for all elements' margins, borders, and padding.
To use this class, create a container element (again, usually a <div>)
and pass it to Layout(Element). Rather than attaching child elements
directly to the element managed by this Layout, use the
attachChild(Element) method. This will attach the child
element and return a Layout.Layer object which is used to manage the
child.
A separate Layout.Layer instance is associated with each child
element. There is a set of methods available on this class to manipulate the
child element's position and size. In order for changes to a layer to take
effect, you must finally call one of layout() or
layout(int). This allows many changes to different layers to be
applied efficiently, and to be animated.
On most browsers, this is implemented using absolute positioning. It also contains extra logic to make IE6 work properly.
public class LayoutExample implements EntryPoint {
public void onModuleLoad() {
// The following is a very simple example, which constructs a layout around
// a parent element, and attaches two child elements that split their
// parent's space vertically. It then goes on to animate from the first
// state to a horizontal stacking that uses EM units rather than
// percentages.
Document doc = Document.get();
Element parent = doc.createDivElement();
doc.getBody().appendChild(parent);
Layout layout = new Layout(parent);
layout.onAttach();
Element topChild = doc.createDivElement(), bottomChild = doc
.createDivElement();
Layer topLayer = layout.attachChild(topChild);
Layer bottomLayer = layout.attachChild(bottomChild);
// Stack the two children vertically, meeting at 50%.
topLayer.setLeftRight(0, PX, 0, PX);
bottomLayer.setLeftRight(0, PX, 0, PX);
topLayer.setTopHeight(0, PCT, 50, PCT);
bottomLayer.setBottomHeight(0, PCT, 50, PCT);
layout.layout();
// Update the two children to stack horizontally, meeting at 10em.
// Also have them animate for 500ms.
topLayer.setTopBottom(0, PX, 0, PX);
bottomLayer.setTopBottom(0, PX, 0, PX);
topLayer.setLeftWidth(0, EM, 10, EM);
bottomLayer.setLeftRight(10, EM, 0, EM);
layout.layout(500);
}
}
NOTE: This class will only work in standards mode, which requires that the HTML page in which it is run have an explicit <!DOCTYPE> declaration.
NOTE: This class is still very new, and its interface may change without warning. Use at your own risk.
| Modifier and Type | Class and Description |
|---|---|
static class |
Layout.Alignment
Used to specify the alignment of child elements within a layer.
|
static interface |
Layout.AnimationCallback
Callback interface used by
layout(int, AnimationCallback)
to provide updates on animation progress. |
class |
Layout.Layer
This class is used to set the position and size of child elements.
|
| Constructor and Description |
|---|
Layout(Element parent)
Constructs a new layout associated with the given parent element.
|
| Modifier and Type | Method and Description |
|---|---|
void |
assertIsChild(Element elem)
Asserts that the given child element is managed by this layout.
|
Layout.Layer |
attachChild(Element child)
Attaches a child element to this layout.
|
Layout.Layer |
attachChild(Element child,
Element before)
Attaches a child element to this layout.
|
Layout.Layer |
attachChild(Element child,
Element before,
java.lang.Object userObject)
Attaches a child element to this layout.
|
Layout.Layer |
attachChild(Element child,
java.lang.Object userObject)
Attaches a child element to this layout.
|
void |
fillParent()
Causes the parent element to fill its own parent.
|
double |
getUnitSize(Style.Unit unit,
boolean vertical)
Returns the size of one unit, in pixels, in the context of this layout.
|
void |
layout()
Updates this layout's children immediately.
|
void |
layout(int duration)
Updates the layout by animating it over time.
|
void |
layout(int duration,
Layout.AnimationCallback callback)
Updates the layout by animating it over time, with a callback on each frame
of the animation, and upon completion.
|
void |
onAttach()
This method must be called when the parent element becomes attached to the
document.
|
void |
onDetach()
This method must be called when the parent element becomes detached from
the document.
|
void |
removeChild(Layout.Layer layer)
Removes a child element from this layout.
|
public Layout(Element parent)
parent - the element to serve as the layout parentpublic void assertIsChild(Element elem)
elem - the element to be testedpublic Layout.Layer attachChild(Element child)
This method will attach the child to the layout, removing it from its
current parent element. Use the Layout.Layer it returns to manipulate the
child.
child - the child to be attachedLayout.Layer associated with the elementpublic Layout.Layer attachChild(Element child, Element before)
This method will attach the child to the layout, removing it from its
current parent element. Use the Layout.Layer it returns to manipulate the
child.
child - the child to be attachedbefore - the child element before which to insertLayout.Layer associated with the elementpublic Layout.Layer attachChild(Element child, java.lang.Object userObject)
This method will attach the child to the layout, removing it from its
current parent element. Use the Layout.Layer it returns to manipulate the
child.
child - the child to be attacheduserObject - an arbitrary object to be associated with this layerLayout.Layer associated with the elementpublic Layout.Layer attachChild(Element child, Element before, java.lang.Object userObject)
This method will attach the child to the layout, removing it from its
current parent element. Use the Layout.Layer it returns to manipulate the
child.
child - the child to be attachedbefore - the child element before which to insertuserObject - an arbitrary object to be associated with this layerLayout.Layer associated with the elementpublic void fillParent()
This is most useful for top-level layouts that need to follow the size of another element, such as the <body>.
public double getUnitSize(Style.Unit unit, boolean vertical)
This will work for any unit type, but be aware that certain unit types,
such as Style.Unit.EM, and Style.Unit.EX, will return different values
based upon the parent's associated font size. Style.Unit.PCT is dependent
upon the parent's actual size, and the axis to be measured.
unit - the unit type to be measuredvertical - whether the unit to be measured is on the vertical or
horizontal axis (this matters only for Style.Unit.PCT)public void layout()
layers.public void layout(int duration)
duration - the duration of the animationlayout(int, AnimationCallback)public void layout(int duration,
Layout.AnimationCallback callback)
duration - the duration of the animationcallback - the animation callbackpublic void onAttach()
onDetach()public void onDetach()
onAttach()public void removeChild(Layout.Layer layer)
layer - the layer associated with the child to be removed