+Show TOC
×Hide TOC

UserList

Kind of class:	public class
Package:	com.smartfoxserver.smartfoxbits.bits
Inherits from:	UIComponent
Version:	1.0
Author:	The gotoAndPlay() Team http://www.smartfoxserver.com http://www.gotoandplay.it
Classpath:	com.smartfoxserver.smartfoxbits.bits.UserList
File last modified:	Wednesday, 15 April 2009, 19:01:45

The UserList class provides the public APIs to interact with the SmartFoxBits UserList control at author-time and run-time.

The SmartFoxBits UserList control displays the list of users in a room and allows sending and receiving private messages.
The UserList control shows all user types: standard, guest and moderator. The "guest" users are recognized by the name, which starts with the "guest_" string followed by a progressive number (according to the SmartFoxBits' LoginBox control behavior).
When a user in the list is clicked, if the enablePrivateChat property is set to true, an inner ChatBox control is displayed for private messaging. If the user clicking on the list is a Moderator, also Kick and Ban buttons are displayed.
As for all the other SmartFoxBits controls, the UserList internal components are Flex controls which can be accessed to set their properties (check the Flex documentation for controls styling operations).
The UserList can be highly customized: you can set the list items labels and icons, use a custom ItemRenderer, set the buttons labels, etc.
Both user label and icon can be set on the basis of user properties (see the SmartFoxServer's User class for more informations), so you can set, for example, a specific icon for a user.
By default the component shows different icons depending on the user type. The icons can be customized by creating a custom ItemRenderer.

NOTE: in the provided examples, userList always indicates a UserList instance.

Usage:

Add the "SmartFoxBits base Pack.swc" file to the Library Path in your Flex project properties: the SmartFoxBits category will appear in the Flex Components panel.
Drag the UserList control from the Components panel and drop it in the Flex Design View. The UserList properties can be set in Flex Properties panel or in the Source View (by editing the MXML tag) at author-time.
The UserList instance can also be created and its properties set at run-time, using ActionScript.
The UserList communicates with SmartFoxServer through the Connector control: read the Connector's class description for additional informations.
If you need to override the default behaviour (show private chat panel) when a user is clicked in the list, you can register to the BitEvent.USER_CHANGE event (for example if you want to implement a private chat system different from the default one).
During run-time, as soon as the user joins a room, the component is enabled and the list filled with users in that room.
Styling
The following style is available for the UserList control: gap
Styles can be applied using the standard Flex styling systems. Check the Flex documentation for additional informations.
Item renderer
The ItemRenderer of the UserList control can be customized by accessing the internal Flex List control. See the list property description for an example of custom ItemRenderer assignment.

Example:

To instantiate the UserList at author-time via MXML, write the following:

<sfb:UserList id="userList" enablePrivateChat="false" />

To instantiate the UserList at run-time, write the following:

import com.smartfoxserver.smartfoxbits.bits.UserList

// Create UserList instance
var userList:UserList = new UserList()

// Set UserList instance properties (for example disable private chat)
userList.enablePrivateChat = false

// Add userList instance to stage
addChild(userList)

Events broadcasted to listeners:

BitEvent with type: USER_CHANGE
- Dispatched by the UserList component when the selected user is changed.

Summary

Constructor

UserList

Instance properties

enablePrivateChat : Boolean
- Enable/disable private chat and moderation features.
newPrivateMsgLabelColor : uint
- The color of the user label when a private message is received.
banMessage : String
- The message sent to a user when being banned by the Moderator.
kickMessage : String
- The message sent to a user when being kicked by the Moderator.
moderateLabelText : String
- The text of the label located above the moderation buttons.
banButtonText : String
- The label of the "ban" button.
kickButtonText : String
- The label of the "kick" button.
privateChatLabelText : String
- The text of the label located above the private chat module.
rowHeight : Number
- The height of the list items.
showIcons : Boolean
- Show/hide the user icons.
sortOrder : String
- The users' sorting order.
labelFunction : Function
- A reference to a custom method to be invoked when rendering the user labels, to set their text.
iconFunction : Function
- A reference to a custom method to be invoked when instantiating the user icon.
kickButton : Button
- A reference to the "kick" Button control.
banButton : Button
- A reference to the "ban" Button control.
privateChatLabel : Label
- A reference to the "private chat module" Label control.
moderateLabel : Label
- A reference to the "moderation module" Label control.
privateChatBox : ChatBox
- A reference to the "private chat" ChatBox control.
list : List
- A reference to the inner List control.

Instance methods

destroy : void
- Destroy the UserList instance.
refreshList : void
- Refresh the list of users.

Constructor

UserList

public function UserList (

)

UserList constructor.

Example:

See the example in the class description.

Instance properties

banButton

public banButton:Button

(read)

A reference to the "ban" Button control.
This property allows you to get a reference to the ban Flex Button control, to set its properties (for example size). Check the Flex Components documentation for additional details.
The button becomes visible when a Moderator clicks on a user, and only if the enablePrivateChat property is set to true.

NOTE: if you change the Button control size, you then have to call the UserList.invalidateDisplayList method to rearrange the UserList view accordingly.

Example:

To access the ban Button control in ActionScript:

import mx.controls.Button

var button:Button = userList.banButton
button.height = 50

userList.invalidateDisplayList()

banButtonText

public banButtonText:String

(read,write)

The label of the "ban" button.

Example:

To set the ban button label in MXML:
```
<sfb:UserList banButtonText="Ban" />
```
To set the ban button label in ActionScript:
```
userList.banButtonText = "Ban"
```

See also:

Component metadata:

Bindable	"banButtonTextChange"
Inspectable	category: "Common" defaultValue: "Ban" name: "Ban button text"

banMessage

public banMessage:String

(read,write)

The message sent to a user when being banned by the Moderator.

Example:

To set the ban message in MXML:

<sfb:UserList banMessage="The Moderator banned you!" />

To set the ban message in ActionScript:

userList.banMessage = "The Moderator banned you!"

See also:

kickMessage

Component metadata:

Bindable	"banMessageChange"
Inspectable	category: "Common" defaultValue: "You have been banned by the Moderator" name: "Ban message"

enablePrivateChat

public enablePrivateChat:Boolean

(read,write)

Enable/disable private chat and moderation features.
Setting this property to false prevents the private ChatBox and kick/ban buttons to appear when a user is clicked in the list.

Example:

To disable the private chat using MXML:
```
<sfb:UserList enablePrivateChat="false" />
```
To disable the private chat using ActionScript:
```
userList.enablePrivateChat = false
```

Component metadata:

Inspectable	category: "Common" defaultValue: true name: "Enable private chat" type: Boolean

iconFunction

public iconFunction:Function

(read,write)

A reference to a custom method to be invoked when instantiating the user icon.
Using the iconFunction property, you can set your own user icon by means of a custom function which must receive an object as parameter (see the labelFunction property for details), and return the Class definition for the icon.

Example:

To set the UserList label function:

    [Embed(source="images/userIcon.png")]
    public var customUserIcon:Class;

function setCustomUserIcon(item:Object):Class
{
    var user:User = item.userData

    // Depending on the user parameters, a different icon class may be set

    return customUserIcon
}

userList.iconFunction = setCustomUserIcon

See also:

labelFunction

Component metadata:

Bindable	"iconFunctionChange"
Inspectable	category: "Common" name: "Icon Function"

kickButton

public kickButton:Button

(read)

A reference to the "kick" Button control.
This property allows you to get a reference to the kick Flex Button control, to set its properties (for example size). Check the Flex Components documentation for additional details.
The button becomes visible when a Moderator clicks on a user, and only if the enablePrivateChat property is set to true.

NOTE: if you change the Button control size, you then have to call the UserList.invalidateDisplayList method to rearrange the UserList view accordingly.

Example:

To access the kick Button control in ActionScript:

import mx.controls.Button

var button:Button = userList.kickButton
button.height = 50

userList.invalidateDisplayList()

kickButtonText

public kickButtonText:String

(read,write)

The label of the "kick" button.

Example:

To set the kick button label in MXML:
```
<sfb:UserList kickButtonText="Kick" />
```
To set the kick button label in ActionScript:
```
userList.kickButtonText = "Kick"
```

See also:

Component metadata:

Bindable	"kickButtonTextChange"
Inspectable	category: "Common" defaultValue: "Kick" name: "Kick button text"

kickMessage

public kickMessage:String

(read,write)

The message sent to a user when being kicked by the Moderator.

Example:

To set the kick message in MXML:

<sfb:UserList kickMessage="The Moderator kicked you!" />

To set the kick message in ActionScript:

userList.kickMessage = "The Moderator kicked you!"

See also:

banMessage

Component metadata:

Bindable	"kickMessageChange"
Inspectable	category: "Common" defaultValue: "You have been kicked by the Moderator" name: "Kick message"

labelFunction

public labelFunction:Function

(read,write)

A reference to a custom method to be invoked when rendering the user labels, to set their text.
Using the labelFunction property, you can set your own user labels by means of a custom function. This function receives an object as parameter, and must return a string containing the label text.
If you use the default ItemRenderer for list items, the text can be formatted using the html tags supported by the Flex UITextField component.
The object passed to the function has the following properties:

label:String
The user name (this would be the standard label for each list item, but the UserList control makes use of an internal label function to set a more informative label; see the example below).
data:Number
The user ID.
userData:User
The SmartFoxServer User object corresponding to the list item (check the User class documentation for a list of available properties and methods).
Using this object you can easily customize the user label to display specific user informations.
newMsgCount:Number
The number of private messages received from the user and not yet displayed in the recipient's private chat.

Example:

To set the UserList label function using ActionScript:

userList.labelFunction = setCustomUserLabel

The following code shows the labelFunction used by the UserList internally to generate the default user label:

function setCustomUserLabel(item:Object):String
{
    var user:User = item.userData
    var label:String = "<font"

    if (item.newMsgCount > 0)
        label += " color='#" + newPrivateMsgLabelColor.toString(16) + "'"

    label += ">" + user.getName() + "</font>"

    if (item.newMsgCount > 0)
    {
            label += "<br>"
        label += "<font size='10' color='#666666'>"
        label += String(item.newMsgCount) + " message" + (item.newMsgCount > 1 ? "s" : "") + " to read"
        label += "</font>"
    }

    return label
}

See also:

Component metadata:

Bindable	"labelFunctionChange"
Inspectable	category: "Common" name: "Label Function"

list

public list:List

(read)

A reference to the inner List control.
This property allows you to get a reference to the internal Flex List control, to set its properties (for example the ItemRenderer). Check the Flex Components documentation for additional details.

Example:

To access the internal List control in ActionScript and assign a custom ItemRenderer:

import mx.controls.List
import my.class.path.CustomItemRenderer

var list:List = userList.list

// Assign a custom ItemRenderer
list.itemRenderer = new ClassFactory(CustomItemRenderer)

moderateLabel

public moderateLabel:Label

(read)

A reference to the "moderation module" Label control.
This property allows you to get a reference to the moderation module Flex Label control, to set its properties (for example text styling). Check the Flex Components documentation for additional details.
The label becomes visible when a Moderator clicks on a user, and only if the enablePrivateChat property is set to true.

Example:

To access the moderation module Label control in ActionScript:

import mx.controls.Label

var label:Label = userList.moderateLabel
label.setStyle("color", 0xFFCC00)

moderateLabelText

public moderateLabelText:String

(read,write)

The text of the label located above the moderation buttons.

Example:

To set the moderation buttons label in MXML:
```
<sfb:UserList moderateLabelText="Moderate:" />
```
To set the moderation buttons label in ActionScript:
```
userList.moderateLabelText = "Moderate:"
```

See also:

Component metadata:

Bindable	"moderateLabelTextChange"
Inspectable	category: "Common" defaultValue: "Moderate user

newPrivateMsgLabelColor

public newPrivateMsgLabelColor:uint

(read,write)

The color of the user label when a private message is received.
This property sets the color to which a user label is switched whenever a private message is received and: (a) the private chat module is not visible; (b) the private chat module is visible but the recipient is having a private chat with a different user.
When the recipient clicks on the user, the label turns back to the default color.

NOTE: this property works in conjuntion with the default ItemRenderer only; see the labelFunction property.

Example:

To set the label color in MXML:

<sfb:UserList newPrivateMsgLabelColor="#FFCC00" />

To set the label color in ActionScript:

userList.newPrivateMsgLabelColor = 0xFFCC00

See also:

labelFunction

Component metadata:

Bindable	"newPrivateMsgLabelColorChange"
Inspectable	category: "Common" defaultValue: "#CC0000" format: "Color" name: "Label color on new private message"

privateChatBox

public privateChatBox:ChatBox

(read)

A reference to the "private chat" ChatBox control.
This property allows you to get a reference to the internal ChatBox control, to set its properties. Check the ChatBox documentation for additional details.
The ChatBox becomes visible when clicking on a user, and only if the enablePrivateChat property is set to true.

NOTE: if you change the ChatBox control height, you then have to call the UserList.invalidateDisplayList method to rearrange the UserList view accordingly.

Example:

To access the internal ChatBox control in ActionScript:

import com.smartfoxserver.smartfoxbits.bits.ChatBox

var privateChatBox:ChatBox = userList.privateChatBox

    // Change a ChatBox property
privateChatBox.showColorPicker = true

See also:

ChatBox

privateChatLabel

public privateChatLabel:Label

(read)

A reference to the "private chat module" Label control.
This property allows you to get a reference to the private chat module Flex Label control, to set its properties (for example text styling). Check the Flex Components documentation for additional details.
The label becomes visible when clicking on a user, and only if the enablePrivateChat property is set to true.

Example:

To access the private chat module Label control in ActionScript:

import mx.controls.Label

var label:Label = userList.privateChatLabel
label.setStyle("color", 0xFFCC00)

privateChatLabelText

public privateChatLabelText:String

(read,write)

The text of the label located above the private chat module.

Example:

To set the private chat label in MXML:

<sfb:UserList privateChatLabelText="Send a private message:" />

To set the private chat label in ActionScript:

userList.privateChatLabelText = "Send a private message:"

See also:

Component metadata:

Bindable	"privateChatLabelTextChange"
Inspectable	category: "Common" defaultValue: "Private messaging

rowHeight

public rowHeight:Number

(read,write)

The height of the list items.

Example:

To set the list rows height in MXML:
```
<sfb:UserList rowHeight="20" />
```
To set the list rows height in ActionScript:
```
userList.rowHeight = 20
```

Component metadata:

Bindable	"rowHeightChange"
Inspectable	category: "Common" defaultValue: 32 name: "Row height" type: Number

showIcons

public showIcons:Boolean

(read,write)

Show/hide the user icons.

Example:

To hide the icons using MXML:
```
<sfb:UserList showIcons="false" />
```
To hide the icons using ActionScript:
```
userList.showIcons = false
```

Component metadata:

Inspectable	category: "Common" defaultValue: true name: "Show icons" type: Boolean

sortOrder

public sortOrder:String

(read,write)

The users' sorting order.
List items are ordered by user name (not by label!): set this property to ASC to have an ascending order, to DESC to have a descending order, or set it to NOSORT to remove the sorting.
If the list is not sorted, the last user who entered the room is displayed at the bottom of the list.

Example:

To set the sorting order using MXML:
```
<sfb:UserList sortOrder="DESC" />
```
To set the sorting order using ActionScript:
```
userList.sortOrder = "DESC"
```

Component metadata:

Inspectable	category: "Common" defaultValue: "ASC" enumeration: "ASC,DESC,NOSORT" name: "Sort order" type: Array

Instance methods

destroy

public function destroy (

) : void

Destroy the UserList instance.
This method should be called to make the UserList eligible for garbage-collection in the Flash Player.
When called, this methods removes the listeners to the SmartFoxClient events added during initialization.

Example:

To destroy the UserList instance:
```
userList.destroy()
```

refreshList

public function refreshList (

) : void

Refresh the list of users.
This method can be used to force the UserList to reload the list of users for the currently joined room.
This can be useful in multi-state applications. In fact, in this kind of application design, usually the login is made in a certain state, but the UserList is instantiated in one of the following states.
As the UserList, internally, relies on the room join event to initialize itself, if this event is fired before the UserList is read to catch it, then the correct list of users won't be displayed.

Example:

To refresh the list of users in the current room:
```
userList.refreshList()
```