About the creationPolicy property

To defer the creation of any component, container, or child of a container, you use the creationPolicy property. Every container has a creationPolicy property that determines how the container decides whether to create its descendants when the container is created. You can change the policy of a container using MXML or ActionScript.

The valid values for the creationPolicy property are auto, all, and none. The meaning of these settings depends on whether the container is a navigator container (multiple-view container) or a single-view container.

The creationPolicy property is inheritable when set on the MX Container or Spark SkinnableContainer class. This means that if you set the value of the creationPolicy property to none on an outer container, all containers within that container inherit that value of the creationPolicy property, unless otherwise overridden.

This inheritance does not apply to sibling containers. If you have two containers at the same level (of the same type) and you set the creationPolicy of one of them, the other container continues to have the default value of the creationPolicy property unless you explicitly set it.

Single-view containers

Single-view containers by default create all their children when the application first starts. You can use the creationPolicy property to change this behavior. The following table describes the values of the creationPolicy property when you use it with single-view containers:

Value

Description

all, auto

Creates all controls inside the single-view container. The default value is auto, but all results in the same behavior.

none

Instructs Flex to not instantiate any component within the container until you manually instantiate the controls.

When the value of the creationPolicy property is none, you generally set a width and height for that container explicitly. Normally, Flex scales the container to fit the children that are inside it, but because no children are created, proper scaling is not possible. If you do not explicitly size the container, it grows to accommodate the children when they are created.

To manually instantiate controls, you use the createDeferredContent() method (for Spark containers) or the createComponentsFromDescriptors() method (for MX containers). For more information, see Creating deferred components.

The following example sets the value of a Spark Panel container’s creationPolicy property to auto, the default value:

<?xml version="1.0"?>
<!-- layoutperformance/AutoCreationPolicy.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:VerticalLayout/> 
    </s:layout>

    <s:Panel id="myPanel" creationPolicy="auto">
        <s:Button id="b1" label="Get Weather"/>
    </s:Panel>
</s:Application>

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

The default behavior of all single-view containers is that they and their children are entirely instantiated when the application starts. If you set the creationPolicy property to none, however, you can selectively instantiate controls within the containers by using the techniques described in Creating deferred components.

Multiple-view containers

Containers with multiple views, such as the ViewStack and Accordion, do not immediately create all of their descendants, but only those descendants that are visible in the initial view. Flex defers the instantiation of descendants that are not initially visible until the user navigates to a view that contains them. The following containers have multiple views and, so, are defined as navigator containers:

When you instantiate a navigator container, Flex creates all of the top-level children. For example, creating an Accordion container triggers the creation of each of its views, but not the controls within those views. The creationPolicy property determines the creation of the child controls inside each view.

When you set the creationPolicy property to auto (the default value), navigator containers instantiate only the controls and their children that appear in the initial view. The first view of the Accordion container is the initial pane, as the following example shows:

When the user navigates to another panel in the Accordion container, the navigator container creates the next set of controls, and recursively creates the new view’s controls and their descendants. You can use the Accordion container’s creationPolicy property to modify this behavior. The following table describes the values of the creationPolicy property when you use it with navigator containers:

Value

Description

all

Creates all controls in all views of the navigator container. This setting causes a delay in application startup time and an increase in memory usage, but results in quicker response time for user navigation. You should generally not use all because of the performance hit that your application will take when it starts up.

auto

Creates all controls only in the initial view of the navigator container. This setting causes a faster startup time for the application, but results in slower response time for user navigation.

This setting is the default for multiple-view containers.

none

Instructs Flex to not instantiate any component within the navigator container or any of the navigator container’s panels until you manually instantiate the controls.

To manually instantiate controls, you use the createDeferredContent() method (for Spark containers) or the createComponentsFromDescriptors() method (for MX containers). For more information, see Creating deferred components.

The following example sets the creationPolicy property of an Accordion container to all, which instructs the container to instantiate all controls for every panel in the navigator container when the application starts:

<?xml version="1.0"?>
<!-- layoutperformance/AllCreationPolicy.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:Panel title="Accordion">
        <mx:Accordion id="myAccordion" creationPolicy="all">
            <mx:VBox label="Accordion Button for Panel 1">
                <mx:Label text="Accordion container panel 1"/>
                <s:Button label="Click Me"/>
            </mx:VBox>
            <mx:VBox label="Accordion Button for Panel 2">
                <mx:Label text="Accordion container panel 2"/>
                <s:Button label="Click Me"/>
            </mx:VBox>
            <mx:VBox label="Accordion Button for Panel 3">
                <mx:Label text="Accordion container panel 3"/>
                <s:Button label="Click Me"/>
            </mx:VBox>
        </mx:Accordion>
    </s:Panel>
</s:Application>

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

Setting a container’s creationPolicy property does not override the policies of the containers within that container.

In the following example, the button1 control is never created because its immediate parent container specifies a creationPolicy of none, even though the outer container sets the creationPolicy property to all:

<?xml version="1.0"?>
<!-- layoutperformance/TwoCreationPolicies.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:Panel title="Outer Panel where creationPolicy=all" creationPolicy="all">
        <s:Panel title="Inner Panel where creationPolicy=none" creationPolicy="none">
            <s:Button id="button1" label="Click Me"/>
        </s:Panel>
    </s:Panel>
</s:Application>

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