+Show TOC
×Hide TOC

ChatBox

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

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

The SmartFoxBits ChatBox control allows (a) public interaction among users inside the same SmartFoxServer room, by means of public text messages, and (b) private cross-room interaction, by means of private text messages.
The control contains a textfield to input the message, a color picker to set the message color, a send button and a text area where sent and received messages are displayed. 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 ChatBox can be customized by hiding the color picker tool and setting the input field label, its initial message and the button label. You can also set your custom system messages that appear inside the main chat area, like the header in front of each user message, the alerts in case of user entering/leaving the chat room, the Administrator and Moderator messages' headers.
All this messages can be entered using html formatting, and support a number of parameters to display dynamic data (user name, room name, time, date).

NOTE: in the provided examples, chatBox always indicates a ChatBox 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 ChatBox control from the Components panel and drop it in the Flex Design View. The ChatBox properties can be set in Flex Properties panel or in the Source View (by editing the MXML tag) at author-time.
The ChatBox instance can also be created and its properties set at run-time, using ActionScript.
The ChatBox communicates with SmartFoxServer through the Connector control: read the Connector's class description for additional informations.
During run-time usage, as soon as a SmartFoxServer room is joined, the control is enabled and the user can enter a message and hit the button (or the Enter key) to send it.
To use the ChatBox for private chatting, make use of the setPrivateChatUserId method to enable the "private chat" mode and set the ID of the user you want to establish private communication with.
NOTE: public user interaction is not available if a "Limbo" room is joined.
Styling
The following styles are available for the ChatBox control:
gap
paddingBottom
paddingLeft
paddingRight
paddingTop
Styles can be applied using the standard Flex styling systems. Check the Flex documentation for additional informations.

Example:

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

<sfb:ChatBox id="chatBox" />

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

import com.smartfoxserver.smartfoxbits.bits.ChatBox

// Create ChatBox instance
var chatBox:ChatBox = new ChatBox()

// Add ChatBox instance to the display list
addChild(chatBox)

Events broadcasted to listeners:

BitEvent with type: CLEAR_CLICK
- Dispatched by the ChatBox component when the clearButton button is pressed.

Summary

Constructor

ChatBox

Instance properties

inputLabelText : String
- The text of the label located above the message input field.
sendButtonText : String
- The label of the "send" button.
privateChatMode : Boolean
- Enable/disable the "private chat" mode.
groupMessages : Boolean
- Group messages per sender.
initialMessage : String
- The initial message to be displayed inside the message input field.
messageHeader : String
- The html text displayed in front of a message in the main chat area.
adminMessageHeader : String
- The html text displayed in front of an Administrator message in the main chat area.
moderatorMessageHeader : String
- The html text displayed in front of an Moderator message in the main chat area.
roomJoinAlert : String
- The html text displayed in the main chat area when the current user joins the chat room.
userEnterRoomAlert : String
- The html text displayed in the main chat area whenever a user enters the current chat room.
userLeaveRoomAlert : String
- The html text displayed in the main chat area whenever a user leaves the current chat room.
restrict : String
- The set of characters that a user may or may not enter into the message input field.
showClearButton : Boolean
- Show/hide the "clear" button.
showColorPicker : Boolean
- Show/hide the color picker tool.
systemAlertsColor : uint
- The default color of system messages in the main chat area.
messageLabel : Label
- A reference to the message input Label control.
sendButton : Button
- A reference to the "send" Button control.
clearButton : Button
- A reference to the "clear" Button control.
messageTextInput : TextInput
- A reference to the message TextInput control.
chatTextArea : TextArea
- A reference to the chat TextArea control.
colorPicker : ColorPicker
- A reference to the ColorPicker control.
messageQueue : Array
- The queue of sent and received messages.
privateChatUserId : Number
- The SmartFoxServer ID of the user that the ChatBox is listeng to in "private chat" mode.

Instance methods

destroy : void
- Destroy the ChatBox instance.
clear : void
- Clear the chat area.
setPrivateChatUserId (userId:Number, msgQueue:Array = null) : void
- Set the SmartFoxServer ID of the user that the ChatBox is listening to in "private chat" mode.
setMessagesQueue (msgQueue:Array) : void
- Set the list of messages to be displayed in the ChatBox.

Constructor

ChatBox

public function ChatBox (

)

ChatBox constructor.

Example:

See the example in the class description.

Instance properties

adminMessageHeader

public adminMessageHeader:String

(read,write)

The html text displayed in front of an Administrator message in the main chat area.
This header is an html text placed in front of each Administrator message displayed in the chat area.
See the messageHeader property description to know which placeholders can be used to display dynamic data in the header; only the #user placeholder is excluded.

NOTE: an empty line is always added before and after this alert, to highlight the Administrator message.

Example:

To set the header text in MXML:
```
<sfb:ChatBox adminMessageHeader="[#date - #time] The Administrator says: " />
```
To set the header text in ActionScript:
```
chatBox.adminMessageHeader = "[#date - #time] The Administrator says: "
```
NOTE: in this example the header is bold and separated by the message body by a line break. The resulting text is, for example: [15/03/2007 - 11:23:42] The Administrator says:

See also:

Component metadata:

Bindable	"adminMsgHeaderChanged"
Inspectable	category: "Common" defaultValue: "

chatTextArea

public chatTextArea:TextArea

(read)

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

Example:

To access the chat TextArea control in ActionScript:

import mx.controls.TextArea

var ta:TextArea = chatBox.chatTextArea
ta.wordWrap = false

clearButton

public clearButton:Button

(read)

A reference to the "clear" Button control.
This property allows you to get a reference to the clear Flex Button control, to set its properties (for example size). Check the Flex Components documentation for additional details.

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 clear Button control in ActionScript:

import mx.controls.Button

var button:Button = chatBox.clearButton
button.width = 20
button.height = 20

chatBox.invalidateDisplayList()

colorPicker

public colorPicker:ColorPicker

(read)

A reference to the ColorPicker control.
This property allows you to get a reference to the Flex ColorPicker control, to set its properties. Check the Flex Components documentation for additional details.

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

Example:

To access the ColorPicker control in ActionScript:

import mx.controls.ColorPicker

var cp:ColorPicker = chatBox.colorPicker
cp.showTextField = true

groupMessages

public groupMessages:Boolean

(read,write)

Group messages per sender.
Setting this property to true enables the messages grouping: if two or more messages in a row come from the same sender, only the first header is displayed.
If set to false, each message will have its own header, whether the sender is the same or not.

Example:

To enable messages grouping using MXML:
```
<sfb:ChatBox groupMessages="true" />
```
To enable messages grouping using ActionScript:
```
chatBox.groupMessages = true
```

See also:

messageHeader

Component metadata:

Bindable	"groupMessagesFlag"
Inspectable	category: "Common" defaultValue: true name: "Group messages" type: Boolean

initialMessage

public initialMessage:String

(read,write)

The initial message to be displayed inside the message input field.
This message disappears as soon as the input field gains focus. It should be set to an empty string if the message field label is visible.

Example:

To set the initial message in MXML:

<sfb:ChatBox initialMessage="Enter your message here" />

To set the initial message in ActionScript:

chatBox.initialMessage = "Enter your message here"

See also:

inputLabelText

Component metadata:

Bindable	"initialMessageChange"
Inspectable	category: "Common" defaultValue: "Enter your message here" name: "Initial message"

inputLabelText

public inputLabelText:String

(read,write)

The text of the label located above the message input field.
If left empty (as by default), the label doesn't show up in the control.

Example:

To set the label in MXML:

<sfb:ChatBox inputLabelText="Enter your message here:" />

To set the label in ActionScript:

chatBox.inputLabelText = "Enter your message here:"

See also:

Component metadata:

Bindable	"labelTextChange"
Inspectable	category: "Common" defaultValue: "" name: "Label text"

messageHeader

public messageHeader:String

(read,write)

The html text displayed in front of a message in the main chat area.
The message header is an html text placed in front of each new message displayed in the chat area. If groupMessages is set to true, the header is displayed only if the sender of the new message differs from the sender of the previous message.
It is possible to show dynamic data in the header using the following placeholders:

#user: displays the sender's username;
#time: displays the time at which the message was received (format is h:mm:ss);
#date: displays the date at which the message was received (format is dd/mm/yyyy);
#room: displays the room name.

Example:

To set the header text in MXML:
```
<sfb:ChatBox messageHeader="[#date - #time] #user says: " />
```
To set the header text in ActionScript:
```
chatBox.messageHeader = "[#date - #time] #user says: "
```
NOTE: in this example the header is bold and separated by the message body by a line break. The resulting text is, for example: [15/03/2007 - 9:34:18] Jack says:

See also:

Component metadata:

Bindable	"messageHeaderChange"
Inspectable	category: "Common" defaultValue: "

messageLabel

public messageLabel:Label

(read)

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

Example:

To access the message input Label control in ActionScript:

import mx.controls.Label

var label:Label = chatBox.messageLabel
label.setStyle("color", 0xFFCC00)

messageQueue

public messageQueue:Array

(read)

The queue of sent and received messages.
The messageQueue property is an array containing all messages sent or received since when the user entered the room. Message headers are excluded.
Each item in the queue is an object with the following properties:

userId:Number
The SmartFoxServer user ID of the message sender. For system messages (user enter/leave room, administrator messages, etc.) this property is undefined.
userName:String
The name of the message sender. For system messages (user enter/leave room, administrator messages, etc.) this property is undefined.
text:String
The message text.

Example:

To retrieve the last message received:

var queue:Array = chatBox.messageQueue
var msgObj:Object = queue[queue.length - 1]

var senderName:String = msgObj.userName
var message:String = msgObj.text

trace("Message from " + senderName + ": " + message)

messageTextInput

public messageTextInput:TextInput

(read)

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

Example:

To access the message TextInput control in ActionScript:

import mx.controls.TextInput

var ti:TextInput = chatBox.messageTextInput
ti.setStyle("color", 0xFFCC00)

moderatorMessageHeader

public moderatorMessageHeader:String

(read,write)

The html text displayed in front of an Moderator message in the main chat area.
This header is an html text placed in front of each Moderator message displayed in the chat area.
See the messageHeader property description to know which placeholders can be used to display dynamic data in the header; only the #user placeholder is excluded.

NOTE: an empty line is always added before and after this alert, to highlight the Moderator message.

Example:

To set the header text in MXML:
```
<sfb:ChatBox moderatorMessageHeader="[#date - #time] The Moderator says: " />
```
To set the header text in ActionScript:
```
chatBox.moderatorMessageHeader = "[#date - #time] The Moderator says: "
```
NOTE: in this example the header is bold and separated by the message body by a line break. The resulting text is, for example: [15/03/2007 - 22:16:08] The Moderator says:

See also:

Component metadata:

Bindable	"moderatorMessageHeaderChange"
Inspectable	category: "Common" defaultValue: "

privateChatMode

public privateChatMode:Boolean

(read,write)

Enable/disable the "private chat" mode.
Setting this property to true enables the "private chat" mode: public messages are discarded and only private messages coming from the user selected through the privateChatUserId property are displayed.

NOTE: when in private mode, also Administrator and Moderator messages and some alerts are discarded.

Example:

To disable the "private chat" mode using MXML:
```
<sfb:ChatBox privateChatMode="false" />
```
To disable the "private chat" mode using ActionScript:
```
chatBox.privateChatMode = false
```

See also:

Component metadata:

Bindable	"privateChatModeChanged"

privateChatUserId

public privateChatUserId:Number

(read)

The SmartFoxServer ID of the user that the ChatBox is listeng to in "private chat" mode.
This property contains the ID of the user that the ChatBox is currently receiving private messages from. This is a "read-only" property: check the setPrivateChatUserId method for additional informations.

Example:

To retrieve the private chat user ID:

var userId:Number = chatBox.privateChatUserId

See also:

restrict

public restrict:String

(read,write)

The set of characters that a user may or may not enter into the message input field.
Check the Flex TextInput control documentation for a description and usage examples of this property.
By default, tag delimiters ("<" and ">" characters) are not allowed, to prevent possible html textfields corruption.

Component metadata:

Inspectable	category: "Common" defaultValue: "

roomJoinAlert

public roomJoinAlert:String

(read,write)

The html text displayed in the main chat area when the current user joins the chat room.
See the messageHeader property description to know which placeholders can be used to display dynamic data in the alert message; set this property to an empty string to disable the alert.

NOTE: a line break is always added at the end of this alert.

Example:

To set the join alert text in MXML:
```
<sfb:ChatBox roomJoinAlert="You entered #room room" />
```
To set the join alert text in ActionScript:
```
chatBox.roomJoinAlert = "You entered #room room"
```
NOTE: in this example the alert is italic and the resulting text is, for example: You entered The Hall room

See also:

Component metadata:

Bindable	"roomJoinAlertChange"
Inspectable	category: "Common" defaultValue: "

sendButton

public sendButton:Button

(read)

A reference to the "send" Button control.
This property allows you to get a reference to the send Flex Button control, to set its properties (for example size). Check the Flex Components documentation for additional details.

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 send Button control in ActionScript:

import mx.controls.Button

var button:Button = chatBox.sendButton
button.height = 100

chatBox.invalidateDisplayList()

sendButtonText

public sendButtonText:String

(read,write)

The label of the "send" button.

Example:

To set the send button label in MXML:
```
<sfb:ChatBox sendButtonText="Send" />
```
To set the send button label in ActionScript:
```
chatBox.sendButtonText = "Send"
```

See also:

inputLabelText

Component metadata:

Bindable	"sendButtonTextChanged"
Inspectable	category: "Common" defaultValue: "Send" name: "Button text"

showClearButton

public showClearButton:Boolean

(read,write)

Show/hide the "clear" button.

Example:

To show the clear button using MXML:
```
<sfb:ChatBox showClearButton="true" />
```
To show the clear button using ActionScript:
```
chatBox.showClearButton = true
```

Component metadata:

Inspectable	category: "Common" defaultValue: false name: "Show clear button" type: Boolean

showColorPicker

public showColorPicker:Boolean

(read,write)

Show/hide the color picker tool.
As the message color is taken from the ColorPicker, even if it is hidden you can set its color accessing the component programmatically, through the colorPicker property.

Example:

To hide the color picker using MXML:

<sfb:ChatBox showColorPicker="false" />

To hide the color picker using ActionScript:

chatBox.showColorPicker = false

To set the color picker selected color programmatically:

import mx.controls.ColorPicker

var cp:ColorPicker = chatBox.colorPicker
cp.selectedColor = 0xFFCC00

Component metadata:

Inspectable	category: "Common" defaultValue: true name: "Show color picker" type: Boolean

systemAlertsColor

public systemAlertsColor:uint

(read,write)

The default color of system messages in the main chat area.
This property sets the default color of all the system alerts displayed in the main chat area: messages headers, user enter/leave room alerts, room join alert, administrator and moderator messages.

NOTE: you can override this default value for a specific system message using the font tag in the alert text itself, setting the color property.

Example:

To set the global system alerts color using MXML:
```
<sfb:ChatBox systemAlertsColor="#CC0000" />
```
To set the global system alerts color ActionScript:
```
chatBox.systemAlertsColor = 0xCC0000
```

See also:

Component metadata:

Bindable	"systemAlertsColorChange"
Inspectable	category: "Common" defaultValue: "#666666" format: "Color" name: "System alerts color"

userEnterRoomAlert

public userEnterRoomAlert:String

(read,write)

The html text displayed in the main chat area whenever a user enters the current chat room.
See the messageHeader property description to know which placeholders can be used to display dynamic data in the alert message; set this property to an empty string to disable the alert.

NOTE: a line break is always added at the end of this alert.

Example:

To set the user join room alert in MXML:
```
<sfb:ChatBox userEnterRoomAlert="#user entered the room" />
```
To set the user join room alert in ActionScript:
```
chatBox.userEnterRoomAlert = "#user entered the room"
```
NOTE: in this example the alert is italic and the resulting text is, for example: Jack entered the room

See also:

Component metadata:

Bindable	"userEnterRoomAlertChange"
Inspectable	category: "Common" defaultValue: "

userLeaveRoomAlert

public userLeaveRoomAlert:String

(read,write)

The html text displayed in the main chat area whenever a user leaves the current chat room.
See the messageHeader property description to know which placeholders can be used to display dynamic data in the alert message; set this property to an empty string to disable the alert.

NOTE: a line break is always added at the end of this alert.

Example:

To set the user leave room alert in MXML:
```
<sfb:ChatBox userLeaveRoomAlert="#user left the room" />
```
To set the user leave room alert in ActionScript:
```
chatBox.userLeaveRoomAlert = "#user left the room"
```
NOTE: in this example the alert is italic and the resulting text is, for example: Jack left the room

See also:

Component metadata:

Bindable	"userLeaveRoomAlertChange"
Inspectable	category: "Common" defaultValue: "

Instance methods

clear

public function clear (

) : void

Clear the chat area.
This method to empties the chat TextArea and the message TextInput and resets the messageQueue property.

Example:

To clear the chat:
```
chatBox.clear()
```

destroy

public function destroy (

) : void

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

setMessagesQueue

public function setMessagesQueue (

msgQueue:Array) : void

Set the list of messages to be displayed in the ChatBox.
In case you track the public messages that are broadcasted inside a room, and want to show the history whenever a user enters that room, this method can be used to pass a list of previous messages to the ChatBox to be displayed immediately (similarly to what can be done with the setPrivateChatUserId method for private chat).

NOTE: the msgQueue parameter must be an array with the same data structure of the messageQueue property.

Parameters:

msgQueue:

the messages queue to be displayed; it must be an array with the same data structure of the messageQueue property.

Example:

To add a list of previous messages to the ChatBox:

connector.connection.addEventListener(SFSEvent.onJoinRoom, addChatHistory)

function addChatHistory(evt:SFSEvent):void
{
    // Get the room id
    var rId:Number = evt.params.room.getId()

    // Retrieve the history for the current room using a custom method
    // which returns an array of objects with the same structure
    // described in the "ChatBox.messageQueue" property
    var previousChatMessagesArray:Array = getChatHistoryForRoom(rId)

    // Inject history in the ChatBox instance
    chatBox.setMessagesQueue(previousChatMessagesArray)
}

function getChatHistoryForRoom(roomId:Number):Array
{
    //...
}

See also:

messageQueue

setPrivateChatUserId

public function setPrivateChatUserId (

userId:Number, msgQueue:Array = null) : void

Set the SmartFoxServer ID of the user that the ChatBox is listening to in "private chat" mode.
Use this method to set the ID of the user that the ChatBox is currently sending/receiving private messages to/from. If the userId parameter is greater than -1, the privateChatMode is set to true even if this was not set before, and the ChatBox interface is enabled; if userId is equal to -1, the ChatBox remains in "private chat" mode, but the interface is disabled.
This method also accepts an array as (optional) second parameter, containing a list of messages to be displayed in the ChatBox immediately. This is useful in case you need to manage several private conversations in one single ChatBox (like in the SmartFoxBits UserList control, for example): each time you change user, you can keep track of the current conversation through the messageQueue property and then pass it back to this method when re-enabling the private chat with a previous user.

NOTE: the msgQueue parameter must be an array with the same data structure of the messageQueue property.

Parameters:

userId :

the ID of the user to enable private chatting with.

msgQueue:

the initial messages queue to be displayed; it must be an array with the same data structure of the messageQueue property.

Example:

To set the private chat user ID:

chatBox.setPrivateChatUserId(15)

Or:

chatBox.setPrivateChatUserId(15, previousChatMessagesArray)

See also: