BGX Serialization Classes

Documentation for the Bgx Flexible List (Flash MX 2004)

Version 1.0.3 2005-02-05

Overview

Introduction
Deployment
Reference

Introduction

The Bgx Flexible List component provides list logic to create dynamic lists using virtually any MovieClip you like, giving you total freedom in the way your list items may look or behave.

Easy implementation

Simply assign any MovieClip as the clip to use for the list items. The component will automatically take care of repeating the item, scroll options etc.

To implement event handling you only have to:

place a button or hotspot called rowBtn in the MovieClip to define the area where rollOver and press events shall be received
place another MovieClip called bgClip on a background layer with four frames to handle rollover and selection effects

No implementation of further ActionScript is necessary, however the component automatically assigns the variables itemIndex and data to each item instance that can be used for custom functionality like presetting checkboxes etc.

TextFields named following a naming convention will automatically be bound to specified properties in the dataProvider.

Functionality

The BGX Flexible List provides most of the properties provided by the Macromedia List Component and some more, like:

horizontal repeat to create grid structures
multiple field names binding (like with the Datagrid Component)
the possibility to trigger rollover events externally, e.g. to highlight a list item when an external object is rolled over
others like moveItemUp, moveItemDown, removeSelected etc.

The component does not provide scrolling logic of its own but can easily be used with the Macromedia ScrollPane component.

Example Library

The component comes with a library of sample item clips that will be available from the Common Libraries after installation. Use this clips as-is or to start off your own customizations.

Deployment

The Bgx Flexible List component is delivered as MXP file and must be installed with the Macromedia Extensions Manager. After the installation, the actual List Component that will be available from the components panel and a library of sample itemClips will be available from Window>Other Panels>Common Libraries>Bgx List Item Samples.

To create a list using the Bgx Flexible List component you must either drag an instance to the stage and set the appropriate properties or, to use it within an instance of the ScrollPane component, must have a copy of the component in the library. You can find several examples of how to populate the Bgx Flexible List component within or without the ScrollPane component at http://www.bgxcomponents.com/flexibleListExamples.htm

Note: If you drag an instance of the component to the stage you will see only an icon marking the position. If you export the clip the icon will not be visible anymore.

Reference

Bgx Flexible List Component

Understanding the Bgx Flexible List Component
BgxFlexibleList class
Properties
Methods
Events
Keyboard Input

Understanding the Bgx Flexible List Component

The General Logic: itemClip and dataProvider structure

Note: The following tries to explain the concepts behind the Bgx Flexible List. If this appears too abstract to get you started immediately, try the examples at http://www.bgxcomponents.com/flexibleListExamples.htm

The Bgx Flexible List Component is basically a Class that can create vertical lists or lists with several horizontal repeats by creating repeated instances of another MovieClip, specified as the itemClip for the list.

The base for the number of replication builds a dataProvider that is an Array of Objects, each Object containing the data that shall be bound to the individual items. A simple example for such an Array would be the following:

var ListData = new Array();

for (var i = 1; i < 11; i ++)
{
var ListObj = new Object();

    if ( i == 1 || (i > 4 && i < 8) || i >= 9)
    {
        ListObj["icon"] = "IconPainting";
        ListObj["description"] = "Painting " + i;
        ListObj["ordercode"] = "PA/" + i;
    }
    else
    {
        ListObj["icon"] = "IconDrawing";
        ListObj["description"] = "Drawing " + i;
        ListObj["ordercode"] = "DR/" + i;
    }
    ListObj["price"] = i * 3 + ",00 €";
    ListObj["preview"] = "prev" + i + ".swf";
    ListData.push(ListObj);
}

If you define the example ListData Array as the dataProvider for a list instance, 10 instances of the assigned itemClip would be created, whereby the corresponding ListObj would be passed to each of these instances as the data upon which to build the item display.

Similar as with the Macromedia List component each item gets assigned a data property. But by default this is the entire Object (in our example a ListObj) associated with a list item instance. (You cannot have a simple String or a Number as the item data).

As you usually would use the Bgx Flexible List to create lists more complex than the standard List Component would allow, this has the advantage that you always have the whole range of data available that you might need. While our example is still quite basic, using just a flat Array of Objects, you could just as well use multilevel Arrays and complex Objects as the properties of the first level Objects.

Note: assigning the Object to the itemClip does not create a new instance of that data, it just means that the data property in the itemClip points towards a defined Object within your dataProvider. This has two implications:
a) there is no real increase in terms of Memory usage
b) if you make any modfications to the data e.g. changing a value when a CheckBox is clicked or a text entered in a TextField, this value will actually be written to your original Array that is used as dataProvider, meaning that e.g. in our sample the changed value of price on the 3rd list entry would be accessible as:

listInstance.getItemAt(2).data.price;

listInstance.dataProvider.getItemAt(2).price;

ListData[2].price;

But now lets see how this data can be used to actually define the display of a list item.

reference overview back to top

Built-in Databinding: TextFields and Icon

Other than with the Macromedia List component there is no concept of label with the Bgx Flexible List. As you would usually want to create more complex lists with Bgx Flexible List a single label field is not much use. However there is a way to automatically bind text to TextFields and to display a standard icon at the beginning of the item, that makes the Bgx Flexible List easy to use for often needed multi field lists.

If you want to use the built-in databinding mechanism for TextFields you simply have to add any number of TextFields to your itemClip and name them tb0, tb1, tb2, etc. They can be placed wherever you like.

You can then define, via the columnNames property of the list, properties of your data objects as the properties to use to populate these TextFields in order.

In our example you could use e.g.
listInstance.columnNames = ["description","price","ordercode"];
to display the value of the description property in the TextField named tb0, the value of the price property in the TextField named tb1 and so on.

Again you can find an example of that at http://www.bgxcomponents.com/flexibleListExamples.htm

Note: Strictly speaking there aren't necessarily columns in the Bgx Flexible List. The name columnNames was chosen to resemble the databinding used with the Macromedia DataGrid component.

To display an icon you must have a MovieClip with a defined linkage name in the library. You can then specify a property within your data Objects that refers to that linkage name (or names if you have more than one).

To display an icon you have to define which property of the data Objects holds the information for the icon to use. In our case you could use:

listInstance.iconField = "icon";

Also for that you can find examples at http://www.bgxcomponents.com/flexibleListExamples.htm

reference overview back to top

Custom Databinding: Accessing the data Object from within the itemClip

If you want more customized binding options you can access the data property from within the itemClip you use to basically do with it whatever you want. For instance: at http://www.bgxcomponents.com/flexibleListExamples.htm you can find examples of lists that use CheckBoxes (see also the CheckBox examples in the sample files that come with the component).

The itemClip for these examples contains one CheckBox named cbx. To automatically check/un-check the box when the list gets populated you can add the following line the first frame in the itemClip:

cbx.selected = (data.description.indexOf("Drawing") > -1);

The data property is passed on to the itemClip right at creation. It is instantly available, you do not have to retrieve e.g. the data for the list index from the list.

reference overview back to top

Understanding itemClips: rowBtn and bgClip

We have already mentioned the itemClip several times without really explaining what it is.

An itemClip can be any MovieClip in your library. It must have a linkage name defined. To use it as the itemClip for your list simply set the value of the itemClip property to the linkage name of the MovieClip you want, like:

listInstance.itemClip = "BgxListBasicCheckboxes";

We have already mentioned that an itemClip can contain TextFields named tbx0, tbx1,.. for easy databinding. Apart from that there are two further Objects that are expected by the List in an itemClip (but don't necessarily have to exist).

rowBtn

The first one is any kind of Button with the instance name rowBtn. In the samples that come with the components that is usually a transparent hotspot. The list component automatically assigns the necessary functions to trigger itemRollOver, itemRollOut and itemPress events to that button. The reason why those functions are not simply assigned to the itemClip as a whole is that you may not want e.g. the whole area of an item to be active. Maybe only a certain TextField or image shall have that functionality. In this case you can simply move the hotspot to the desired position in a layer above the object you want.

Another reason is that you may want to have objects above that rowBtn that shall not trigger the list events, like a CheckBox or a TextInput. By having a physical Button on a layer you can arrange the itemClip the way it suits you.

As mentioned the functionality of triggering the list events can also be assigned to other Objects by calling the triggerItemPress, triggerItemRollOver and triggerItemRollOut functions of the list. The list itself is accessible as the _parent of the itemClip.

Have a look e.g. at the BgxListBasicCheckboxes example from the Sample Library which has no hotspot but assigns the trigger functions to a CheckBox instead:

cbx.onRollOver = _parent.triggerItemRollOver(itemIndex);
cbx.onRollOut = _parent.triggerItemRollOut(itemIndex);
cbx.onPress = _parent.triggerItemPress(itemIndex);

bgClip

The other Object that is expected is a four frame MovieClip with frames labeled "default", "selected", "rollover" and "selectedover". There must be a stop() action in the first frame. Each of this frames can contain any kind of code or graphics that modify the appearance of the itemClip. This can be a simple background graphic or code to change the text color of text fields, load an image etc.

The list component will send this bgClip to the appropriately labeled frame when state changing events occur and thus trigger the change in the appearance of the itemClip.

While you can do very sophisticated things with that mechanism, the mechanism itself is deliberately simple, allowing you to quickly and easily create a library of re-usable effects without having to modify and deploy e.g. CellRenderer classes. As the bgClip is another MovieClip various combinations of itemClips and bgClips can be used. In fact this is how the Sample Library is built.

reference overview back to top

Scrolling

While the Bgx Flexible List itself does not provide its own scroll mechanism it can easily be used with the Macromedia ScrollPane component. You can find an example implementation at http://www.bgxcomponents.com/flexibleListExamples.htm

reference overview back to top

Event handling

The change, itemPress, itemRollOver and itemRollOut event all return an eventObject to the assigned event handler that contains the following properties that point directly to the itemClip instance:

eventObject.item:MovieClip
a reference to the list item on which the event occurred, this is directly your MovieClip. Accessible this way you can do with it what you want.

eventObject.itemIndex:Number
a reference to the index of the item on which the event occurred

eventObject.itemData:Object
a reference to the data object of the item on which the event occurred

You find an example of how to catch and process events at http://www.bgxcomponents.com/flexibleListExamples.htm#app2

reference overview back to top

BgxFlexibleList class

Inheritance: MovieClip > UIObject class > UIComponent class > BgxFlexibleList

ActionScript Class Name: bgx.BgxFlexibleList

To reference the BgxFlexibleList component e.g. in a class file use the following:

import bgx.BgxFlexibleList;

class myClass
{
var myBgxFlexibleList:BgxFlexibleList;
}

Properties

Property	Value (defaults in bold)	Description
allowKeySelect	Boolean Default: true	If set to true the UP, DOWN, LEFT, RIGHT and HOME key can be used to select list items when the list has focus. See Keyboard Input.
columnNames	Array Default: undefined	Array of strings that identify the properties that shall be bound to the default text fields. See Built-in Databinding
dataProvider	Array Default: undefined	Array of Objects on base of which the list gets populated. Setting the value of the dataProvider property will trigger the creation of the list items. See General Logic
enabled	Boolean Default: true	If set to false selection is disabled for the list instance. Note: there is no built-in graphical state for a disabled list. But you can set one when setting enabled to false e.g. listInstance.enabled = false; listInstance._alpha = 50;
horizontalRepeat	Number (Integer > 1) Default: 1	Defines how many list item instances shall be drawn horizontally before adding the next row.
hRepeatOffset	Number Default: 60	Horizontal equivalent of rowHeight. Defines in pixels how far apart list items are spaced horizontally when horizontalRepeat > 1.
hScrollPolicy	String "on", "off" or "auto" Default: "off"	The horizontal scroll policy that should be applied to the lists parent ScrollPane. Only applicable when the list is used within a ScrollPane.
iconField	String Default:""	Identifies the property within the Object that is assigned to each item that holds the String value, identifying a linkage name of a MovieClip that should be displayed as icon. See Built-in Databinding
itemClip	String Default: "BgxDefaultRecord"	The linkage name of the MovieClip that shall be used as the item template for the current list. See General Logic
length	Number read only	The number of items in the list.
multipleSelection	Boolean Default: true	If true multiple items can be selected.
rowHeight	Number Default: 22	Defines in pixels how far list items will be spaced apart vertically.
selectedIndices	Array Default: undefined	Numeric Array listing the currently selected indices or null if no item is selected. Assigning a value to the selectedIndices will select all indices in the array. E.g.: listInstance.multipleSelection = true; listInstance.selectedIndices = [0,2,7]; If multipleSelection is set to false setting selectedIndices will have no effect.
selectedIndex	Number Default: undefined	Number identifying the currently selected index or null if no item is selected. Assigning a value to the selectedIndex will move the selection to the item with that index. listInstance.selectedIndex = 7;
selectedItem	MovieClip read only	A reference to the currently selected item or the item that was selected last if more than one is currently selected.
selectedItems	Array of MovieClip read only	An Array listing all the currently selected itemClip instances.
vScrollPolicy	String "on", "off" or "auto" Default: "auto"	The vertical scroll policy that should be applied to the lists parent ScrollPane. Only applicable when the list is used within a ScrollPane.

reference overview back to top

Methods

Method	Parameters	Returns	Description
addItem()	object:Object an Object to be appended to the list	Nothing	Adds the submitted Object at the end of the list. Example: var ListObj = new Object(); ListObj["icon"] = "IconPainting"; ListObj["description"] = "Painting 12"; ListObj["ordercode"] = "PA/12"; listInstance.addItem(ListObj);
addItemAt()	index:Number specifies the index of the target item. object:Object the Object to add at the indicated position	Nothing	Adds the submitted Object at the specified index. Example: var ListObj = new Object(); ListObj["icon"] = "IconPainting"; ListObj["description"] = "Painting 12"; ListObj["ordercode"] = "PA/12"; listInstance.addItemAt(3,ListObj);
deselectAll()	none	Nothing	Deselects all currently selected items. Example listInstance.deselectAll();
getItemAt(index)	index:Number specifies the index of the target item.	A reference to the itemClip instance at the specified index	Returns a reference to the itemClip instance at the specified index Example listInstance.getItemAt(3);
moveItemDown()	index:Number specifies the index of the target item.	Nothing	Moves the item at the specified index down in the list. The following example moves the currently selected item down in the list and re-selects it at the new position: var indexToMove = listInstance.selectedIndex; listInstance.moveItemUp(indexToMove); listInstance.selectedIndex = indexToMove + 1;
moveItemUp()	index:Number specifies the index of the target item.	Nothing	Moves the item at the specified index up in the list. The following example moves the currently selected item up in the list and re-selects it at the new position: var indexToMove = listInstance.selectedIndex; listInstance.moveItemUp(indexToMove); listInstance.selectedIndex = indexToMove - 1;
redraw()	none	Nothing	Redraws the list. The following adds a new Object to the dataProvider and redraws the list to display it: var ListObj = new Object(); ListObj["icon"] = "IconPainting"; ListObj["description"] = "Painting 12"; ListObj["ordercode"] = "PA/12"; listInstance.dataProvider.push(ListObj); listInstance.redraw();
removeAll()	none	Nothing	Removes all items from the list. Example listInstance.removeAll();
removeItemAt()	index:Number specifies the index of the target item.	Nothing	Removes the item at the specified index . Example listInstance.removeItemAt(3);
removeSelected()	none	Nothing	Removes the currently selected items from the list. Example listInstance.removeSelected(3);
replaceItemAt()	index:Number specifies the index of the target item. object:Object the Object with which to replace the current one at the same position	Nothing	Replaces the Object at the specified index with the submitted one. Example: var ListObj = new Object(); ListObj["icon"] = "IconPainting"; ListObj["description"] = "Painting 12"; ListObj["ordercode"] = "PA/12"; listInstance.replaceItemAt(3,ListObj);
selectAll()	none	Nothing	Selects all items in the list. Example listInstance.selectAll();
setScrollPosition()	index:Number specifies the index of the target item.	Nothing	Scrolls to the specified index if the list is used within a ScrollPane. The following example will display the rollover highlight over the item with the index 8 and scroll to it when the user presses a button. On release the scroll position is reset to the one of the currently selected item. rowBtn.onPress = function() { listInstance.triggerItemRollOver(8); listInstance.setScrollPosition(8); } rowBtn.onRelease = function() { listInstance.triggerItemRollOut(8); listInstance.setScrollPosition(listInstance.selectedIndex); }
triggerItemPress(index)	index:Number specifies the index of the target item.	Nothing	Selects the item with the specified index. An itemPress event is usually triggered by the default rowBtn hotspot. You can use triggerItemPress to trigger that event from outside the component or from any other object within the itemClip. Use triggerItemPress rather than setting the selectedIndex property if you want to notify the itemPress event, not just the change event. Example listInstance.triggerItemPress(8);
triggerItemRollOver(index)	index:Number specifies the index of the target item.		Triggers the itemRollOver event for the specified index. An itemPress event is usually triggered by the default rowBtn hotspot. You can use triggerItemRollOver to trigger that event from outside the component or from any other object within the itemClip. The following example will display the rollover highlight over the item with the index 8. rowBtn.onPress = function() { listInstance.triggerItemRollOver(8); }
triggerItemRollOut(index)	index:Number specifies the index of the target item.		Triggers the itemRollOut event for the specified index. An itemPress event is usually triggered by the default rowBtn hotspot. You can use itemRollOut to trigger that event from outside the component or from any other object within the itemClip. The following example will remove the rollover highlight over the item with the index 8. rowBtn.onRelease = function() { listInstance.triggerItemRollOut(8); }

reference overview back to top

Events

Event

Parameters returned

Description

draw

eventObject.target = a reference to the list component

Event invoked when the list was successfully populated or re-drawn as result of one of the following:

setting the value of the dataProvider property
calling any of the following methods: removeAll, removeItemAt, removeSelected, addItem, addItemAt, replaceItemAt, moveItemDown, moveItemUp, redraw

Example:

var listenerObject = new Object();
listenerObject.draw = function(eventObject)
{
// your code here, e.g.:
trace(eventObject.target);
}
listInstance.addEventListener("draw", listenerObject)

change

eventObject.target:BgxFlexibleList
a reference to the list component

eventObject.item:MovieClip
a reference to the list item (= the instance of the MovieClip set as itemClip of the list) on which the event occurred

eventObject.itemIndex:Number
a reference to the index of the item on which the event occurred

eventObject.itemData:Object
a reference to the data object of the item on which the event occurred

Event invoked when the selection of the list items changes as result of one of the following:

user mouse interaction
calling any of the following methods: triggerItemPress, removeSelected
setting the value of selectedIndex

Note: use the itemPress event instead of change if you want to detect if the user changed the selection by mouse click rather than an Actionscript change by setting the selectedIndex property...

Example:

var listenerObject = new Object();
listenerObject.change = function(eventObject)
{
    // your code here, e.g.:
    trace(eventObject.target);
    trace(eventObject.item);
    trace(eventObject.itemIndex);
    trace(eventObject.itemData);
}
listInstance.addEventListener("change", listenerObject)

focusIn

eventObject.target:BgxFlexibleList
a reference to the list component. If the component is loaded within a ScrollPane the reference will be to the spContentHolder of the ScrollPane instance.

Event invoked when the list receives focus. Inherited from UIComponent class .

Example:

var listenerObject = new Object();
listenerObject.focusIn = function(eventObject)
{
    // your code here, e.g.:
    trace(eventObject.target);

}
listInstance.addEventListener("focusIn", listenerObject)

focusOut

eventObject.target:BgxFlexibleList
a reference to the list component. If the component is loaded within a ScrollPane the reference will be to the spContentHolder of the ScrollPane instance.

Event invoked when the list loses focus. Inherited from UIComponent class .

Example:

var listenerObject = new Object();
listenerObject.focusOut = function(eventObject)
{
    // your code here, e.g.:
    trace(eventObject.target);

}
listInstance.addEventListener("focusOut", listenerObject)

itemPress

eventObject.target:BgxFlexibleList
a reference to the list component

eventObject.item:MovieClip
a reference to the list item (= the instance of the MovieClip set as itemClip of the list) on which the event occurred

eventObject.itemIndex:Number
a reference to the index of the item on which the event occurred

eventObject.itemData:Object
a reference to the data object of the item on which the event occurred

Event invoked when the selection of the list items changes as result of one of the following:

user mouse interaction
calling the triggerItemPress method

Note: use the change event instead of itemPress if you want to detect also changes in selection that occurred by changes triggered by Actionscript rather than mouse interaction.

Example:

var listenerObject = new Object();
listenerObject.itemPress = function(eventObject)
{
    // your code here, e.g.:
    trace(eventObject.target);
    trace(eventObject.item);
    trace(eventObject.itemIndex);
    trace(eventObject.itemData);
}
listInstance.addEventListener("itemPress", listenerObject)

itemRollOver

eventObject.target:BgxFlexibleList
a reference to the list component

eventObject.item:MovieClip
a reference to the list item (= the instance of the MovieClip set as itemClip of the list) on which the event occurred

eventObject.itemIndex:Number
a reference to the index of the item on which the event occurred

eventObject.itemData:Object
a reference to the data object of the item on which the event occurred

Event invoked as result of one of the following:

the user rolls the mouse over an item
calling the triggerItemRollOver method

Example:

var listenerObject = new Object();
listenerObject.itemRollOver = function(eventObject)
{
    // your code here, e.g.:
    trace(eventObject.target);
    trace(eventObject.item);
    trace(eventObject.itemIndex);
    trace(eventObject.itemData);
}
listInstance.addEventListener("itemRollOver", listenerObject)

itemRollOut

eventObject.target:BgxFlexibleList
a reference to the list component

eventObject.item:MovieClip
a reference to the list item (= the instance of the MovieClip set as itemClip of the list) on which the event occurred

eventObject.itemIndex:Number
a reference to the index of the item on which the event occurred

eventObject.itemData:Object
a reference to the data object of the item on which the event occurred

Event invoked when the selection of the list items changes as result of one of the following:

the user rolls the mouse away from an item
calling the triggerItemRollOut method

Example:

var listenerObject = new Object();
listenerObject.itemRollOut = function(eventObject)
{
    // your code here, e.g.:
    trace(eventObject.target);
    trace(eventObject.item);
    trace(eventObject.itemIndex);
    trace(eventObject.itemData);
}
listInstance.addEventListener("itemRollOut", listenerObject)

reference overview back to top

Keyboard Input

Key	Description
Control	Allows multiple noncontiguous selections and deselections when pressed while clicking on list items.
Down Arrow	If horizontalRepeat = 1 Selects next item down, if horizontalRepeat > 1 Selects the item in the same column in the next row down, (allowKeySelect must be set to true)
Home	Selects first item in list (allowKeySelect must be set to true)
Left Arrow	If horizontalRepeat > 1 Selects the item with the next lower index, (allowKeySelect must be set to true)
Shift	Allows for contiguous selection when pressed while clicking on list items.
Right Arrow	If horizontalRepeat > 1 Selects the item with the next higher index, (allowKeySelect must be set to true)
Up Arrow	If horizontalRepeat = 1 Selects next item up, If horizontalRepeat > 1 Selects the item in the same column in the next row up, (allowKeySelect must be set to true)

reference overview back to top