Halo ViewStack and Spark ButtonBar Specification

Alex Harui (Dev)
Kari White (QA)

Functional and Design Specification

Glossary

IList - The interface that describes a modifiable array that dispatches change notifications

Summary and Background

Halo ButtonBar could take all kinds of things as a dataProvider such as XMLList, Array or even a ViewStack. In Spark, the dataProvider properly is strongly-typed as IList to simplify and reduce code. In a separate but related feature, Spark Containers can now be placed in a ViewStack and that will increase the odds that someone will want to control that ViewStack using Spark ButtonBar instead of a Halo ButtonBar

Usage Scenarios

Casper uses the new capabilities of ViewStack to create a stack of Spark-based containers that represent different views of a data model. He needs a component that will allow the user to select which ViewStack page is displayed. Because he wants to use custom skins for everything, he doesn't want to use a different skinning model for Halo ButtonBar vs the various Spark skins in the ViewStack pages. He wants to use Spark ButtonBar, but he can't assign the ViewStack as the dataProvider of a Spark ButtonBar

Detailed Description

This feature is implemented in three steps:
1) ViewStack implements IList. New methods implementing IList that mirror DisplayObjectContainer APIs (addChild/removeChild) are added to ViewStack.
2) ViewStack also implements ISelectableList that indicates that the dataProvider has a selectedIndex property.
3) ButtonBar checks when its selectedIndex changes and if the dataProvider implements ISelectableList, sets the selectedIndex on the dataProvider, and watches for the ViewStack's selectedIndex to change and updates its selectedIndex if needed.

API Description

package mx.core
{
/**
 *  Dispatched when the selectedIndex property changes.
 *
 *  @eventType flash.events.Event.CHANGE
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
<a href="Event%28name%3D%26quot%3Bchange%26quot%3B%29">Event(name="change")</a>

/**
 *  ISelectableList is an interface that indicates that the
 *  implementor is a Navigator and supports a selectedIndex
 *  property that should be mirrored by a listening object
 *  like a ButtonBar
 *  
 *  @langversion 3.0
 *  @playerversion Flash 10
 *  @playerversion AIR 1.5
 *  @productversion Flex 4
 */
public interface ISelectableList extends IList
{
    /**
     *  The selectedIndex property that selects which
     *  child the Navigator is viewing.
     */
    function set selectedIndex(value:int):void;
    function get selectedIndex():int;
}

}

B Features

None

Examples and Usage

In MXML:

    <s:ButtonBar id="tb" dataProvider="{vs}" labelField="label" requireSelection="true" />
    <mx:ViewStack id="vs" >

Additional Implementation Details

None

Prototype Work

Prototype complete

Compiler Work

None

Web Tier Compiler Impact

None

Flex Feature Dependencies

None

Backwards Compatibility

Syntax changes

None

Behavior

None

Warnings/Deprecation

None

Accessibility

None

Performance

When a child is added and removed ViewStack will now dispatch CollectionChange events as well as the ADD/REMOVE events it used to dispatch, if there is anybody listening for CollectionChange events. The expected impact of these extra events or logic to consider whether to dispatch them is considered minimal given that ViewStack children are not added and removed very often.

Globalization

None

Localization

Compiler Features

None

Framework Features

None

Issues and Recommendations

None

Documentation

None

QA

None