Gumbo Group - Functional and Design Specification

<Skin xmlns...>

    <!-- This group is the background graphics for the button skin. -->
    <Group left="0" right="0" top="0" bottom="0">
        <Rect radiusX="4" radiusY="4" left="0" top="0" right="0" bottom="0">
            <stroke> ... </stroke>
            <fill> ... </fill>
        </Rect>
        <Rect radiusX="3" radiusY="3" left="1" top="1" right="1" bottom="1">
            <fill> ... </fill>
        </Rect>
    </Group>

    <Label horizontalCenter="0" verticalCenter="0" text="{component.label}" />
</Skin>

<Skin xmlns...>

    <!-- This group is the header for the panel. Note that the "content"
         property for this group is bound to the "header" property of the Panel.
         Since Group content can be visual or data, this allows any arbitrary
         content to be inside a Panel header. -->
    <Group id="header" left="0" right="0" top="0" height="30"
           layout="flex.layout.HorizontalLayout" 
           content="{component.header}" />

    <!-- This group is the main content area for the panel. -->
    <Group id="content" left="5" top="35" right="5" bottom="35"
           layout="flex.layout.VerticalLayout"
           content="{component.content}" />

    <!-- This group is the footer for the Panel. -->
    <Group id="footer" left="0" right="0" bottom="0" height="30"
           layout="flex.layout.HorizontalLayout" 
           content="{component.footer}" />
</Skin>

<!-- This is the item renderer definition. The group data item
     is bound into the renderer. -->
MyItemRenderer.mxml
<Group layout="flex.layout.HorizontalLayout">
    <Label text="{data.lastName}, {data.firstName}" />
    <Image source="{data.imageURL}" />
</Group>

<!-- This group contains raw data content. It uses an itemRenderer to
     display the data. -->
<Group itemRenderer="MyItemRenderer">
    <Object firstName="Chet" lastName="Haase" imageUrl="http://..." />
    <Object firstName="Corey" lastName="Lucier" imageUrl="http://..." />
    <Object firstName="Ely" lastName="Greenfield" imageUrl="http://..." />
    <Object firstName="Evtim" lastName="Georgiev" imageUrl="http://..." />
    <Object firstName="Glenn" lastName="Ruehle" imageUrl="http://..." />
</Group>

private function myItemRendererFunction(item:*):IFactory
{
// "employee" and "contractor" get special renderers.
if (item.status == "employee")
return employeeItemRenderer;
else if (item.status == "contractor")
return contractorItemRenderer;

// everyone else gets the default renderer.
return defaultItemRenderer;
}

package flex.core
{

/**
*  Dispatched prior to the group's content being changed. This is only
*  dispatched when all content of the group is changing.
*/
[Event(name="contentChanging", type="flash.events.Event")]

/**
*  Dispatched after the group's content has changed. This is only
*  dispatched when all content of the group has changed.
*/
[Event(name="contentChanged", type="flash.events.Event")]

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

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

class Group extends UIComponent implements IGraphicElementHost
{
//--------------------------------------------------------------------------
//
//  Properties
//
//--------------------------------------------------------------------------

/**
*  Flag that specifies whether or not an item renderer should always be
*  created for each item. When true, an item renderer is always created
*  for each item, even if the item is a visual element.
*
*  @default false
*/
public var alwaysUseItemRenderer:Boolean;

/**
*  Content for this Group.
*
*The content can be an Array, Vector, IList, or
*  a single item. The content items can be any type.

*
*  @default undefined
*
*  @see #itemRenderer
*  @see #itemRendererFunction
*/
public function get content():*;
public function set content(value:*):void;

/**
*  Renderer to use for data items. The class must
*  implement theIDataRendererinterface.
*  TheitemRendererFunctionproperty,
*  if defined, takes precedence over this property.
*
*  @default null
*/
public var itemRenderer:IFactory;

/**
*  Function that returns an item renderer for a specific item.
*  The signature of the function is:

*function itemRendererFunction(item:*):IFactory
*
*  @default null
*/
public var itemRendererFunction:Function;

/**
*  Layout for this Group.
*
*The layout object is responsible for measurement
*  and layout of the Group contents.

*
*  @default flex.layout.BasicLayout
*
*  @see ILayout
*/
public function get layout():Class;
public function set layout(value:Class):void;

//--------------------------------------------------------------------------
//
//  Content management
//
//  The properties and methods in this section mimic the child management
//  APIs available in the flash class DisplayObjectContainer.
//
//--------------------------------------------------------------------------

//----------------------------------
//  Item iteration
//----------------------------------

/**
*  The number of items in this group.
*
*  @return The number of items in this group
*/
public function get numItems():int;

/**
*  Gets thenth item in the Group.
*
*  @param index The index of the item to retrieve.
*
*  @return The item at the specified index, or null if the item does not exist.
*/
public function getItemAt(index:int):*;

//----------------------------------
//  Item addition
//----------------------------------

/**
*  Adds an item to this Group. The item is added after all other
*  items.
*
*  @param item The item to be added to the Group.
*
*  @return The item that was added to the Group.
*/
public function addItem(item:*):*;

/**
*  Adds an item to this Group. The item is added at the index
*  specified.
*
*  @param item The item to be added to the Group.
*  @param index The index to add the item at.
*
*  @return The item that was added to the Group.
*/
public function addItemAt(item:*, index:int):*;

//----------------------------------
//  Item removal
//----------------------------------

/**
*  Removes an item from this Group.
*
*  @param item The item to be removed from the Group.
*
*  @return The item removed from the Group.
*/
public function removeItem(item:*):*;

/**
*  Removes an item at a specified index from this Group.
*
*  @param index The index of the item to remove.
*
*  @return The item removed from the Group.
*/
public function removeItemAt(index:int):*;

//----------------------------------
//  Item index
//----------------------------------

/**
*  Gets the zero-based index of a specific item.
*
*  @param item Reference to item whose index to get.
*
*  @return Number between 0 and (numItems - 1), or -1 if
*          the item is not in this Group.
*/
public function getItemIndex(item:*):int;

/**
*  Sets the zero-based index of a specific item.
*
*  @param item The item whose index is being set.
*  @param index The new zero-based index for the item.
*/
public function setItemIndex(item:*, index:int):void;

//----------------------------------
//  Item swapping
//----------------------------------

/**
*  Swaps the index of the two specified items. All other items
*  remain in the same index position.
*
*  @param item1 The first item.
*  @param item2 The second item.
*/
public function swapItems(item1:*, item2:*):void;

/**
*  Swaps the index of the two specified items. All other items
*  remain in the same index position.
*
*  @param index1 The index of the first item.
*  @param index2 The index of the second item.
*/
public function swapItemsAt(index1:int, index2:int):void;

//--------------------------------------------------------------------------
//
//  Content to renderer mapping
//
//--------------------------------------------------------------------------

/**
*  Returns the instance of the renderer for the specified item. If the
*  the specified item is a visual item (component or IGraphicElment),
*  the item itself is returned.
*
*  @param item The item whose renderer is to be returned.
*
*  @return The renderer instance for the specified item. If the item
*          is a subclass of DisplayObject or IGraphicElement, the item
*          itself is returned.
*/
public function getItemRenderer(item:*):*;

/**
*  Returns the item associated with the specified renderer.
*
*  @param renderer The renderer whose item you want to retrieve.
*
*  @return The item associated with the specified renderer.
*/
public function getRendererItem(renderer:*):*;

//--------------------------------------------------------------------------
//
//  Layout item iteration
//
//  Iterators used by Layout objects. For visual items, the layout item
//  is the item itself. For data items, the layout item is the item renderer
//  instance that is associated with the item.
//
//--------------------------------------------------------------------------

/**
*  The number of layout items in this Group. Typically this is the same
*  as the number of items in the Group.
*/
public function get numLayoutItems():int;

/**
*  Gets thenth layout item in the Group. For visual items, the
*  layout item is the item itself. For data items, the layout item is the
*  item renderer instance that is associated with the item.
*
*  @param index The index of the item to retrieve.
*
*  @return The layout item at the specified index.
*/
public function getLayoutItemAt(index:int):Object;

//--------------------------------------------------------------------------
//
//  Protected methods
//
//--------------------------------------------------------------------------

/**
*  Create the visual representation for the item, if needed.
*
protected function createVisualForItem(item:*):DisplayObject;

/**
*  Called when an item has been added to this Group.
*
*  @param item The item that was added.
*  @param index The index where the item was added.
*/
protected function itemAdded(item:*, index:int):void;

/**
*  Called when an item is about to be removed from this Group.
*
*  @param index The index of the item that is being removed.
*/
protected function itemRemoved(index:int):void;
}

}