+Show TOC
×Hide TOC

RoomList

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.RoomList
File last modified:	Wednesday, 15 April 2009, 19:01:35

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

The SmartFoxBits RoomList control displays the list of available rooms in the current SmartFoxServer zone, so that users can access them by clicking on the corresponding list items.
The component shows all the three available room types (chat, game and "limbo", see Room configuration in the SmartFoxServer documentation); it handles password request for private rooms and let users join as players or spectators in game rooms.
As for all the other SmartFoxBits controls, the ChatBox internal components are Flex controls which can be accessed to set their properties (check the Flex documentation for controls styling operations).
The RoomList can be highly customized: you can set the list items labels and icons, use a custom ItemRenderer, group rooms by type, set the buttons labels, show or hide specific room types or private rooms.
Both room label and icon can be set on the basis of room properties (see the SmartFoxServer's Room class for more informations), so you can show, for example, the number of current users/players/spectators, or set a specific icon for the room.
By default the component shows different icons depending on the room type and room being public or private. The icons can be customized by creating a custom ItemRenderer.

NOTE: in the provided examples, roomList always indicates a RoomList 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 RoomList control from the Components panel and drop it in the Flex Design View. The RoomList properties can be set in Flex Properties panel or in the Source View (by editing the MXML tag) at author-time.
The RoomList instance can also be created and its properties set at run-time, using ActionScript.
The RoomList communicates with SmartFoxServer through the Connector control: read the Connector's class description for additional informations.
If you need to override the default room join process when a room is clicked in the list, you can register to the BitEvent.ROOM_CHANGE event (for example if you need to show a password request panel different from the default one).
During run-time usage, as soon as the user logs in, the component is enabled and a room is joined (if an "auto-joinable" room exists on the server, or if a room name has been specified in Parameters panel - see the defaultRoom property); then the user can join other rooms by clicking on the list.
Styling
The following style is available for the RoomList 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 RoomList 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 RoomList at author-time via MXML, write the following:

<sfb:RoomList id="roomList" defaultRoom="The Garden" />

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

import com.smartfoxserver.smartfoxbits.bits.RoomList

// Create RoomList instance
var roomList:RoomList = new RoomList()

// Set the name of the room to be joined
roomList.defaultRoom = "The Garden"

// Add RoomList instance to the display list
addChild(roomList)

Events broadcasted to listeners:

BitEvent with type: ROOM_CHANGE
- Dispatched by the RoomList component when the selected room is changed.

Summary

Constructor

RoomList

Instance properties

errorsDisplayTime : Number
- The number of seconds that error messages must remain visible for.
groupByRoomType : Boolean
- Group rooms by type.
joinButtonText : String
- The label of the "join" button.
passwordLabelText : String
- The text of the label located above the password input field.
playButtonText : String
- The label of the "play" button.
watchButtonText : String
- The label of the "watch" button.
defaultRoom : String
- The default room to be joined after a successful login.
rowHeight : Number
- The height of the list items.
showChatRooms : Boolean
- Show/hide the chat rooms inside the list.
showGameRooms : Boolean
- Show/hide the game rooms inside the list.
showLimboRooms : Boolean
- Show/hide the limbo rooms inside the list.
showPrivateRooms : Boolean
- Show/hide the private rooms (independently of their type).
showIcons : Boolean
- Show/hide the room icons.
sortOrder : String
- The rooms' sorting order.
labelFunction : Function
- A reference to a custom method to be invoked when rendering the room labels, to set their text.
iconFunction : Function
- A reference to a custom method to be invoked when instantiating the room icon.
joinButton : Button
- A reference to the "join/play" Button control.
watchButton : Button
- A reference to the "watch" Button control.
cancelButton : Button
- A reference to the "cancel" Button control.
passwordLabel : Label
- A reference to the "password" Label control.
passwordTextInput : TextInput
- A reference to the "password" TextInput control.
list : List
- A reference to the inner List control.
errorTextField : UITextField
- A reference to the "error" UITextField component.

Instance methods

destroy : void
- Destroy the RoomList instance.

Constructor

RoomList

public function RoomList (

)

RoomList constructor.

Example:

See the example in the class description.

Instance properties

cancelButton

public cancelButton:Button

(read)

A reference to the "cancel" Button control.
This property allows you to get a reference to the cancel Flex Button control, to set its properties (for example size). Check the Flex Components documentation for additional details.
The button becomes visible when clicking on a private room.

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

Example:

To access the cancel Button control in ActionScript:

import mx.controls.Button

var button:Button = roomList.cancelButton
button.height = 50

roomList.invalidateDisplayList()

defaultRoom

public defaultRoom:String

(read,write)

The default room to be joined after a successful login.
You can either pass the name of the room to be joined or its numeric id. If this property is undefined, the component checks if a static server room has the "autoJoin" property set to true and joins it if found.

Example:

To set the default room using MXML:

<sfb:RoomList defaultRoom="The Garden" />

To set the default room using ActionScript:

roomList.defaultRoom = "The Garden"

Component metadata:

Bindable	"defaultRoomChange"
Inspectable	category: "Common" defaultValue: "" name: "Room to join"

errorsDisplayTime

public errorsDisplayTime:Number

(read,write)

The number of seconds that error messages must remain visible for.
If set to 0, error messages (tipically room join errors) won't be displayed.

Example:

To set the display time in MXML:
```
<sfb:RoomList errorsDisplayTime="3" />
```
To set the display time in ActionScript:
```
roomList.errorsDisplayTime = 3
```

Component metadata:

Bindable	"errorDisplayTimeChange"
Inspectable	category: "Common" defaultValue: 2 name: "Error messages display time" type: Number

errorTextField

public errorTextField:UITextField

(read)

A reference to the "error" UITextField component.
This property allows you to get a reference to the error Flex UITextField component, to set its properties (for example text styling). Check the Flex Components documentation for additional details.

Example:

To access the error UITextField component in ActionScript:

import mx.core.UITextField

var tf:UITextField = roomList.errorTextField
tf.setStyle("color", 0xFFCC00)

groupByRoomType

public groupByRoomType:Boolean

(read,write)

Group rooms by type.
Setting this property to true enables the rooms grouping by type: "limbo" rooms appear at the top of the list, followed by chat rooms and game rooms at the bottom. Inside each group rooms are ordered by room name accordingly to the sortOrder parameter.

Example:

To group rooms by type using MXML:
```
<sfb:RoomList groupByRoomType="true" />
```
To group rooms by type using ActionScript:
```
roomList.groupByRoomType = true
```

See also:

sortOrder

Component metadata:

Inspectable	category: "Common" defaultValue: false name: "Group rooms by type" type: Boolean

iconFunction

public iconFunction:Function

(read,write)

A reference to a custom method to be invoked when instantiating the room icon.
Using the iconFunction property, you can set your own room 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 RoomList icon function using ActionScript:

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

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

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

function setCustomRoomIcon(item:Object):Class
{
    var room:Room = item.roomData

    if (room.isLimbo())
        return limboRoomIcon
    else
        if (room.isGame())
            return gameRoomIcon
        else
            return chatRoomIcon
}

roomList.iconFunction = setCustomRoomIcon

See also:

labelFunction

Component metadata:

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

joinButton

public joinButton:Button

(read)

A reference to the "join/play" Button control.
This property allows you to get a reference to the join/play Flex Button control, to set its properties (for example size). Check the Flex Components documentation for additional details.
The button becomes visible when clicking on a private room, or a game room accepting spectators. If the room type is "chat", the button label is set to the joinButtonText property value; in case of "game" room, the label is set to the playButtonText property value.

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

Example:

To access the join/play Button control in ActionScript:

import mx.controls.Button

var button:Button = roomList.joinButton
button.height = 50

roomList.invalidateDisplayList()

joinButtonText

public joinButtonText:String

(read,write)

The label of the "join" button.

Example:

To set the join button label in MXML:
```
<sfb:RoomList joinButtonText="Join" />
```
To set the join button label in ActionScript:
```
roomList.joinButtonText = "Join"
```

See also:

Component metadata:

Bindable	"joinButtonTextChange"
Inspectable	category: "Common" defaultValue: "Join" name: "Join button text"

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 room 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 room name (this would be the standard label for each list item, but the RoomList control makes use of an internal label function to set a more informative label; see the example below).
data:Number
The room ID.
roomData:Room
The SmartFoxServer Room object corresponding to the list item (check the Room class documentation for a list of available properties and methods).
Using this object you can easily customize the room label to display specific room informations like number of current users/players/spectators, room type, capacity, etc.

Example:

To set the RoomList label function using ActionScript:

roomList.labelFunction = setCustomRoomLabel

The following code shows the labelFunction used by the RoomList internally to generate the default room label:

function setCustomRoomLabel(item:Object):String
{
    var room:Room = item.roomData
    var label:String = room.getName()

    if (!room.isLimbo())
    {
        label += "<br>"
        label += "<font size='10' color='#666666'>"

        if (room.isGame())
            label += "Players: "
        else
            label += "Users: "

        label += room.getUserCount() + "/" + room.getMaxUsers()

        if (room.getMaxSpectators() > 0)
            label += " | Watchers: " + room.getSpectatorCount() + "/" + room.getMaxSpectators()

        label += "</font>"
    }

    return label
}

See also:

iconFunction

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 = roomList.list

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

passwordLabel

public passwordLabel:Label

(read)

A reference to the "password" Label control.
This property allows you to get a reference to the password Flex Label control, to set its properties (for example text styling). Check the Flex Components documentation for additional details.

Example:

To access the password Label control in ActionScript:

import mx.controls.Label

var label:Label = roomList.passwordLabel
label.setStyle("color", 0xFFCC00)

passwordLabelText

public passwordLabelText:String

(read,write)

The text of the label located above the password input field.

Example:

To set the password label in MXML:

<sfb:RoomList passwordLabelText="Enter password for this room:" />

To set the password label in ActionScript:

roomList.passwordLabelText = "Enter password for this room:"

See also:

Component metadata:

Bindable	"passwordLabelTextChange"
Inspectable	category: "Common" defaultValue: "Enter the password

passwordTextInput

public passwordTextInput:TextInput

(read)

A reference to the "password" TextInput control.
This property allows you to get a reference to the password Flex TextInput control, to set its properties (for example text styling). Check the Flex Components documentation for additional details.

Example:

To access the password TextInput control in ActionScript:

import mx.controls.TextInput

var ti:TextInput = roomList.passwordTextInput
ti.setStyle("color", 0xFFCC00)

playButtonText

public playButtonText:String

(read,write)

The label of the "play" button.

Example:

To set the play button label in MXML:
```
<sfb:RoomList playButtonText="Play" />
```
To set the play button label in ActionScript:
```
roomList.playButtonText = "Play"
```

See also:

Component metadata:

Bindable	"playButtonTextChange"
Inspectable	category: "Common" defaultValue: "Play" name: "Play button text"

rowHeight

public rowHeight:Number

(read,write)

The height of the list items.

Example:

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

Component metadata:

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

showChatRooms

public showChatRooms:Boolean

(read,write)

Show/hide the chat rooms inside the list.

Example:

To hide the chat rooms using MXML:
```
<sfb:RoomList showChatRooms="false" />
```
To hide the chat rooms using ActionScript:
```
roomList.showChatRooms = false
```

See also:

Component metadata:

Inspectable	category: "Common" defaultValue: true name: "Show chat rooms" type: Boolean

showGameRooms

public showGameRooms:Boolean

(read,write)

Show/hide the game rooms inside the list.

Example:

To hide the game rooms using MXML:
```
<sfb:RoomList showGameRooms="false" />
```
To hide the game rooms using ActionScript:
```
roomList.showGameRooms = false
```

See also:

Component metadata:

Inspectable	category: "Common" defaultValue: true name: "Show game rooms" type: Boolean

showIcons

public showIcons:Boolean

(read,write)

Show/hide the room icons.

Example:

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

Component metadata:

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

showLimboRooms

public showLimboRooms:Boolean

(read,write)

Show/hide the limbo rooms inside the list.

Example:

To show the limbo rooms using MXML:
```
<sfb:RoomList showLimboRooms="true" />
```
To show the limbo rooms using ActionScript:
```
roomList.showLimboRooms = true
```

See also:

Component metadata:

Inspectable	category: "Common" defaultValue: false name: "Show limbo rooms" type: Boolean

showPrivateRooms

public showPrivateRooms:Boolean

(read,write)

Show/hide the private rooms (independently of their type).

Example:

To hide the private rooms using MXML:
```
<sfb:RoomList showPrivateRooms="false" />
```
To hide the private rooms using ActionScript:
```
roomList.showPrivateRooms = false
```

See also:

Component metadata:

Inspectable	category: "Common" defaultValue: true name: "Show private rooms" type: Boolean

sortOrder

public sortOrder:String

(read,write)

The rooms' sorting order.
List items are ordered by room 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 sorted and the groupByRoomType property is set to true, the ordering isn't applied to the full list but to each group separately; if the list is not sorted, the last created room is displayed at the bottom of the list.

Example:

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

See also:

groupByRoomType

Component metadata:

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

watchButton

public watchButton:Button

(read)

A reference to the "watch" Button control.
This property allows you to get a reference to the watch Flex Button control, to set its properties (for example size). Check the Flex Components documentation for additional details.
The button becomes visible when clicking on a game room accepting spectators. The button label is set to the watchButtonText property value.

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

Example:

To access the watch Button control in ActionScript:

import mx.controls.Button

var button:Button = roomList.watchButton
button.height = 50

roomList.invalidateDisplayList()

watchButtonText

public watchButtonText:String

(read,write)

The label of the "watch" button.

Example:

To set the watch button label in MXML:
```
<sfb:RoomList watchButtonText="Watch" />
```
To set the watch button label in ActionScript:
```
roomList.watchButtonText = "Watch"
```

See also:

Component metadata:

Bindable	"watchButtonTextChange"
Inspectable	category: "Common" defaultValue: "Watch" name: "Watch button text"

Instance methods

destroy

public function destroy (

) : void

Destroy the RoomList instance.
This method should be called to make the RoomList 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 RoomList instance:
```
roomList.destroy()
```