Gumbo ItemsComponent and Selector - Functional and Design Specification

public class Panel extends ItemsComponent {

    // The content, layout, and itemRenderer properties are inherited from ItemsComponent. 
    // These are the main content for the Panel. 

    // Skin parts. The Panel class has two new parts: headerGroup and footerGroup. These
    // correspond to the header/footer of the Panel. The contentGroup part represents the
    // main content area.

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

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

    // Content for the header and footer
    public var header:*;
    public var footer:*;

    // This function is called when the skin part is loaded and assigned. 
    override protected function partAdded(partName:String, instance:*):void
    {
        // Assign the content to the header and footer. The main content
        // assignment is done in the superclass (ItemsComponent)
        switch (partName)
        {
            case "headerGroup":
                headerGroup.content = header;
                break;

            case "footerGroup":
                footerGroup.content = footer;
                break;

            default:
                super.partAdded(partName, instance);
                break;
        }
    }
}

public class MediaBrowser extends SkinnableComponent {
    
    // The MediaBrowser can switch between Music, Photos, and Video. 
    // The component implementation doesn't care how the switching is 
    // done. It could be a set of tabs, a combobox, or a set of radio buttons;
    // as long as it is a subclass of Selector.
    [SkinPart]
    public var mediaTypeSelector: Selector;

    private static const mediaTypes:Array = ["Music", "Photos", "Video"];

    override protected function partAdded(partName:String, instance:*):void
    {
        if (instance == mediaTypeSelector)
        {
            // Set the content of the type selector
            mediaTypeSelector.content = mediaTypes;

            // Add a selectionChanged listener to the selector
            mediaTypeSelector.addEventListener("selectionChanged", 
                  mediaTypeSelector_selectionChangedHandler);
        }
        else
        {
            super.partAdded(partName, instance);
        }
    }

    private function mediaTypeSelector_selectionChangedHandler(event:Event):void
    {
        // Show the selected media
        showMedia(mediaTypeSelector.selectedItem);
    }
 
    private function showMedia(mediaType:String):void
    {
        ...
    }
}

package flex.component
{

/**
 *  Dispatched when an item is added to the component.
 *  event.relatedObject is the item that was added.
 */
[Event(name="itemAdd", type="flex.events.ItemExistenceChangedEvent")]

/**
 *  Dispatched when an item is removed from the component.
 *  event.relatedObject is the item that was removed.
 */
[Event(name="itemRemove", type="flex.events.ItemExistenceChangedEvent")]

[DefaultProperty("content")]

class ItemsComponent extends SkinnableComponent
{
    //--------------------------------------------------------------------------
    //
    //  Skin Parts
    //
    //--------------------------------------------------------------------------

    /**
     *  The Group that displays the content of this component. The content,
     *  layout, itemRenderer, and itemRendererFunction properties of the 
     *  component are assigned to this skin part.
     */
    [SkinPart]
    public var contentGroup:Group;

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

    //--------------------------------------------------------------------------
    //
    //  Properties
    //
    //--------------------------------------------------------------------------

    public var content;
    public var layout;
    public var itemRenderer;
    public var itemRendererFunction;


    //--------------------------------------------------------------------------
    //
    //  Content management 
    //
    //  These are proxies to the properties and methods on the contentGroup
    //  skin part, provided for convenience. They are equivalent to accessing 
    //  the contentGroup part directly. For example, addItem(item); and 
    //  contentGroup.addItem(item); do the same thing. 
    //--------------------------------------------------------------------------

    public function get numItems();
    public function getItemAt();
   
    public function addItem();
    public function addItemAt();

    public function removeItem();
    public function removeItemAt();

    public function getItemIndex();
    public function setItemIndex();

    public function swapItems();
    public function swapItemsAt();
}

}

package flex.component {

/**
 *  Dispatched when the selection is going to change. Calling preventDefault()
 *  on the event will prevent the selection from changing.
 */
Event(name="selectionChanging", type="mx.events.IndexChangeEvent")]

/**
 *  Dispatched after the selection has changed. 
 */
[Event(name="selectionChanged", type="mx.events.IndexChangeEvent")]

public class Selector extends ItemsComponent
{
    //--------------------------------------------------------------------------
    //
    //  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 
     *  (numItems - 1). If items 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 (numItems - 1), or -1 if there are
     *  no items.
     *
     *  @default false
     */
    public var requiresSelection:Boolean = false;

    //--------------------------------------------------------------------------
    //
    //  Methods
    //
    //--------------------------------------------------------------------------
    
    /**
     *  Called when an item is selected or de-selected. Subclasses must override
     *  this method to display the selection.
     */
    protected function itemSelected(item:Object, selected:Boolean):void;
}

}