Menu

Spark SkinnableDataContainer

SourceForge Editorial Staff

Spark SkinnableDataContainer - Functional and Design Specification


Summary and Background


graphic element - A graphical element like a Rectangle, Path, or Bitmap. This element is not a subclass of DisplayObject; however, it does need a DisplayObject to render on to.

visual element - A visual element (a.k.a. - "element"). This can be a halo component, a gumbo component, or a graphic element. Visual elements implement IVisualElement.

data item (a.k.a. - "item") - Basically anything is considered a data item. Mostly it refers to a non-visual item like a String, Number, XMLNode, etc. A visual element can also be a data item--it just depends on how it's treated.
}SkinnableContainer - A skinnable component with chrome that holds and lays out visual elements. It also serves as a base class for other skinnable visual containers. For example, Panel is a subclass of SkinnableContainer that has a border, header, and footer.

}SkinnableDataContainer - A skinnable component with chrome that holds and lays out data items and supports virtualization. It also serves as a base class for other skinnable data containers. For example, List is a subclass of SkinnableDataContainer that adds support for selection, mouse handling, and key handling.

Usage Scenario


The first example shows using SkinnableDataContainer as a container to show data items. The second example extends SkinnableDataContainer to create ListBase to add selection handling to SkinnableDataContainer.

Example 1: Displaying data items in SkinnableDataContainer

<s:SkinnableDataContainer itemRenderer="myItemRenderer">
    <s:layout><s:VerticalLayout horizontalAlign="center"/></s:layout>
    <s:ArrayCollection>
        <fx:Object firstName="Deepa" lastName="Subramaniam" phoneNumber="415-555-1111" />
        <fx:Object firstName="Glenn" lastName="Ruehle" phoneNumber="415-555-2222" />
        <fx:Object firstName="Ely" lastName="Greenfield" phoneNumber="415-555-3333" />
        <fx:Object firstName="Alex" lastName="Harui" phoneNumber="415-555-4444" />
        <fx:Object firstName="Ryan" lastName="Frishberg" phoneNumber="415-555-5555" />
    </s:ArrayCollection>
</s:SkinnableDataContainer>

Example 2: ListBase

package spark.components {
/**
 *  Dispatched when the selection is going to change. 
 *  Calling the <code>preventDefault()</code> method
 *  on the event will prevent the selection from changing.
 */
<a href="Event%28name%3D%26quot%3BselectionChanging%26quot%3B%2C%20type%3D%26quot%3Bmx.events.IndexChangedEvent%26quot%3B%29">Event(name="selectionChanging", type="mx.events.IndexChangedEvent")</a>

/**
 *  Dispatched after the selection has changed. 
 */
<a href="Event%28name%3D%26quot%3BselectionChanged%26quot%3B%2C%20type%3D%26quot%3Bmx.events.IndexChangedEvent%26quot%3B%29">Event(name="selectionChanged", type="mx.events.IndexChangedEvent")</a>

/**
 *  Dispatched after the focus has changed.  
 */
<a href="Event%28name%3D%26quot%3BitemFocusChanged%26quot%3B%2C%20type%3D%26quot%3Bmx.events.IndexChangedEvent%26quot%3B%29">Event(name="itemFocusChanged", type="mx.events.IndexChangedEvent")</a>

public class ListBase extends SkinnableDataContainer
{
    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------

    /**
     *  The 0-based index of the selected item, or -1 if no item is selected.
     *  Setting the selectedIndex property de-selects the currently selected
     *  item and selects the item at the specified index.
     *
     *  The value of selectedIndex is always pinned between -1 and
     *  (dataProvider.length - 1). If item's at a lower index than selectedIndex are
     *  removed from the component, the selected index is adjusted downward
     *  accordingly. If the selected item is removed, selected index is
     *  set to -1 (if requireSelection = false or there are no remaining items)
     *  or 0 (if requireSelection = true and there is at least one item).
     *
     *  @default -1
     */
    public var selectedIndex:int;

    /**
     *  The item that is currently selected. Setting the selectedItem property
     *  de-selects the currently selected item and selects the specified item.
     *
     *  Setting selectedItem to an item that is not in this component results in
     *  no selection, and selectedItem being set to undefined. If the selected
     *  item is removed, the selected item is set to undefined (if requireSelection
     *  = false or there are no remaining items) or the first item (if
     *  requireSelection = true and there is at least one item).
     *
     *  @default undefined
     */
    public var selectedItem:*;

    /**
     *  Specifies whether an item must always be selected.
     *  If the value is true, the selectedIndex property will always be
     *  set to a value between 0 and (dataProvider.length - 1), or -1 if there are
     *  no items.
     *
     *  @default false
     */
    public var requiresSelection:Boolean = false;

    //--------------------------------------------------------------------------
    //
    //  Methods
    //
    //--------------------------------------------------------------------------

    /**
     *  Called when an item is selected or deselected. 
     *  Subclasses must override this method to display the selection.
     *
     *  @param index The item index that was selected.
     *
     *  @param selected <code>true</code> if the item is selected, 
     *  and <code>false</code> if it is deselected.
     */
    protected function itemSelected(index:int, selected:Boolean):void;
}

}

Detailed Description


SkinnableDataContainer

The SkinnableDataContainer class is basically a Spark DataGroup with skinnable chrome. More precisely, it is a SkinnableComponent whose skin has a dataGroup. It has one SkinPart named dataGroup, and it facades the dataProvider, layout, viewport, and and item renderer functionality of the dataGroup skin part. See the API Description section for details. Because of this, SkinnableDataContainer has non-content children and is skinnable, while DataGroup can only contain the rendered data items.

API Description


SkinnableDataContainer

Most of the SkinnableDataContainer APIs are proxies to the dataGroup skin part. Details on these APIs can be found in the Spark DataGroup spec.

package spark.components
{

<a href="DefaultProperty%28%26quot%3BdataProvider%26quot%3B%29">DefaultProperty("dataProvider")</a>

class SkinnableDataContainer extends SkinnableContainerBase
{

// NOTE: SkinnableContainerBase extends SkinnableComponent
// SkinnableContainerBase handles enabling/disabling of children and 
// also an IViewport implementation needed for scrolling

    //--------------------------------------------------------------------------
    //
    //  Skin Parts
    //
    //--------------------------------------------------------------------------

    /**
     *  The DataGroup that displays the content of this component. The dataProvider,
     *  layout, itemRenderer, and itemRendererFunction properties of the
     *  component are assigned to this skin part.
     */
    <a href="SkinPart">SkinPart</a>
    public var dataGroup:DataGroup;

    //--------------------------------------------------------------------------
    //
    //  DataGroup property and method proxies
    //
    //  The remainder of the DataContainer API are direct proxies to the
    //  dataGroup SkinPart.
    //
    //  Details for these APIs can be found in the DataGroup class.
    //--------------------------------------------------------------------------

    //--------------------------------------------------------------------------
    //
    //  Properties .. proxies to dataGroup
    //
    //--------------------------------------------------------------------------

    public function get dataProvider():IList;
    public function set dataProvider(value:IList):void;

    public function get layout():LayoutBase;
    public function set layout(value:LayoutBase):void;

    public function get itemRenderer():IFactory;
    public function set itemRenderer(value:IFactory):void;

    public function get itemRendererFunction():Function;
    public function set itemRendererFunction(value:Function):void;

    public function get typicalItem():Object;
    public function set typicalItem(value:Object):void;

}

}

Prototype Work


An implementation of SkinnableDataContainer has been checked in. Work has been done on subclasses, ListBase and List. As more work gets done on the subclasses, some of that might be pushed into SkinnableDataContainer.

Compiler Work


None.

Web Tier Compiler Impact


None.

Flex Feature Dependencies


Spark DataGroup - SkinnableDataContainer has a very tight connection with the DataGroup class, and we must keep the API's in sync.

Spark Virtualization - This is mostly baked into DataGroup and layouts, but specced separately.

List - The list component, which extends SkinnableDataContainer, provides selection support.

ItemRenderer - Item Renderers are how data items are visualized.

Backwards Compatibility


Syntax changes

None. These are new classes.

Behavior

None. These are new classes.

Warnings/Deprecation

None.

Accessibility


N/A

Performance


These classes are bound by the performance of the DataGroup class.

Globalization


Not Applicable.

Localization


Compiler Features

None.

Framework Features

None.

Issues and Recommendations


QA


Related

Wiki: Flex 4
Wiki: Spark DataGroup
Wiki: Spark Virtualization

Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.