Spark containers

Spark containers provide a hierarchical structure to arrange and configure their children.

Layout with Spark containers

Spark containers have a default layout scheme, but let you switch the layout to suit your application requirements. The layout classes are defined in the spark.layouts package, and include the following classes:
  • BasicLayout Use absolute positioning, or layout constraints.

  • HorizontalLayout Lay out children in a single horizontal row.

  • TileLayout Lay out children in multiple rows and columns.

  • VerticalLayout Lay out children in a single vertical column.

For example, the default layout of the Group container is BasicLayout, which means you must set the position of each container child. For the SkinnableContainer container, the default layout is BasicLayout. You can use any of the layout classes with the Spark containers.

For more information, see Spark containers.

Skinning Spark containers

The Spark Group, DataGroup, and BorderContainer containers do not support skinning. All other Spark containers support skinning so that you can control the visual aspects of the container.

For more information, see Spark Skinning.

Scrolling Spark containers

The following example shows a Spark Group container that contains a child Image control:
<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\SparkNoViewportNoSB.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">
  
    <s:Group width="100" height="100">  
        <s:Image width="300" height="400" 
            source="@Embed(source='/assets/logo.jpg')"/> 
    </s:Group>         
</s:Application> 

The executing SWF file for the previous example is shown below:

The size of the Image control is larger than that of its parent Group container. By default, the child extends past the boundaries of the parent container.

Rather than allow the child to extend past the boundaries of the parent container, you can clip the child to the container boundaries. With clipping enabled, you can control the part of the underlying image to show in the container. To clip the children to the container boundaries, use a viewport and scroll bars.

Configuring a Spark viewport

A viewport is any class that implements the IViewport interface. The Spark Group and DataGroup containers implement this interface, so they can function as viewports. All subclasses of Group and DataGroup can also function as viewports.

A viewport defines a logical content area that encompasses all of the children of the container. It also defines a rectangular area, called the visible window, of the logical content area. The visible window is the subset of the logical area of a container that you want to display.

The following figure shows a Group container with a child Image control that is larger than the area of the Group container:

A.
Group container

B.
Area of the visible window

C.
Visible window of the Group container that appears in the application

The application user only sees that part of the container enclosed by the visible window.

You use the following properties of the Spark container to configure the viewport:

  • contentHeight and contentWidth specify the size of the logical content area of the container. This is the area occupied by all of the container’s children.

  • height and width specify the size of the visible window of the container.

  • verticalScrollPosition and horizontalScrollPosition specify the origin of the visible window in the container’s coordinate system. The default value is (0,0) corresponding to the upper-left corner of the container.

  • clipAndEnableScrolling, if true, specifies to clip the children to the boundaries of the container. If false, the container children extend past the container boundaries, regardless of the size specification of the container. The default value is false.

The following example sets the clipAndEnableScrolling property to true to clip the container’s children to the container boundaries:
<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\SparkViewport.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">

    <s:Group width="100" height="100"
        clipAndEnableScrolling="true">  
        <s:Image width="300" height="400" 
            source="@Embed(source='/assets/logo.jpg')"/> 
    </s:Group>         
</s:Application> 

The executing SWF file for the previous example is shown below:

In this example, you set the width and height of the container, corresponding to the visible window, to 100 by 100 pixels.

By default, the visible window is located at the coordinates (0,0) in the container. Use the verticalScrollPosition and horizontalScrollPosition properties to set its location, as the following example shows:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\SparkViewportSet.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" >

    <s:Group width="100" height="100"
        horizontalScrollPosition="50" verticalScrollPosition="50"
        clipAndEnableScrolling="true"> 
        <s:Image width="300" height="400"
            source="@Embed(source='/assets/logo.jpg')"/> 
    </s:Group>          
</s:Application> 

The executing SWF file for the previous example is shown below:

Adding scroll bars to a Spark container

The visible window of a viewport on its own is not movable by the application user. However, you can combine a viewport with scroll bars so the user can scroll the visible window to see the entire container. Scroll bars let you display an object that is larger than the available screen space or display more objects than fit in the current size of the container, as the following image shows:
Flex container with scroll bars
A.
Image at full size

B.
Image in a container with scroll bars

Add scroll bars to Spark containers in the following ways:

  • For viewport containers such as Group and DataGroup, add HScrollBar and VScrollBar components.

  • For viewport containers such as Group and DataGroup, wrap the container in a Scroller component. The Scroller component displays a single child component with horizontal and vertical scroll bars.

  • For any skinnable Spark container, create a skin for the container that uses the Scroller component. For information on creating a scrollable skin, see Adding scroll bars to Spark containers.

In the following example, you add the HScrollBar and VScrollBar components to the application:
<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\SparkScrollViewportSetSB.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" >
    <s:layout>
        <s:HorizontalLayout/>
    </s:layout>
    
    <s:VGroup>
        <s:Group id="myGroup" width="100" height="100"
            clipAndEnableScrolling="true"
            horizontalScrollPosition="50" verticalScrollPosition="50"> 
            <s:Image width="300" height="400" 
                source="@Embed(source='/assets/logo.jpg')"/> 
        </s:Group>                 
        <s:HScrollBar viewport="{myGroup}" width="100"/>
    </s:VGroup>
    <s:VScrollBar viewport="{myGroup}" height="100"/>
</s:Application> 

The executing SWF file for the previous example is shown below:

Use the viewport property of a scroll bar component to specify the viewport associated with it. In this example, you associate the myGroup container with the scoll bars. As you manipulate the HScrollBar component, it modifies the horizontalScrollPosition property of the group container. The VScrollBar component modifies the verticalScrollPosition property.

In the following example, you add scroll bars to the Spark Group container by wrapping the container in the Scroller component:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\SparkScroll.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" >
 
    <s:Scroller width="100" height="100">
        <s:Group> 
            <s:Image width="300" height="400" 
                source="@Embed(source='/assets/logo.jpg')"/> 
        </s:Group>        
    </s:Scroller>     
</s:Application>

The executing SWF file for the previous example is shown below:

The Scroller component can only wrap a single component. The child of a Scroller tag must implement the IViewport interface, which is implemented by the Spark Group and DataGroup containers.

The Scroller component sets the height and width properties, rather than its child. Alternatively, you can omit the size settings on the Scroller component and let the application determine its size.

To ensure that scroll bars appear, do not set explicit sizes on the child of the Scroller. If you set the size of the child explicitly, then that size becomes the size of the child and no scroll bars appear. Instead, use constraints to size the Scroller (such as setting the height property to 100%).

If the Scroller is unconstrained, it sizes itself to be as big as the viewport. When you constrain the size of the Scroller a size smaller than the child, the Scroller displays scroll bars so that you can view the entire child.

Notice that the Group container did not set the clipAndEnableScrolling property to true. The Scroller component automatically sets the clipAndEnableScrolling property to true for any viewport within it. Scroll bars only appear if required by the viewport.

Use the Scroller.ensureElementIsVisible() method to scroll a component into view. Simply pass the component as an argument to the ensureElementIsVisible() method.

The default skin for the scroll bars defines the minimum height of a vertical scroll bar and the minimum width of a vertical scroll bar as 35 pixels. If the size of the scroll bar is less than 35 pixels, the thumb is hidden.

The default property of the Scroller tag is viewport. The previous example omits this tag, but you can specify it explicitly, as the following example shows:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\SparkScrollViewport.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark">

    <s:Scroller width="100" height="100">
        <s:viewport>
            <s:Group> 
                <s:Image width="300" height="400" 
                    source="@Embed(source='/assets/logo.jpg')"/> 
            </s:Group>
        </s:viewport>
    </s:Scroller>
</s:Application> 

The executing SWF file for the previous example is shown below:

You can combine scroll bars with explicit settings for the container’s viewport. The viewport settings determine the initial position of the viewport, and then you can use the scroll bars to move it, as the following example shows:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\SparkScrollViewportSet.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" >

    <s:Scroller width="100" height="100">
        <s:Group
            horizontalScrollPosition="50" 
            verticalScrollPosition="50"> 
            <s:Image width="300" height="400" 
                source="@Embed(source='/assets/logo.jpg')"/> 
        </s:Group>                 
    </s:Scroller>
</s:Application> 

The executing SWF file for the previous example is shown below:

Not all Spark containers implement the IViewPort interface. Therefore, those containers, such as the BorderContainer and SkinnableContainer containers, cannot be used as the direct child of the Scroller component.

However, all Spark containers can have a Scroller component as a child component. For example, to use scroll bars on a child of the Spark BorderContainer container, wrap the child in a Scroller component, as the following example shows:

<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\SparkScrollBorder.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" >

    <s:BorderContainer width="100" height="100" 
        borderWeight="3" borderStyle="solid">
        <s:Scroller width="100%" height="100%">
            <s:Group
                horizontalScrollPosition="50" 
                verticalScrollPosition="50"> 
                <s:Image width="300" height="400" 
                    source="@Embed(source='/assets/logo.jpg')"/> 
            </s:Group>                 
        </s:Scroller>        
    </s:BorderContainer> 
</s:Application> 

The executing SWF file for the previous example is shown below:

The previous example used the Scroller component to make a child of the BorderContainer container scrollable. To make the entire BorderContainer container scrollable, wrap it in a Group container. Then, make the Group container the child of the Scroller component, as the following example shows:
<?xml version="1.0" encoding="utf-8"?>
<!-- containers\spark\SparkScrollBorderOuter.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
    xmlns:mx="library://ns.adobe.com/flex/mx" 
    xmlns:s="library://ns.adobe.com/flex/spark" >

    <s:Scroller width="100" height="100">
        <s:Group>
            <s:BorderContainer 
                borderWeight="3" borderStyle="solid">
                    <s:Image width="300" height="400" 
                        source="@Embed(source='/assets/logo.jpg')"/> 
            </s:BorderContainer> 
        </s:Group>
    </s:Scroller>
</s:Application> 

The executing SWF file for the previous example is shown below: