Main Page | Packages | Class Tree | Index

it.gotoandplay.smartfoxbits.bits

class UserList

MovieClip
  |
  +--it.gotoandplay.smartfoxbits.bits.UserList


class UserList
extends MovieClip

The UserList class provides methods and properties to control the SmartFoxBits' UserList component behavior at author-time and run-time.

The SmartFoxBits' UserList component displays the list of users in a room an allows private messages exchange.
The UserList component 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 (see the SmartFoxBits' LoginBox component).
When a user in the list is clicked, if the enablePrivateChat property is set to true, an inner ChatBox component is displayed for private messaging. If the user clicking on the list is a Moderator, also Kick and Ban buttons are shown.
As for all the other SmartFoxBits components, the UserList is based on the mCOM Flash components. You can read more about these components and their features here. Besides working on the mCOM components' styling and skinning features, you can customize the UserList by setting the list items' labels and icons and buttons' labels.

Both user label and icon can be set on the basis of user propeties (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. These icons can be easily customized without using the iconFunction property: just add to your application library three movieclips with the linkage property set to:

User icons also support the following states, corresponding to the list item states: up, over, select.
To display these states properly, the custom icons must have the following structure:

NOTE 1: use the same frame labels (case-sensitive).
NOTE 2: add a stop() action in each frame.

The UserList component also supports external icon files (swf and jpg formats): check the iconFunction property.

Usage:
Drag & drop the UserList component onto the stage and set its properties in the Property Inspector at author-time, or attach it at run-time using actionscript.
The component communicates with SmartFoxServer through the SmartFoxBits' Connector component: read the Connector's description for further details.
If you need to override the default behaviour when a user is clicked in the list, you can register to the it.gotoandplay.smartfoxbits.events.BitEvent.onUserChange event using the addEventListener method (for example if you want to implement 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.


Author:

Version:
1.0.0 - First release.

Since:
SmartFoxBits v1.0

Example:
To instantiate the UserList at run-time, make sure it's contained in your library and write the following:
import it.gotoandplay.smartfoxbits.bits.UserList
 
var userList_mc:UserList = UserList(attachMovie("UserList", "userList_mc", 3))
userList_mc.enablePrivateChat = false

NOTE 1: importing the it.gotoandplay.smartfoxbits.bits.UserList class and casting the UserList's movieclip to it is useful if you intend to use a development tool having code-completion features. Otherwise this is enough:

var userList_mc = attachMovie("UserList", "userList_mc", 3)
NOTE 2: in the following examples userList_mc represents the UserList instance name.

See also:


Property Summary

public
banButton: Button (read-only)
A reference to the "ban" Button component.

public
banButtonText: String (read, write)
The label of the "ban" button.

public
banMessage: String (read, write)
The message sent to a user when being banned by the Moderator.

public
enablePrivateChat: Boolean (read, write)
Enable/disable private chat and moderation features.

public
height: Number (read, write)
The height of the UserList component on the stage, in pixels.

public
iconFunction: Function (read, write)
A reference to a custom method to be invoked when attaching the room icon movieclip.

public
kickButton: Button (read-only)
A reference to the "kick" Button component.

public
kickButtonText: String (read, write)
The label of the "kick" button.

public
kickMessage: String (read, write)
The message sent to a user when being kicked by the Moderator.

public
labelFunction: Function (read, write)
A reference to a custom method to be invoked when rendering the room labels, to set their text.

public
labelMargin: Number (read, write)
The space between the list item left border and the label.

public
moderateLabel: Label (read-only)
A reference to the "moderation module" Label component.

public
moderateLabelTxt: String (read, write)
The label text of the moderation module.

public
newPrivateMsgLabelColor: Number (read, write)
The color of user label when a private message is received.

public
privateChat: ChatBox (read-only)
A reference to the "private chat" ChatBox component.

public
privateChatLabel: Label (read-only)
A reference to the "private chat module" Label component.

public
privateChatLabelTxt: String (read, write)
The label text of the private chat module.

public
rowHeight: Number (read, write)
The height of the list items.

public
showFocusRectangle: Boolean (read, write)
Show/hide the focus rectangle around the user list, the private ChatBox, and the kick/ban buttons.

public
showIcons: Boolean (read, write)
Show/hide the user icons.

public
sortOrder: String (read, write)
The users' sorting order.

public
spacing: Number (read, write)
The number of pixels dividing the UserList sub-components (private ChatBox, kick/ban buttons, etc.).

public
usersList: AdvancedList (read-only)
A reference to the inner AdvancedList component.

public
useSmartList: Boolean (read, write)
Enable/disable the "Smart List" feature.

public
width: Number (read, write)
The width of the UserList component on the stage, in pixels.

Constructor


UserList ( )
UserList class constructor. Initializes the component.

Method Summary

public
addEventListener ( type: String, listener: Function ): Void
Register a listener function in order to receive notification of a UserList event.

public
refreshView ( ): Void
Refresh the UserList view.

public
removeEventListener ( type: String, listener: Function ): Void
Remove a listener from the UserList's event dispatcher, to stop receiving notification of an event.



Property Documentation

banButton

public banButton: Button (read-only)
A reference to the "ban" Button component.

This reference allows you to take control over the ban Button mCOM component, to set its properties (for example size). Please notice that if you change the component size, you have to call the refreshView method to rearrange the UserList's view accordingly.
Check the mCOM Flash components documentation for further details.

NOTE: this button becomes visible when a Moderator clicks on a user, and only if the enablePrivateChat property is set to true.

Usage:
To access the ban Button component:
import com.metaliq.controls.Button
 
var bt:Button = userList_mc.banButton
bt.height = 50
userList_mc.refreshView()

See also:
com.metaliq.controls.Button, SmartFoxBits and the mCOM Flash components

banButtonText

public banButtonText: String (read, write)
The label of the "ban" button.

Usage:
To set the ban button label:
userList_mc.banButtonText = "Ban"

See also:

banMessage

public banMessage: String (read, write)
The message sent to a user when being banned by the Moderator.

Usage:
To set the ban message:
userList_mc.banMessage = "The Moderator banned you!"

See also:

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.

Usage:
To disable private chat:
userList_mc.enablePrivateChat = false

height

public height: Number (read, write)
The height of the UserList component on the stage, in pixels.

Use this property instead of _height to resize the UserList mantaining the inner components' aspect ratio.

Usage:
To set the UserList's height:
userList_mc.height = 600

See also:

iconFunction

public iconFunction: Function (read, write)
A reference to a custom method to be invoked when attaching the room icon movieclip.

Using the iconFunction property, you can set your own user icons by means of a custom function. This function receives an object as parameter (see the labelFunction property for details), and must return a string containing the icon's movieclip linkage name (you must have the icon in your application's library) or a filename of an external icon (only jpg and swf files are supported).
If you intend to use an external icon, please read the useSmartList property description.

Usage:
To set the UserList's label function:
function setCustomUserIcon(item):String
{
	user = item.userData
	
	var icon:String
	
	[...]
	
	return icon
}
 
userList_mc.iconFunction = setCustomUserIcon

See also:

kickButton

public kickButton: Button (read-only)
A reference to the "kick" Button component.

This reference allows you to take control over the kick Button mCOM component, to set its properties (for example size). Please notice that if you change the component size, you have to call the refreshView method to rearrange the UserList's view accordingly.
Check the mCOM Flash components documentation for further details.

NOTE: this button becomes visible when a Moderator clicks on a user, and only if the enablePrivateChat property is set to true.

Usage:
To access the kick Button component:
import com.metaliq.controls.Button
 
var bt:Button = userList_mc.kickButton
bt.height = 50
userList_mc.refreshView()

See also:
com.metaliq.controls.Button, SmartFoxBits and the mCOM Flash components

kickButtonText

public kickButtonText: String (read, write)
The label of the "kick" button.

Usage:
To set the kick button label:
userList_mc.kickButtonText = "Kick"

See also:

kickMessage

public kickMessage: String (read, write)
The message sent to a user when being kicked by the Moderator.

Usage:
To set the kick message:
userList_mc.kickMessage = "The Moderator kicked you!"

See also:

labelFunction

public labelFunction: Function (read, write)
A reference to a custom method to be invoked when rendering the room 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 renderer for list items, the text can be formatted using html tags supported by the Flash TextField class. 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 component uses an internal label function to set a more informative label; see the example below).
  • data:Number
    The user ID.
  • icon:String
    The default icon linkage name (undefined if the showIcons property is set to false). The UserList component uses three different default icons, depending on the user type (see the UserList class description).
  • 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 room label/icon to display specific user informations.
  • newMsgCount:Number
    The number of private messages sent by the user not yet displayed in the recipient's private chat.

Usage:
To set the UserList's label function:
userList_mc.labelFunction = setCustomUserLabel

The following code shows the labelFunction used by the component itself to generate the default user label:

function setCustomUserLabel(item:Object):String
{
	var user:User = item.userData
	var label:String = "<font size='10'"
	
	if (item.newMsgCount > 0)
		label += " color='#" + newPrivateMsgLabelColor.toString(16) + "'"
	
	label += ">" + user.getName() + "</font>"
	
	if (item.newMsgCount > 0)
	{
		label += "<br>"
		label += "<font size='9' color='#666666'>"
		label += String(item.newMsgCount) + " message" + (item.newMsgCount > 1 ? "s" : "") + " to read"
		label += "</font>"
	}
	
	return label
}

See also:

labelMargin

public labelMargin: Number (read, write)
The space between the list item left border and the label.

If the label margin is undefined, the icon width is used as margin. Setting this property is recommended when external swf or jpg files are used for room icons: as loading can take some time, setting a fixed margin prevents the label to be relocated after loading completion.

Usage:
To set the margin:
userList_mc.labelMargin = 30

moderateLabel

public moderateLabel: Label (read-only)
A reference to the "moderation module" Label component.

This reference allows you to take control over the moderation module Label mCOM component, to set its properties (for example text styling). Please notice that if you change the component size, you have to call the refreshView method to rearrange the UserList's view accordingly.
Check the mCOM Flash components documentation for further details.

NOTE: this button becomes visible when a Moderator clicks on a user, and only if the enablePrivateChat property is set to true.

Usage:
To access the moderation module Label component:
import com.metaliq.controls.Label
 
var lb:Label = userList_mc.moderateLabel
lb.setInstanceStyle("fontColor", 0xFFCC00)

See also:
com.metaliq.controls.Label, SmartFoxBits and the mCOM Flash components

moderateLabelTxt

public moderateLabelTxt: String (read, write)
The label text of the moderation module.

If left empty, the label doesn't show up in the component.

Usage:
To set the moderation module label text:
userList_mc.moderateLabelTxt = "Moderate:"

See also:

newPrivateMsgLabelColor

public newPrivateMsgLabelColor: Number (read, write)
The color of 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:
(1) the private chat module is not visible; (2) 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 original color.

Usage:
To set the label color:
userList_mc.newPrivateMsgLabelColor = 0xCC0000

privateChat

public privateChat: ChatBox (read-only)
A reference to the "private chat" ChatBox component.

This reference allows you to take control over the SmartFoxBits' ChatBox component contained inside the UserList, to set its properties.
Check the component's documentation for further details.

NOTE: this component becomes visible when clicking on a user, and only if the enablePrivateChat property is set to true.

Usage:
To access the private chat ChatBox component:
import it.gotoandplay.smartfoxbits.bits.ChatBox
 
var privateChatBox_mc:ChatBox = userList_mc.privateChat
privateChatBox_mc.initialMessage = "Enter your private message here"

See also:

privateChatLabel

public privateChatLabel: Label (read-only)
A reference to the "private chat module" Label component.

This reference allows you to take control over the private chat module Label mCOM component, to set its properties (for example text styling). Please notice that if you change the component size, you have to call the refreshView method to rearrange the UserList's view accordingly.
Check the mCOM Flash components documentation for further details.

NOTE: this label becomes visible when clicking on a user, and only if the enablePrivateChat property is set to true.

Usage:
To access the private chat module Label component:
import com.metaliq.controls.Label
 
var lb:Label = userList_mc.privateChatLabel
lb.setInstanceStyle("fontColor", 0xFFCC00)

See also:
com.metaliq.controls.Label, SmartFoxBits and the mCOM Flash components

privateChatLabelTxt

public privateChatLabelTxt: String (read, write)
The label text of the private chat module.

If left empty, the label doesn't show up in the component.

Usage:
To set the private chat module label text:
userList_mc.privateChatLabelTxt = "Send a private message:"

See also:

rowHeight

public rowHeight: Number (read, write)
The height of the list items.

Usage:
To set the height:
userList_mc.rowHeight = 30

showFocusRectangle

public showFocusRectangle: Boolean (read, write)
Show/hide the focus rectangle around the user list, the private ChatBox, and the kick/ban buttons.

Usage:
To show the focus rectangle:
userList_mc.showFocusRectangle = true

showIcons

public showIcons: Boolean (read, write)
Show/hide the user icons.

Usage:
To hide the icons:
userList_mc.showIcons = false

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, or set it to DESC to have a descending order.

Usage:
To set the sorting order:
userList_mc.sortOrder = "DESC"

spacing

public spacing: Number (read, write)
The number of pixels dividing the UserList sub-components (private ChatBox, kick/ban buttons, etc.).

Usage:
To set the spacing:
userList_mc.spacing = 10

usersList

public usersList: AdvancedList (read-only)
A reference to the inner AdvancedList component.

This reference allows you to take control over the users AdvancedList component, an enhanced version of the List mCOM component, to set its properties (for example text styling). Please notice that changing the component size via ActionScript won't affect the rendering on screen, as the AdvancedList is always resized to match the UserList component size.
Check this document for details about the list's RowRenderer.

Usage:
To access the users AdvancedList component:
import com.metaliq.controls.AdvancedList
 
var al:AdvancedList = userList_mc.usersList
al.setInstanceStyle("fontColor", 0xFFCC00)

See also:

useSmartList

public useSmartList: Boolean (read, write)
Enable/disable the "Smart List" feature.

When the "Smart List" feature is enabled, only the currently visible list items are rendered. For this reason during list scrolling, each time an item goes out of sight or becomes visible, all the visible items are redrawn. This prevents performance degradation in case of huge number of users, but causes icons flickering in case of externally loaded icons (due to the fact that they are reloaded at each redraw).
On the other hand, when this feature is disabled, all the UserList items are rendered, even those out of sight: in case lots of users must be displayed, scrolling may become CPU consuming.

If you plan to have many users inside each rooms, it's highly recommended that you enable this feature and use icons contained in the FLA library.

Usage:
To disable the "Smart List" feature:
userList_mc.useSmartList = false

width

public width: Number (read, write)
The width of the UserList component on the stage, in pixels.

Use this property instead of _width to resize the UserList mantaining the inner components' aspect ratio.

Usage:
To set the UserList's width:
userList_mc.width = 600

See also:


Constructor Documentation

UserList

function UserList()
UserList class constructor. Initializes the component.


Method Documentation

addEventListener

public function addEventListener(type: String,
 listener: Function): Void
Register a listener function in order to receive notification of a UserList event.

You can register to events fired by the UserList component, in case you need to be notified to execute your own code.
The UserList dispatches the following events:

If you no longer need an event listener, remove it by calling the removeEventListener method.

NOTE: you should use the Delegate.create(listenerFunctionName) method when registering a listener, to keep right scope in your application.

Usage:
To register to an event:
import it.gotoandplay.smartfoxbits.events.*
import mx.utils.Delegate
 
userList_mc.addEventListener(BitEvent.onUserChange, Delegate.create(this, myListener))
 
private function myListener(evt:BitEvent):Void
{
	trace("Got the event!")
	trace("Event type: " + evt.type)
	trace("Event target: " + evt.target)
	trace("Additional parameters:")
 
	for (var i in evt.params)
		trace("\t" + i + " -> " + evt.params[i])
}

Parameters:
type
The UserList event type you want to be notified of.
listener
The listener function in your application that processes the event. This function must accept an BitEvent object as its only parameter and must return nothing, as in the example above.
See also:

refreshView

public function refreshView(): Void
Refresh the UserList view.

If you change the size of the UserList's inner components, you have to call this method to rearrange the UserList's view accordingly.

removeEventListener

public function removeEventListener(type: String,
 listener: Function): Void
Remove a listener from the UserList's event dispatcher, to stop receiving notification of an event.

Usage:
To remove a listener:
userList_mc.removeEventListener(BitEvent.onUserChange, myListener)

NOTE: the Delegate.create(listenerFunctionName) is not required to remove a listener.

Parameters:
type
The UserList event type you registered your listener to.
listener
The listener function to remove.
See also:


The documentation was generated from the following file: