Main Page | Packages | Class Tree | Index

it.gotoandplay.smartfoxbits.bits

class RoomList

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


class RoomList
extends MovieClip

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

The SmartFoxBits' RoomList component displays the list of available rooms in the zone, so that users can access them by clicking on a list item.
By default the RoomList component shows all the three available room types (chat, game and "limbo", see Room configuration) and handles password request for private rooms and joining as player/spectator for game rooms.
As for all the other SmartFoxBits components, the RoomList 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 RoomList by setting the list items' labels and icons, grouping rooms by type, setting buttons' labels, showing or hiding specific room types or private rooms.

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

Room 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 RoomList component also supports external icon files (swf and jpg formats): check the iconFunction property.

Usage:
Drag & drop the RoomList 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 room join process when a room is clicked in the list, you can register to the it.gotoandplay.smartfoxbits.events.BitEvent.onRoomChange event using the addEventListener method (for example if you need to show a password request panel different from the default one).
During run-time, as soon as the user logged 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 Property Inspector - see defaultRoom); then the user can join other rooms by clicking on the list.


Author:

Version:
1.0.0 - First release.

Since:
SmartFoxBits v1.0

Example:
To instantiate the RoomList at run-time, make sure it's contained in your library and write the following:
import it.gotoandplay.smartfoxbits.bits.RoomList
 
var roomList_mc:RoomList = RoomList(attachMovie("RoomList", "roomList_mc", 1))
roomList_mc.defaultRoom = "The Garden"

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

var roomList_mc = attachMovie("RoomList", "roomList_mc", 1)
NOTE 2: in the following examples roomList_mc represents the RoomList instance name.

See also:


Property Summary

public
cancelButton: Button (read-only)
A reference to the "cancel" Button component.

public
defaultRoom: String (read, write)
The default room to join after a succesful login.

public
errorsDisplayTime: Number (read, write)
The number of seconds error messages must remain visible for.

public
errorTextField: TextField (read-only)
A reference to the error message TextField.

public
groupByRoomType: Boolean (read, write)
Group rooms by type.

public
height: Number (read, write)
The height of the RoomList 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
joinButton: Button (read-only)
A reference to the "join"/"play" Button component.

public
joinButtonText: String (read, write)
The label of the "join" button.

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
passwordLabel: Label (read-only)
A reference to the "password" Label component.

public
passwordLabelText: String (read, write)
The label text of the password input field.

public
passwordTextInput: TextInput (read-only)
A reference to the "password" TextInput component.

public
playButtonText: String (read, write)
The label of the "play" button.

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

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

public
showChatRooms: Boolean (read, write)
Show/hide the chat rooms inside the list.

public
showFocusRectangle: Boolean (read, write)
Show/hide the focus rectangle around the rooms list, the password input field, and the join/play/watch/cancel buttons.

public
showGameRooms: Boolean (read, write)
Show/hide the game rooms inside the list.

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

public
showLimboRooms: Boolean (read, write)
Show/hide the limbo rooms inside the list.

public
showPrivateRooms: Boolean (read, write)
Show/hide the private rooms (independently of their type).

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

public
spacing: Number (read, write)
The number of pixels dividing the RoomList sub-components (password input field, join/play buttons, etc.).

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

public
watchButton: Button (read-only)
A reference to the "watch" Button component.

public
watchButtonText: String (read, write)
The label of the "watch" button.

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

Constructor


RoomList ( )
RoomList 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 RoomList event.

public
refreshView ( ): Void
Refresh the RoomList view.

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



Property Documentation

cancelButton

public cancelButton: Button (read-only)
A reference to the "cancel" Button component.

This reference allows you to take control over the cancel 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 RoomList's view accordingly.
Check the mCOM Flash components documentation for further details.

The cancel Button default icon can be customized by adding a custom movieclip with the following linkage property to your application library: it.gotoandplay.smartfoxbits.bits.assets.CancelButtonIcon.

NOTE: this button becomes visible when clicking on a private room.

Usage:
To access the cancel Button component:
import com.metaliq.controls.Button
 
var bt:Button = roomList_mc.cancelButton
bt.height = 50
roomList_mc.refreshView()

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

defaultRoom

public defaultRoom: String (read, write)
The default room to join after a succesful login.

You can both pass the name of the room to join or it's 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.

Usage:
To set the default room:
roomList_mc.defaultRoom = "The Garden"

See also:

errorsDisplayTime

public errorsDisplayTime: Number (read, write)
The number of seconds error messages must remain visible for.

If set to 0, error messages (tipically room join errors) won't be displayed.

Usage:
To set the display time:
roomList_mc.errorsDisplayTime = 3

errorTextField

public errorTextField: TextField (read-only)
A reference to the error message TextField.

This reference allows you to take control over the error message TextField, to set its properties (for example text styling). Check the Flash documentation for further details.

Usage:
To access the error message TextField:
var tf:TextField = roomList_mc.errorTextField
tf.textColor = 0xCC0000

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.

Usage:
To group room by type:
roomList_mc.groupByRoomType = true

See also:

height

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

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

Usage:
To set the RoomList's height:
roomList_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 room icon 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 RoomList's label function:
function setCustomRoomIcon(item):String
{
	room = item.roomData
	
	if (room.isLimbo())
		return "http://www.smartfoxserver.com/smartFoxBits/iconLimbo.jpg"
	else
		if (room.isGame())
			return "http://www.smartfoxserver.com/smartFoxBits/iconGame.swf"
		else
			return "http://www.smartfoxserver.com/smartFoxBits/iconChat.jpg"
}
 
roomList_mc.iconFunction = setCustomRoomIcon

See also:

joinButton

public joinButton: Button (read-only)
A reference to the "join"/"play" Button component.

This reference allows you to take control over the join/play 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 RoomList's view accordingly.
Check the mCOM Flash components documentation for further details.

NOTE: this button becomes visible when clicking on a private room, or a game room accepting spectators. If the room's 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.

Usage:
To access the join/play Button component:
import com.metaliq.controls.Button
 
var bt:Button = roomList_mc.joinButton
bt.height = 50
roomList_mc.refreshView()

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

joinButtonText

public joinButtonText: String (read, write)
The label of the "join" button.

Usage:
To set the join button label:
roomList_mc.joinButtonText = "Join"

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 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 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 room name (this would be the standard label for each list item, but the RoomList component uses an internal label function to set a more informative label; see the example below).
  • data:Number
    The room ID.
  • icon:String
    The default icon linkage name (undefined if the showIcons property is set to false). The RoomList component uses five different default icons, depending on the room type (see the RoomList class description).
  • 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/icon to display specific room informations like number of current users/players/spectators, room type, capacity, etc.

Usage:
To set the RoomList's label function:
roomList_mc.labelFunction = setCustomRoomLabel

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

function setCustomRoomLabel(item:Object):String
{
	var room:Room = item.roomData
	var label:String = "<font size='10'>" + room.getName() + "</font>"
	
	if (!room.isLimbo())
	{
		label += "<br>"
		label += "<font size='9' 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:

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:
roomList_mc.labelMargin = 30

passwordLabel

public passwordLabel: Label (read-only)
A reference to the "password" Label component.

This reference allows you to take control over the password 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 RoomList's view accordingly.
Check the mCOM Flash components documentation for further details.

NOTE: this label becomes visible when clicking on a private room, and only if the passwordLabelText property is not null.

Usage:
To access the password Label component:
import com.metaliq.controls.Label
 
var lb:Label = roomList_mc.passwordLabel
lb.setInstanceStyle("fontColor", 0xFFCC00)

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

passwordLabelText

public passwordLabelText: String (read, write)
The label text of the password input field.

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

Usage:
To set the password label text:
roomList_mc.passwordLabelText = "Enter password for this room:"

See also:

passwordTextInput

public passwordTextInput: TextInput (read-only)
A reference to the "password" TextInput component.

This reference allows you to take control over the password TextInput 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 RoomList's view accordingly.
Check the mCOM Flash components documentation for further details.

NOTE: this label becomes visible when clicking on a private room.

Usage:
To access the password TextInput component:
import com.metaliq.controls.TextInput
 
var ti:TextInput = roomList_mc.passwordTextInput
ti.setInstanceStyle("fontColor", 0xFFCC00)

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

playButtonText

public playButtonText: String (read, write)
The label of the "play" button.

Usage:
To set the play button label:
roomList_mc.playButtonText = "Play"

See also:

roomsList

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

This reference allows you to take control over the rooms 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 RoomList component size.
Check this document for details about the list's RowRenderer.

Usage:
To access the rooms AdvancedList component:
import com.metaliq.controls.AdvancedList
 
var al:AdvancedList = roomList_mc.roomsList
al.setInstanceStyle("fontColor", 0xFFCC00)

See also:

rowHeight

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

Usage:
To set the height:
roomList_mc.rowHeight = 20

showChatRooms

public showChatRooms: Boolean (read, write)
Show/hide the chat rooms inside the list.

Usage:
To hide the chat rooms:
roomList_mc.showChatRooms = false

See also:

showFocusRectangle

public showFocusRectangle: Boolean (read, write)
Show/hide the focus rectangle around the rooms list, the password input field, and the join/play/watch/cancel buttons.

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

showGameRooms

public showGameRooms: Boolean (read, write)
Show/hide the game rooms inside the list.

Usage:
To hide the game rooms:
roomList_mc.showGameRooms = false

See also:

showIcons

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

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

showLimboRooms

public showLimboRooms: Boolean (read, write)
Show/hide the limbo rooms inside the list.

Usage:
To hide the limbo rooms:
roomList_mc.showLimboRooms = false

See also:

showPrivateRooms

public showPrivateRooms: Boolean (read, write)
Show/hide the private rooms (independently of their type).

Usage:
To hide the private rooms:
roomList_mc.showPrivateRooms = false

See also:

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, or set it to DESC to have a descending order.
If the groupByRoomType property is set to true, the ordering isn't applied to the full list but to the single groups only.

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

See also:

spacing

public spacing: Number (read, write)
The number of pixels dividing the RoomList sub-components (password input field, join/play buttons, etc.).

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

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 rooms, 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 RoomList items are rendered, even those out of sight: in case lots of rooms must be displayed, scrolling may become CPU consuming.

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

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

watchButton

public watchButton: Button (read-only)
A reference to the "watch" Button component.

This reference allows you to take control over the watch 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 RoomList's view accordingly.
Check the mCOM Flash components documentation for further details.

NOTE: this button becomes visible when clicking on a game room accepting spectators.

Usage:
To access the watch Button component:
import com.metaliq.controls.Button
 
var bt:Button = roomList_mc.watchButton
bt.height = 50
roomList_mc.refreshView()

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

watchButtonText

public watchButtonText: String (read, write)
The label of the "watch" button.

Usage:
To set the watch button label:
roomList_mc.watchButtonText = "Watch"

See also:

width

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

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

Usage:
To set the RoomList's width:
roomList_mc.width = 600

See also:


Constructor Documentation

RoomList

function RoomList()
RoomList 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 RoomList event.

You can register to events fired by the RoomList component, in case you need to be notified to execute your own code.
The RoomList 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
 
roomList_mc.addEventListener(BitEvent.onRoomChange, 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 RoomList 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 RoomList view.

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

removeEventListener

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

Usage:
To remove a listener:
roomList_mc.removeEventListener(BitEvent.onRoomChange, myListener)

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

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


The documentation was generated from the following file: