Mobile ActionBar - Functional and Design Specification

Glossary

ViewNavigator - Like the Flex ViewStack navigation container, ViewNavigator is a new navigator container which consists of a collection of child sections (a Vector of Views) stacked on top of each other, where only one section at a time is visible.

Summary and Background

ActionBar is a SkinnableComponent used to support ViewNavigator. ActionBar provides discrete navigation, title and action content groups that are managed by ViewNavigator. ViewNavigator derives this content from the currently active View or from ViewNavigator's own default content.

Customization is provided in 2 ways:

1. Basic customization is provided via components declared in template properties. For detailed information on template properties, see MobileApplication, View & ViewNavigator specs. These template properties follow a pattern similar to the Spark Application and Panel controlBar groups.
2. Advanced customization is provided by skinning.

Usage Scenarios

John is creating a document editor. Instead of using the OptionsMenu to provide actions for the screen, he uses the actionContent property of his View to add Save and Undo actions to the ActionBar.

Ryan is a designer who wants to create a branded experience for his application. He creates a custom skin for ActionBar that includes a logo Image that provides "Home" navigation. He also uses CSS to specify a flat-styled look to ActionBar Buttons.

Builder - Design View

See Flex Mobile Design View (TBD) spec.

Ryan wants to use Design View to add a back button to simulate the iOS look and feel. He drags a new Button component from the Components panel near the left-hand side of the ActionBar. Design View highlights the area for insertion. When Ryan drops the button over the left side of the ActionBar, the s:navigationContent template property is inserted in to MXML along with a new s:Button.

Catalyst

Work with your Catalyst contacts to complete a workflow specification that describes how this feature will be exposed to users in Catalyst. Include a link to this document here.

Detailed Description

Class Descriptions

The ActionBar feature includes the following classes:

• ActionBar - Defines a component that includes a title area, a navigation area, and an action area
• ActionBarSkin - Default skin

ActionBar Skin Parts

• Required
  • None
• Optional
  • titleDisplay:Text Field (Note: Final text component depends on FMF Components - Text Components (TBD))
  • navigationGroup:Group
  • titleGroup:Group
  • actionGroup:Group

Usage of template properties for ActionBar content

There are 6 total template properties for ActionBar:

• navigationContent and navigationLayout
• titleContent and titleLayout
• actionContent and actionLayout

Template properties for navigationContent, titleContent and actionContent are null by default. Layout properties for each content area are defined by the skin. The default layout is a HorizontalLayout with zero padding.

Title Group

If titleContent is not null, it's visual elements replace the mxmlContent of titleGroup. If titleContent is null, ActionBar inserts the titleDisplay, if present, as the only mxmlContent of titleGroup.

For example, the default skin specifies a titleDisplay TextField. A developer may choose to have a View that replaces the title with an Image. The Image replaces the TextFieldand ActionBar no longer displays the View's title property. When navigating to a new View that does not specify titleContent, the titleDisplay TextField is restored and the new View's title is displayed.

Action Group

actionContent is a proxy for the mxmlContent of actionGroup. Unlike titleGroup, it has no special rules for null content.

Navigation Group

navigationContent is a proxy for the mxmlContent of navigationGroup. Unlike titleGroup, it has no special rules for null content.

Interaction between ActionBar and View and ViewNavigator

Both View and ViewNavigator define proxies for the 6 template properties of ActionBar. When ViewNavigator adds a new View, it checks for these properties and pushes the content to ActionBar. If the active View does not define it's own content, ViewNavigator updates the ActionBar with it's values for these properties. This allows developers to define default content such as a consistent Home button in the navigationContent.

Properties of ActionBar are driven by ViewNavigator as listed below:

• navigationContent - The navigationContent of the active View. If not specified by the View, use ViewNavigator's default content.
• title - The ViewNavigator assigns the ActionBar title value from using the title of the active View. If the value is null or empty, no title is displayed.
• titleContent - The titleContent of the active View. If not specified by the View, use ViewNavigator's default content.
• actionContent - The actionContent of the active View. If not specified by the View, use ViewNavigator's default content.

ViewNavigator manages the ActionBar content as navigation events occur. ViewNavigator listens for property changes when a View becomes activated in order to push updated content to the ActionBar without navigation occurring. When the View is deactivated, ViewNavigator removes it's listeners from the View and listens to the new active View.

Interaction between ActionBar and MobileApplication

MobileApplication also defines proxies for the 6 template properties of ActionBar. These properties offer a declarative way set these default values on ViewNavigator.

ViewNavigator Transitions

Transitions are specified by the View Transitions and Frame-Based Animation (TBD) spec. ActionBar does not provide a mechanism for internal content transitions.

SlideViewTransition defines behavior that requires knowledge of and access to ActionBar skin parts. In particular, SlideViewTransition will detect when content areas of ActionBar can remain static or should be animated in-sync with the View. See the view transitions spec for more details.

API Description

package spark.components
{

[Style(name="chromeColor", type="uint", format="Color", inherit="no", theme="spark")]

/**
* The alpha of the background chrome for this component.
*/
[Style(name="backgroundAlpha", type="Number", inherit="yes", theme="spark", minValue="0.0", maxValue="1.0")]

/**
*
*/
public class ActionBar extends SkinnableComponent
{
public function ActionBar()

[SkinPart(required="false")]
public var titleDisplay:TextField; /* Final text component TBD */

[SkinPart(required="false")]
public var navigationGroup:Group;

[SkinPart(required="false")]
public var titleGroup:Group;

[SkinPart(required="false")]
public var actionGroup:Group;

/**
* Title to display.
*/
public function get title():String
public function set title(value:String):void

[ArrayElementType("mx.core.IVisualElement")]

/**
*  The set of components to include in the titleGroup of the
*  ActionBar. If titleContent is not null, it's visual elements replace the
*  mxmlContent of titleGroup. If titleContent is null, the
*  titleDisplay skin part, if present, replaces the mxmlContent of titleGroup.
*  The location and appearance of the titleGroup of the ActionBar container
*  is determined by the spark.skins.mobile.ActionBarSkin class.
*  By default, the ActionBarSkin class defines the titleGroup to appear in the center
*  of the ActionBar.
*  Create a custom skin to change the default location and appearance of the titleGroup.
*
*  @default null
*/
public function get titleContent():Array
public function set titleContent(value:Array):void

/**
*  Defines the layout of the titleGroup.
*
*  @default HorizontalLayout
*/
public function get titleLayout():LayoutBase
public function set titleLayout(value:LayoutBase):void

[ArrayElementType("mx.core.IVisualElement")]

/**
*  The set of components to include in the navigationGroup of the
*  ActionBar.
*  The location and appearance of the navigationGroup of the ActionBar container
*  is determined by the spark.skins.mobile.ActionBarSkin class.
*  By default, the ActionBarSkin class defines the navigationGroup to appear to the left
*  of the title display area of the ActionBar.
*  Create a custom skin to change the default location and appearance of the navigationGroup.
*
*  @default null
*/
public function get navigationContent():Array
public function set navigationContent(value:Array):void

/**
*  Defines the layout of the navigationGroup.
*
*  @default HorizontalLayout
*/
public function get navigationLayout():LayoutBase
public function set navigationLayout(value:LayoutBase):void

[ArrayElementType("mx.core.IVisualElement")]

/**
*  The set of components to include in the actionGroup of the
*  ActionBar.
*  The location and appearance of the actionGroup of the ActionBar container
*  is determined by the spark.skins.mobile.ActionBarSkin class.
*  By default, the ActionBarSkin class defines the actionGroup to appear to the right
*  of the title display area of the ActionBar.
*  Create a custom skin to change the default location and appearance of the actionGroup.
*
*  @default null
*/
public function get actionContent():Array
public function set actionContent(value:Array):void

/**
*  Defines the layout of the action area.
*
*  @default HorizontalLayout
*/
public function get actionLayout():LayoutBase
public function set actionLayout(value:LayoutBase):void
}
}

B Features

None

Examples and Usage

Example View that provides a title and 2 IconButtons for actionContent.

<?xml version="1.0" encoding="utf-8"?>
<s:View xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark"
        xmlns:ns="*"
        title="Edit Description">
    <s:actionContent>
        <s:Button icon="@Embed(source='undo.fxg')"/>
        <s:Button icon="@Embed(source='redo.fxg')"/>
    </s:actionContent>
    <s:TextArea width="100%" height="100%"/>
</s:View>

Example ViewNavigatorApplication that provides a default Home button for all views.

<?xml version="1.0" encoding="utf-8"?>
<s:ViewNavigatorApplication xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark" firstView="views.HomeView">
    <s:navigationContent>
        <s:Button icon="@Embed(source='home.fxg')" click="navigator.popToFirstView()"/>
    </s:navigationContent>
</s:ViewNavigatorApplication>

Example spark Application (not a ViewNavigatorApplication) in a mobile project defining ActionBar as a child component.

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" 
        xmlns:s="library://ns.adobe.com/flex/spark">    
    <s:ActionBar left="0" right="0" top="0">
        <s:navigationContent>
            <s:Image source="@Embed(source='logo.fxg')"/>
        </s:navigationContent>
        <s:titleContent>
            <s:TextInput text="Find in Page"/>
        </s:titleContent>
        <s:actionContent>
            <s:Button label="Find"/>
            <s:Button label="Next"/>
            <s:Button label="Previous"/>
        </s:actionContent>
    </s:ActionBar>
</s:Application>

Additional Implementation Details

Enter implementation/design details for the feature here. This section may be updated after the spec signs off.

Compiler Work

Will this feature require any compiler changes? If so, describe here, if not already included in the Detailed Description.

• any new compiler switches (flex-config.xml configuration)
• proposed workflow changes
• changes to the Compiler API - example, a logger or localization manager now required

Backwards Compatibility

Syntax changes

None

Behavior

None

Warnings/Deprecation

None

Accessibility

TODO

Performance

None

Globalization

TODO

Localization

Compiler Features

None

Framework Features

List the RTE message strings that will require localization. (They must all come from .properties files.)

List all UI text that will require localization, such as the month and day names in a DateChooser. (All such text must all come from .properties files.)

List all UI images, skins, sounds, etc. that will require localization.

Discuss any locale-specific formatting requirements for numbers, dates, currency, etc.

Discuss any locale-specific sorting requirements.

Cross-Platform Considerations

Tablet

Given the larger screen sizes of tablets, we anticipate that applications will have multiple ViewNavigators displayed simultaneously, each with their own ActionBar. There are no known limitations for ActionBar for the current implementation.

Issues and Recommendations

Open Issues

Resolved Issues