The DividedBox layout container lays out its children horizontally or vertically, similar to a Box container, except that it inserts a divider between each child. You can use a mouse pointer to move the dividers in order to resize the area of the container allocated to each child. You use the direction property of a DividedBox container to determine vertical (default) or horizontal layout. The HDividedBox and VDividedBox containers are DividedBox containers with horizontal and vertical direction property values.

The following example shows a DividedBox container:

In this example, the outermost container is a horizontal DividedBox container. The horizontal divider marks the border between a Tree control and a vertical DividedBox container.

The vertical DividedBox container holds a DataGrid control (top) and a TextArea control (bottom). The vertical divider marks the border between these two controls.

For complete reference information, see the Adobe Flex Language Reference.

Creating a DividedBox, HDividedBox, or VDividedBox container

You use the <mx:DividedBox>, <mx:VDividedBox>, and <mx:HDividedBox> tags to define DividedBox containers. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block. Typically, you use the VDividedBox (vertical DividedBox) and HDividedBox (horizontal DividedBox) containers as shortcuts so that you do not have to specify the direction property.

The following code example creates the image shown in DividedBox, HDividedBox, and VDividedBox layout containers:

<?xml version="1.0"?>
<!-- containers\layouts\HDivBoxSimple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
    backgroundColor="white">

    <mx:Script>
      <![CDATA[
        private function myGrid_initialize():void {
          myGrid.dataProvider = [
            {Artist:'Pavement', Album:'Slanted and Enchanted', 
                Price:11.99, Comment:'One of their best. 4 Stars.'},
            {Artist:'Pavement', Album:'Brighten the Corners', 
                Price:11.99, Comment:'My favorite.'}
          ];
        }
      ]]>
    </mx:Script>

    <mx:HDividedBox width="100%" height="100%">
        <mx:Tree id="tree1" 
            width="30%" height="100%"
            labelField="@label" 
            showRoot="true">
            <mx:XMLList>
                <menuitem label="Products">
                    <menuitem label="Posters" isBranch="true"/>
                    <menuitem label="CDs">
                        <menuitem label="Pavement"/>
                        <menuitem label="Pavarotti"/>
                        <menuitem label="Phish"/>
                    </menuitem>
                    <menuitem label="T-shirts" isBranch="true"/>
                    <menuitem label="Tickets" isBranch="true"/>
                </menuitem>
            </mx:XMLList>
        </mx:Tree>

        <mx:VDividedBox width="70%" height="100%">
            <mx:DataGrid id="myGrid" 
                width="100%" height="100%" 
                initialize="myGrid_initialize();"
                change="currentMessage.text=
                    event.currentTarget.selectedItem.Comment;"/>
            <mx:TextArea id="currentMessage" 
                width="100%" 
                height="60" 
                text="One of their best. 4 Stars."/>
        </mx:VDividedBox>

    </mx:HDividedBox>
</mx:Application>
The executing SWF file for the previous example is shown below:

Notice that this example does not implement the logic to change the top area of the VDividedBox container when you select a node in the Tree control.

Using the dividers

The dividers of a DividedBox container let you resize the area of the container allocated for a child. However, for the dividers to function, the child has to be resizable; that is, it must specify a percentage-based size. So, a child with an explicit or default height or width cannot be resized in the corresponding direction by using a divider. Therefore, when you use the DividedBox container, you typically use percentage sizing for its children to make them resizable.

When you specify a percentage value for the height or width properties of a child to make it resizable, Flex initially sizes the child to the specified percentage, if possible. Then Flex can resize the child to take up all available space.

You can use the dividers to resize a percentage-sized child up to its maximum size, or down to its minimum size. To constrain the minimum size or maximum size of an area of the DividedBox, set an explicit value for the minWidth and minHeight properties or the maxWidth and maxHeight properties of the children in that area.

Using live dragging

By default, the DividedBox container disables live dragging. This means that the DividedBox container does not update the layout of its children until the user finishes dragging the divider, when the user releases the mouse button on a selected divider.

You can configure the DividedBox container to use live dragging by setting the liveDragging property to true. With live dragging enabled, the DividedBox container updates its layout as the user moves a divider. In some cases, you may encounter decreased performance if you enable live dragging.