Package com.google.gwt.layout.client

Class Layout

  • public class Layout
extends java.lang.Object
    Helper class for laying out a container element and its children.

    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.

    Example

    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.

    • Constructor Summary

      Constructors 
      Constructor Description
      Layout​(Element parent)
      Constructs a new layout associated with the given parent element.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method 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.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Layout

        public Layout​(Element parent)
        Constructs a new layout associated with the given parent element.
        Parameters:
        parent - the element to serve as the layout parent

    • Method Detail

      • assertIsChild

        public void assertIsChild​(Element elem)
        Asserts that the given child element is managed by this layout.
        Parameters:
        elem - the element to be tested

      • attachChild

        public Layout.Layer attachChild​(Element child)
        Attaches a child element to this layout.

        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.

        Parameters:
        child - the child to be attached
        Returns:
        the Layout.Layer associated with the element

      • attachChild

        public Layout.Layer attachChild​(Element child,
                                Element before)
        Attaches a child element to this layout.

        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.

        Parameters:
        child - the child to be attached
        before - the child element before which to insert
        Returns:
        the Layout.Layer associated with the element

      • attachChild

        public Layout.Layer attachChild​(Element child,
                                java.lang.Object userObject)
        Attaches a child element to this layout.

        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.

        Parameters:
        child - the child to be attached
        userObject - an arbitrary object to be associated with this layer
        Returns:
        the Layout.Layer associated with the element

      • attachChild

        public Layout.Layer attachChild​(Element child,
                                Element before,
                                java.lang.Object userObject)
        Attaches a child element to this layout.

        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.

        Parameters:
        child - the child to be attached
        before - the child element before which to insert
        userObject - an arbitrary object to be associated with this layer
        Returns:
        the Layout.Layer associated with the element

      • fillParent

        public void fillParent()
        Causes the parent element to fill its own parent.

        This is most useful for top-level layouts that need to follow the size of another element, such as the <body>.

      • getUnitSize

        public double getUnitSize​(Style.Unit unit,
                          boolean vertical)
        Returns the size of one unit, in pixels, in the context of this layout.

        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.

        Parameters:
        unit - the unit type to be measured
        vertical - whether the unit to be measured is on the vertical or horizontal axis (this matters only for Style.Unit.PCT)
        Returns:
        the unit size, in pixels

      • layout

        public void layout()
        Updates this layout's children immediately. This method must be called after updating any of its children's layers.

      • layout

        public void layout​(int duration)
        Updates the layout by animating it over time.
        Parameters:
        duration - the duration of the animation
        See Also:
        layout(int, AnimationCallback)

      • layout

        public 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.
        Parameters:
        duration - the duration of the animation
        callback - the animation callback

      • onAttach

        public void onAttach()
        This method must be called when the parent element becomes attached to the document.
        See Also:
        onDetach()

      • onDetach

        public void onDetach()
        This method must be called when the parent element becomes detached from the document.
        See Also:
        onAttach()

      • removeChild

        public void removeChild​(Layout.Layer layer)
        Removes a child element from this layout.
        Parameters:
        layer - the layer associated with the child to be removed