SmartFoxBits and the mCOM Flash components

The SmartFoxBits components' user interface is based on the widely appreciated Metaliq Components, also known as mCOM components.
The decision of relying on third-party UI components as the foundation of the SmartFoxBits has been taken to speed up development process, without having to "reinvent the wheel". In particular, the choice of adopting the mCOM components as an alternative to the standard Flash V2 components is due to the benefits they provide: smaller filesize, reduced CPU usage, simplified skinning system and API that in most cases mirrors the V2 components API.

This document provides a startup guidance to components' text styling, skinning and row rendering. Simplified and advanced examples are provided together with the SmartFoxBits packs (check this paragraph for more info).
For more detailed explanations, please refer to the original mCOM documentation following the provided links.

Vegetabled skin
An advanced skin example provided with the SmartFoxBits Community Edition pack
(includes customized text styling and row renderers)

Text styling

Basic text styling is supported by all the mCOM components. The following text styles can be set:

• fontFamily:String
  The font face applied to the text
• fontSize:Number
  The font size applied to the text
• fontColor:Number
  The color applied to the text
• fontWeight:String (normal / bold)
  Whether to display text as bold or not
• fontStyle:String (normal / italic)
  Whether to display text as italicized or not
• embedFonts:Boolean
  Whether to embed fonts or not

Text styles can be applied on a per instance basis or globally to all components. To apply styles to specific components, you can use the .setInstanceStyle method:

// In this example, chatBox_mc is the instance name of the SmartFoxBits' ChatBox
// The chatBox_mc.chatTextArea property returns a reference to the mCOM TextArea component
 
import com.metaliq.controls.TextArea
 
var ta:TextArea = chatBox_mc.chatTextArea
ta.setInstanceStyle("fontFamily", "Comic Sans MS")
ta.setInstanceStyle("fontSize", 14)
ta.setInstanceStyle("fontWeight", "bold")

Styles can also be applied globally using the UIObject.setStyle method:

import com.metaliq.controls.UIObject
 
UIObject.setStyle("fontFamily", "Comic Sans MS")
UIObject.setStyle("fontSize", 14)
UIObject.setStyle("fontWeight", "bold")

When global styles are applied, any additional styles set on specific instances will always override styles set globally.

For more fine grained control over text styles on a component, you can also use the .textFormat property of the components. This property allows you to set a TextFormat directly on the component:

import com.metaliq.controls.TextArea
 
var ta:TextArea = chatBox_mc.chatTextArea
 
var tf:TextFormat = new TextFormat()
tf.font = "Comic Sans MS"
tf.size = 14
tf.bold = true
 
ta.textFormat = tf

Skinning mCOM components is quite straightforward, thanks to the following features:

• skins can be purely graphical, purely code, or a combination of both;
• a simple skin interface has been implemented, which provides support for sizing, enabling, mouse interaction states, and drawing custom focus borders;
• skins can be assigned on a per instance basis, or globally on all instances of a component type.

Each skin must be set up as a MovieClip symbol. This symbol may or may not be linked to an AS2 class. Linking symbols to classes provide more fine-grained control over the skin.

All skins that ship with mCOM components extend a base class (com.metaliq.skins.BaseBackground). The base class implements the following interface:

• setSize(p_w:Number, p_h:Number):Void
  Called when the component is sized; it stores the size internally and calls the draw method.
• setState(p_state:String):Void
  Called when a state change occurs in the component; it stores the state internally and calls the draw method.
• setFocus(p_foc:Boolean):Void
  Called when the component gains/loses focus; it stores the focus Boolean internally and calls the draw method.
• width:Number
  Sets/gets the width value of the skin.
• height:Number
  Sets/gets the height value of the skin.
• useFocusRect:Boolean
  Indicates whether the default focus border will be used as the focus border (true) or whether the skin will draw it's own focus border (false).
• draw():Void
  Visually lays out the background for the component; it is overriden by the classes extending the base class.

The simplest way to apply skins globally is to create a skin symbol that uses the same linkage ID as the corresponding mCOM skin. The following are the linkage ID names for all components used in the SmartFoxBits:

Alternatively, skins can be applied to individual components via the background property (or headerBackground for the Window component). This property can be set to the linkage ID of the custom skin:

// In this example, loginBox_mc is the instance name of the SmartFoxBits' LoginBox
// The loginBox_mc.loginButton property returns a reference to the mCOM Button component
 
import com.metaliq.controls.Button
 
var bt:Button = loginBox_mc.loginButton
bt.background = "customSkinLinkageID"

Implementation

There are three ways of implementing a skin class. All require the creation of a movie clip symbol.

• Simple skin
  You only need to create a background graphic within your .fla library and set the movie clip's linkage appropriately (see the table above). The framework will then resize it automatically when the component instance is resized (via _width and _height properties).
• Skin with child clips
  Create a background MovieClip containing the required child clips, then create a background class: you can create it from scratch, implementing all the methods required by the mCOM framework, or you can simply extend the base class (com.metaliq.skins.BaseBackground) described above. You don't need to have the base class source file, as Flash retrieves it form the SmartFoxBits SWC files. Inside the class' draw method you can manage the positioning/sizing of the various child clips. This allows you to create graphically complex backgrounds.
• Skin using drawing API
  Similarly to the previous implementation, once the background clip and class have been created, you can implement the draw method so that it uses the drawing API to draw a background with the appropriate size.

Setting size

When a component is sized, the component checks to see whether it's background class implements a setSize method. If it does, it leaves the sizing up to the background class by calling setSize(p_w, p_h) on it, and passing in width (p_w) and height (p_h) values. If you extend the mCOM base background class, you just need to implement the draw method appropriately.

If the background class doesn't exist or does not implement a setSize method, the component sizes the background by setting it's _width and _height properties to the newly set values.

States

Some components support the display of different states based on mouse interaction with the component. The common mouse states used in the components are: up, over and down. For components such as Button, which implements the ability to be toggled, there are an alternate set of states: trueUp, trueOver, trueDown, falseUp, falseOver and falseDown.

All background classes can support a disabled state when the value of the component's enabled property is set to false. When enabled is set to true, the state is set to up.
For components such as Button, which implements the ability to be toggled, there are an alternate set of states: falseUp, falseDisabled, trueUp and trueDisabled.

Check the Button skinning example in the links section at the bottom of this page.

Setting states

When a component's state changes, it checks to see whether the background class implements a setState method. If it does, the component calls setState(p_state) on the background and passes in the appropriate state string and allows the background to take care of setting the visual state. If you extend the mCOM base background class, you just need to implement the draw method appropriately.

If no setState method is implemented, the component will call a gotoAndStop(p_state) on the background. In this case, the background movie clip needs to have frames labeled with the same names as the names of the states listed above. If no frame exists with a label corresponding to the new state, the command fails silently and there is no visual change in the component.

Implementing the draw method

All of the default background classes that ship with mCOM extend com.metaliq.skins.BaseBackground, and it is recommended that any custom background classes also extend BaseBackground. BaseBackground implements setSize, setState, and setFocus so you will not have to implement those in your background classes. Each of these methods set private properties and then call the draw method. The code that updates the visual display of the background should be contained within this method.

The draw method visually lays out the background for the component. In order to properly draw the background, you will need to use the following properties (please notice that width and height properties do not have the underscore char in their names):

• width:Number
  Width of the background.
• height:Number
  Height of the background.
• state:String
  The current state of the background (see the table above and the States paragraph for state names).
• focused:Boolean
  Whether the background should draw the focus highlight symbol (a focus rectangle, for example).

You can use conditional statements to draw different visual appearances based on the state and focused properties of the background class.

Some SmartFoxBits (for example RoomList and UserList) use a slightly modified version of the mCOM List component, called AdvancedList. This component adds some features to the mCOM List component, but its rowRenderer system for displaying rows was not changed. This system implements a "rowRenderer", which is a MovieClip symbol that is linked to a class with a specific interface.

To apply a rowRenderer to a list component inside a SmartFoxBit, you have to set the rowRenderer property to the linkage ID of your custom renderer:

// In this example, roomList_mc is the instance name of the SmartFoxBits' RoomList
// The roomList_mc.roomsList property returns a reference to the AdvancedList component
// (evolution oof the mCOM List component)
 
import com.metaliq.controls.AdvancedList
 
var al:AdvancedList = roomList_mc.roomsList
al.rowRenderer = "customRowRendererLinkageID"

The following is the API for the default rowRenderer used by the SmartFoxBits' RoomList and UserList components:

• setValue(p_item:Object, p_selected:Boolean):Void
  This is called on the rowRenderer whenever the data in the display is updated (via change in dataProvider, or scrolling of the AdvancedList - when the useSmartList property is set to true). It is passed the item object associated with the List item to display (ie. label, data, etc.), and a Boolean indicating whether the item is selected. This method should contain the code that determines how to display the contents of the rowRenderer.
• setEnabled(p_enable:Boolean):Void
  This is called on the rowRenderer whenever the enabled state of the component changes. It should determine how the renderer should appear when enabled/disabled.
• setInstanceStyle(p_style:String,p_val):Void
  This is called on the rowRenderer in order to update any text styling information (see Text Styling paragraph). It takes the style and stores it as a TextFormat object in the textFormat property of the rowRenderer. The textFormat property can then be assigned to the rowRenderer label at the time that setValue is called.
• listOwner:GUIList
  A reference to the List that the rowRenderer is contained in.
• index:Number
  The index position of the item drawn in the rowRenderer.
• labelField:String
  A string representing the property value in the item to use as the label.
• labelFunction:Function
  A function that returns a label to display for that item.
• iconField:String
  A string representing the property value in the item to use as the icon linkage ID or URL.
• iconFunction:Function
  A function that returns the icon linkage ID or URL for that item.

The assets (MovieClip and ActionScript class) of the default rowRenderer used by the SmartFoxBits' RoomList and UserList components can be downloaded for reference in creating your own RowRenderer. Click here to download.

The SmartFoxBits Community Edition pack contains the examples described hereafter. You can find the source files in the examples/skinning folder contained in the downloaded zip file. Check the ActionScript comments inside the FLA files for further details.

• Simple skin example (skin1.fla)
  A very basic skinning example using plain MovieClips to customize the look of the SmartFoxBits' LoginBox component. Please notice that this example is not a fully working application.
• Basic skin example (skin2.fla)
  An more advanced version of the previous example: this skin still uses simple MovieClips, but where necessary (buttons, for example) they implement all the required states (up, over, etc.).
• Advanced skin example (skin3.fla)
  An even more advanced version of the previous example: this skin uses empty MovieClips linked to external custom ActionScript classes which render the user interface using the Flash Drawing API. Also global text styling is applied.
• VEGETABLED skin (vegetabledSkin.fla)
  A funny, sparkling, mint-flavoured skin!
  This skin shows the full potential of SmartFoxBits skinning & styling capabilities through the mCOM components. Almost every technique explained in this document has been applied: multi-state skin MovieClips, background classes using the Drawing API, global and per-instance text styling, custom row renderers. This example is a fully working chat application.

The following links will provide general informations about the mCOM components and their skinning features.

• The mCOM components homepage
  An introduction to the mCOM components, with a live demonstration suite
• mCOM skinning overview
  A simplified description of the mCOM skinning capabilities, with a downloadable example
• Getting started: skinning the mCOM
  A detailed description of the mCOM skinning capabilities
• Button skinning example
  A simple example on how to skin a multi-state button

Please inform us in case of broken links.