One use of view states is to implement a login and registration form. In this example, the default view state prompts the user to log in, and includes a LinkButton control that lets the user register, if necessary, as the following image shows:

LinkButton control (A)

If the user selects the Need to Register link, the form changes view state to display registration information, as the following image shows:

A.

Modified title of Panel container

B.

New form item

C.

Modified label of Button control

D.

New LinkButton control

Notice the following changes to the default view state to create this view state:

• The title of the Panel container is set to Register

• The Form container has a new TextInput control for confirming the password

• The label of the Button control is set to Register

• The LinkButton control has been replaced with a new LinkButton control that lets the user change state back to the default view state

When the user clicks the Return to Login link, the view state changes back to the default view state to display the Login form. This change reverses all the changes made when changing to the register view state.

To see the code that creates this example, see Example: Login form application.

View states give you one way to change the appearance of an application or component in response to a user action. You can also use MX navigator containers, such as the Accordion, Tab Navigator, and ViewStack containers when you perform changes that affect several components.

Your choice of using navigator containers or states depends on your application requirements and user-interface design. For example, if you want to use a tabbed interface, use a TabNavigator container. You might decide to use the Accordion container to let the user navigate through a complex form, rather than using view states to perform this action.

When comparing view states to ViewStack containers, one thing to consider is that you cannot easily share components between the different views of a ViewStack container. That means you have to recreate a component each time you change views. For example, if you want to show a search component in all views of a View Stack container, you must define it in each view.

When using view states, you can easily share components across multiple view states by defining the component once, and then including it in each view state. For more information about sharing components among view states, see Controlling when to create added children. For more information on navigator containers, see MX navigator containers.

The following example shows an application with a default view state, and one additional view state named "NewButton". In this example, changing to the NewButton view state adds button b2 to the Group container, and disables button b1. Switching back to the default view state removes b2 and enables b1:

<?xml version="1.0"?> 
<!-- states\StatesSimple.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:states> 
        <!-- Define the new view states. --> 
        <s:State name="default"/> 
        <s:State name="NewButton"/> 
    </s:states>    
    <s:VGroup id="g1"> 
 
        <s:HGroup> 
            <!-- Disable Button in the NewButton view state. --> 
            <s:Button id="b1" label="Click Me" 
                enabled.NewButton="false"/> 
 
            <!-- Add a new child control to the VBox. --> 
            <s:Button id="b2" label="New Button" 
                includeIn="NewButton"/> 
        </s:HGroup> 
 
        <!-- Define Button control to switch to NewButton view state. --> 
        <s:Button label="Change to NewButton state" 
            click="currentState='NewButton';"/>            
        <!-- Define Button control to switch to default view state. --> 
        <s:Button label="Change to default view state" 
            click="currentState='default';"/> 
    </s:VGroup>    
</s:Application>

Consider the following when you define a view state.

• Define view states at the root of an application or at the root of a custom component; that is, as a property of the Application container of an application file, or of the root tag of an MXML component.

• Define states by using a component's states property, normally by using the <s:states> tag in MXML.

• Populate the states property with an Array of one or more State objects, where each State object corresponds to a view state.

• Use the name property of the State object to specify its identifier. To change to that view state, you set a component's currentState property to the value of the name property.

  Note: View state definitions are processed at compile time. Therefore, you cannot use data binding to set the State.name property because data binding occurs at run time.

The following MXML code shows this structure:

 <s:Application>  
 	<!-- Define the view states.  
 		The <s:states> tag can also be a child tag of  
 		the root tag of a custom component.  
 	--> 
 	<s:states> 
 		<s:State name="State1"/> 
		<s:State name="State2"/> 
		<s:State name="State3"/> 
		. 
 		. 
 	</s:states> 
 	<!-- Application definition. --> 
 	. 
 	. 
 </s:Application>

The default view state is defined as the first view state in the <s:states> Array. An application uses the default view state when it loads. The name of the default view state is not reserved, so it is not required to be "default".

The UIComponent class defines the currentState property that you use to set the current view state. When the application starts, the default value of the currentState property is the name of the first view state defined by the <s:states> tag.

In the next example, you use a Button control to set the currentState property of the Application object to "State1" or "State2", the names of a view state specified by the <s:State> tag:

 <s:Button id="b1" label="Change to State 1" click="currentState='State2';"/> 
 <s:Button id="b2" label="Change to the default" click="currentState='State1';"/>

The second button in the previous example sets the current state to "State1" so that you can switch back to the default view state from "State2".

You can also set the currentState property to an empty String to set it to the default state, as the following example shows:

  <s:Button id="b2" label="Change to the default" click="currentState='';"/>

You can change a component's view state by calling the setCurrentState() method of the UIComponent class. Use this method when you do not want to apply a transition that you have defined between two view states. For more information on transitions, see Transitions.

propertyOrStyleName.stateName

<s:Button label="Default State" label.State2="New State"/>

The value of the label property qualified by "State2" specifies the value for the property in that view state. The unqualified property definition, the one that omits the dot notation, defines the value of the property for all view states where you do not explicitly define an override.

Do not define an override for every property, style, and event for all view states. Only define the override for those view states where you want to change the value of the element.

You can also use child tags with the dot notation to define property overrides, as the following example shows for the b1 button control:

<?xml version="1.0"?> 
<!-- states\StatesSimpleChildTags.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:states> 
        <!-- Define the new view states. --> 
        <s:State name="default"/> 
        <s:State name="NewButton"/> 
    </s:states>    
 
    <s:VGroup > 
        <s:HGroup> 
            <!-- Disable Button in the NewButton view state. --> 
            <s:Button id="b1"> 
                <s:label>Click Me</s:label> 
                <s:label.NewButton>Disabled</s:label.NewButton> 
                <s:enabled.NewButton>false</s:enabled.NewButton> 
            </s:Button> 
            
            <!-- Add a new child control to the VBox. --> 
            <s:Button id="b2" label="New Button" 
                includeIn="NewButton"/> 
        </s:HGroup> 
 
        <!-- Define Button control to switch to NewButton view state. --> 
        <s:Button label="Change to NewButton state" 
            click="currentState='NewButton';"/>            
        <!-- Define Button control to switch to default view state. --> 
        <s:Button label="Change to default view state" 
            click="currentState='default';"/> 
    </s:VGroup>    
</s:Application>

<s:Button color="0xFF0000" color.State1="@Clear()"/>

For a style property, setting the value to @Clear() corresponds to calling the clearStyle() method on the property.

Use the dot operator to change the event handler for a specific view state, as the following example shows. In this example, the handler for the click event for button b1 is set based on the view state:

<?xml version="1.0"?> 
<!-- states\StatesEventHandlersSimple.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:states> 
        <s:State name="default"/> 
        <s:State name="logout"/> 
    </s:states> 
 
    <s:VGroup > 
        <s:Button id="b1" label="Click Me" 
            click="ta1.text='hello';" 
            click.logout="ta1.text='goodbye'"/> 
        <s:TextArea id="ta1" height="100" width ="50%"/> 
 
        <s:Button label="Default State" 
            click="currentState='';" 
            enabled="false" 
            enabled.logout="true"/> 
        <s:Button label="Logout State" 
            click="currentState='logout';" 
            enabled="true" 
            enabled.logout="false"/> 
    </s:VGroup> 
</s:Application>

Use the includeIn and excludeFrom MXML attributes to specify the set of view states in which a component is included, where:

• The includeIn attribute specifies the list of view states where the component appears. This attribute takes a comma delimited list of view state names, all which must have been previously declared in the <s:states> Array.

• The excludeFrom attribute specifies the list of view states where the component is omitted. This attribute takes a comma delimited list of view state names.

• The excludeFrom and includeIn attributes are mutually exclusive; it is an error to define both on a single MXML tag.

The following example uses view states to add components to the application based on the current state:

<?xml version="1.0"?> 
<!-- states\StatesSimpleIncExc.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:states> 
        <s:State name="default"/> 
        <s:State name="addCheckBox"/> 
        <s:State name="addTextInput"/> 
        <s:State name="addCheckBoxandButton"/> 
    </s:states> 
     
    <s:HGroup > 
        <!-- Included in the addCheckBox and addCheckBoxandButton view states. --> 
        <s:CheckBox id="myCB" label="Checkbox" 
           includeIn="addCheckBox, addCheckBoxandButton"/> 
     
        <!-- Included in the addTextInput view state. --> 
        <s:TextInput id="myTI" 
           includeIn="addTextInput"/>    
        <!-- Included in the addCheckBoxandButton view state. --> 
        <s:Button id="myB" 
           includeIn="addCheckBoxandButton"/> 
        
        <!-- Exclude from addTextInput view state. --> 
        <s:TextArea text="Exclude from addTextInput" 
            excludeFrom="addTextInput"/>        
    </s:HGroup> 
 
    <s:HGroup> 
        <s:Button label="Add CheckBox" 
            click="currentState='addCheckBox'"/> 
        <s:Button label="Show Textinput Only" 
            click="currentState='addTextInput'"/>    
        <s:Button label="Add CheckBox and Button" 
            click="currentState='addCheckBoxandButton'"/> 
        <s:Button label="Default" 
            click="currentState='default'"/> 
    </s:HGroup> 
</s:Application>

The stateGroups attribute of the <s:States> tag lets you group one or more states together. For example, if multiple components appear in the same set of view states, create a view state group that contains all these view states. Then, when you set the currentState property to any view state in the group, the components appears.

In the following example, the CheckBox control named myCB appears when you change to any view state in Group1:

<?xml version="1.0"?> 
<!-- states\StatesSimpleGroups.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:states> 
        <s:State name="default"/> 
        <s:State name="addCheckBox" stateGroups="Group1"/> 
        <s:State name="addTextInput"/> 
        <s:State name="addCheckBoxandButton" stateGroups="Group1"/> 
    </s:states> 
      
    <s:HGroup> 
        <!-- Included in the addCheckBox and addCheckBoxandButton view states. --> 
        <s:CheckBox id="myCB" label="Checkbox" 
            includeIn="Group1"/> 
     
       <!-- Included in the addTextInput view state. --> 
       <s:TextInput id="myTI" 
            includeIn="addTextInput"/>    
        <!-- Included in the addCheckBoxandButton view state. --> 
        <s:Button id="myB" 
           includeIn="addCheckBoxandButton"/> 
        
        <!-- Exclude from addTextInput view state. --> 
        <s:TextArea text="Exclude from addTextInput" 
           excludeFrom="addTextInput"/>             
    </s:HGroup> 
 
    <s:HGroup> 
        <s:Button label="Add CheckBox" 
            click="currentState='addCheckBox'"/> 
        <s:Button label="Add Textinput" 
            click="currentState='addTextInput'"/>    
        <s:Button label="Add Group 1" 
            click="currentState='addCheckBoxandButton'"/> 
        <s:Button label="Default" 
            click="currentState='default'"/> 
    </s:HGroup> 
</s:Application>

The following example creates the Login and Register forms shown in About view states. This application has the following features:

• When the user clicks the Need to Register LinkButton control, the event handler for the click event sets the view state to Register.

• The Register state code adds a TextInput control, changes properties of the Panel container and Button control, removes the existing LinkButton controls, and adds a new LinkButton control.

• When the user clicks the Return to Login LinkButton control, the event handler for the click event resets the view state to the default view state.

<?xml version="1.0"?> 
<!-- states\LoginExample.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"> 
 
    <!-- The Application class states property defines the view states.--> 
    <s:states> 
        <s:State name="default"/>    
        <s:State name="Register"/> 
    </s:states> 
 
    <!-- Set title of the Panel container based on the view state.--> 
    <s:Panel id="loginPanel" 
        title="Login" title.Register="Register"> 
        <s:layout> 
            <s:VerticalLayout/> 
        </s:layout>        
        <s:Form id="loginForm"> 
            <s:FormItem label="Username:"> 
                <s:TextInput/> 
            </s:FormItem> 
            
            <s:FormItem label="Password:"> 
                <s:TextInput/> 
            </s:FormItem> 
            
            <s:FormItem id="confirm" label="Confirm:" includeIn="Register"> 
                <!-- Add a TextInput control to the form for the Register view state. -->           
                <s:TextInput/> 
            </s:FormItem>            
            
            <s:FormItem>            
                <!-- Use the LinkButton to change view state.--> 
                <s:HGroup> 
                    <!-- Set label of the control based on the view state.--> 
                    <mx:LinkButton id="registerLink" 
                        label="Need to Register?" 
                        label.Register="Return to Login" 
                        click="currentState='Register'" 
                        click.Register="currentState=''"/> 
                    <s:Button id="loginButton" 
                        label="Login" label.Register="Register"/> 
                </s:HGroup> 
            </s:FormItem>            
        </s:Form> 
    </s:Panel> 
</s:Application>

In this example, you define an application with three Panel containers and three view states, as the following example shows:

A.

Default view state

B.

One view state

C.

Two view state

To change view state, click the Panel container that you want to display in the expanded size. For a version of this example that adds a transition to animate the view state change, see Defining transitions.

<?xml version="1.0"?> 
<!-- states/ThreePanel.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" width="400"> 
 
    <!-- Define the two view states, in addition to the default view state.--> 
    <s:states> 
        <s:State name="default"/> 
        <s:State name="One"/> 
        <s:State name="Two"/> 
    </s:states> 
 
    <!-- Define the Group container holding the three Panel containers.--> 
    <s:Group width="100%" height="100%"> 
        <s:Panel id="p1" title="One" 
                x="0" y="0" 
                x.One="110" y.One="0" 
                x.Two="0" y.Two="0" 
                width="100" height="100" 
                width.One="200" height.One="210" 
                width.Two="100" height.Two="100" 
                click="currentState='One'"> 
            <s:Label fontSize="24" text="One"/> 
        </s:Panel> 
        
        <s:Panel id="p2" title="Two" 
                x="0" y="110" 
                x.One="0" y.One="0" 
                x.Two="110" y.Two="0" 
                width="100" height="100" 
                width.One="100" height.One="100" 
                width.Two="200" height.Two="210" 
                click="currentState='Two'"> 
            <s:Label fontSize="24" text="Two"/> 
        </s:Panel> 
        
        <s:Panel id="p3" title="Three" 
                x="110" y="0" 
                x.One="0" y.One="110" 
                x.Two="0" y.Two="110" 
                width="200" height="210" 
                width.One="100" height.One="100" 
                width.Two="100" height.Two="100" 
                click="currentState='default'"> 
            <s:Label fontSize="24" text="Three"/> 
        </s:Panel> 
    </s:Group> 
</s:Application>

You can optimize this application by using view state groups, as the following example shows:

<?xml version="1.0"?> 
<!-- states/ThreePanelGroups.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" width="400"> 
 
    <!-- Define the two view states, in addition to the default state.--> 
    <s:states> 
        <s:State name="default" stateGroups="grpDefaultOne, grpDefaultTwo"/> 
        <s:State name="One" stateGroups="grpDefaultOne, grpOneTwo "/> 
        <s:State name="Two" stateGroups="grpDefaultTwo, grpOneTwo"/> 
    </s:states> 
 
    <!-- Define the Group container holding the three Panel containers.--> 
    <s:Group width="100%" height="100%"> 
        <s:Panel id="p1" title="One" 
                x.grpDefaultTwo="0" y.grpDefaultTwo="0" 
                x.One="110" y.One="0" 
                width.grpDefaultTwo="100" height.grpDefaultTwo="100" 
                width.One="200" height.One="210" 
                click="currentState='One'"> 
            <s:Label fontSize="24" text="One"/> 
        </s:Panel> 
        
        <s:Panel id="p2" title="Two" 
                x="0" y="110" 
                x.One="0" y.One="0" 
                x.Two="110" y.Two="0" 
                width.grpDefaultOne="100" height.grpDefaultOne="100" 
                width.Two="200" height.Two="210" 
                click="currentState='Two'"> 
            <s:Label fontSize="24" text="Two"/> 
        </s:Panel> 
        
        <s:Panel id="p3" title="Three" 
                x="110" y="0" 
                x.grpOneTwo="0" y.grpOneTwo="110" 
                width="200" height="210" 
                width.grpOneTwo="100" height.grpOneTwo="100" 
                click="currentState='default'"> 
            <s:Label fontSize="24" text="Three"/> 
        </s:Panel> 
    </s:Group> 
</s:Application>

When a component's currentState property changes, the State object for the states being exited and entered dispatch the following events:

enterState

Dispatched after a view state is entered. Dispatched by a State object and by a component.

exitState

Dispatched when a view state is about to be exited. Dispatched by a State object before it is exited, and by a component before it exits the current view state.

The component on which you modify the currentState property to cause the state change dispatches the following events:

currentStateChanging

Dispatched when the view state is about to change. It is dispatched by a component after its currentState property changes, but before the view state changes. You can use this event to request any data from the server required by the new view state.

currentStateChange

Dispatched after the view state has completed changing. It is dispatched by a component after its currentState property changes. You can use this event to send data back to a server indicating the user's current view state.

<?xml version="1.0"?> 
<!-- states\StatesSimpleEvent.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" 
    height="450"> 
 
    <s:states> 
        <!-- Define the new view states. --> 
        <s:State name="default" 
            enterState="MyEnterTA.text = 'Enter state: default';" 
            exitState="MyExitTA.text = 'Exit state: default';"/> 
        <s:State name="NewButton" 
            enterState="MyEnterTA.text = 'Enter state: NewButton';" 
            exitState="MyExitTA.text = 'Exit state: NewButton';"/> 
    </s:states>    
    <s:VGroup id="g1"> 
        <s:HGroup> 
            <s:Button id="b1" label="Click Me" 
                enabled.NewButton="false"/> 
            <s:Button id="b2" label="New Button" 
                includeIn="NewButton"/> 
        </s:HGroup> 
 
        <s:Button label="Change to NewButton state" 
            click="currentState='NewButton';"/>            
        <s:Button label="Change to default view state" 
            click="currentState='default';"/> 
 
        <s:TextArea id="MyEnterTA"/> 
        <s:TextArea id="MyExitTA"/> 
        
    </s:VGroup>    
</s:Application>