Main Page | Packages | Class Tree | Index

it.gotoandplay.smartfoxbits.bits

class ChatBox

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


class ChatBox
extends MovieClip

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

The SmartFoxBits' ChatBox component enables public interaction among users inside a server room, allowing them to write and read public text messages, or private cross-room interaction, by means of private text messages. The component 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 components, these items are based on the mCOM Flash components. You can read more about these components and their features here.

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).

Usage:
Drag & drop the ChatBox 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.
During run-time, as soon as a server room is joined, the component 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, set the privateChatMode property to true and set the privateChatUserId property to the user ID of the user you want to establish private communication with.

NOTE: public user interaction is not enabled if a "Limbo" room is joined.


Author:

Version:
1.0.0 - First release.

Since:
SmartFoxBits v1.0

Example:
To instantiate the ChatBox at run-time, make sure it's contained in your library and write the following:
import it.gotoandplay.smartfoxbits.bits.ChatBox
 
var chatBox_mc:ChatBox = ChatBox(attachMovie("ChatBox", "chatBox_mc", 2))
chatBox_mc.labelText = "Enter your message here"

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

var chatBox_mc = attachMovie("ChatBox", "chatBox_mc", 2)
NOTE 2: in the following examples chatBox_mc represents the ChatBox instance name.

See also:


Property Summary

public
adminMessageHeader: String (read, write)
The html text displayed before an Administrator message in the main chat area.

public
chatTextArea: TextArea (read-only)
A reference to the chat TextArea component.

public
clearButton: Button (read-only)
A reference to the "clear" Button component.

public
colorPicker: ColorPicker (read-only)
A reference to the ColorPicker component.

public
groupMessages: Boolean (read, write)
Group messages per sender.

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

public
initialMessage: String (read, write)
The initial message to be displayed inside the message input field.

public
labelText: String (read, write)
The text of the label located above the message input field.

public
messageHeader: String (read, write)
The html text displayed before a message in the main chat area.

public
messageLabel: Label (read-only)
A reference to the message input Label component.

public
messageQueue: Array (read-only)
The queue of sent and received messages.

public
messageTextInput: TextInput (read-only)
A reference to the message TextInput component.

public
moderatorMessageHeader: String (read, write)
The html text displayed before a Moderator message in the main chat area.

public
privateChatMode: Boolean (read, write)
Enable/disable the "private chat" mode.

public
privateChatUserId: Number (read-only)
The SmartFoxServer ID of the user the ChatBox is listeng to in "private chat" mode.

public
restrict: String (read, write)
The set of characters that a user may or may not enter into the message input field.

public
roomJoinAlert: String (read, write)
The html text displayed in the main chat area when the user joins the chat room.

public
sendButton: Button (read-only)
A reference to the "send" Button component.

public
sendButtonText: String (read, write)
The label of the "send" button.

public
showClearButton: Boolean (read, write)
Show/hide the "clear" button.

public
showColorPicker: Boolean (read, write)
Show/hide the color picker tool.

public
showFocusRectangle: Boolean (read, write)
Show/hide the focus rectangle around the input field, the color picker and the send button.

public
spacing: Number (read, write)
The number of pixels dividing the ChatBox sub-components (message input field, color picker, send button, chat text area).

public
systemAlertsColor: Number (read, write)
The default color of system messages in the main chat area.

public
userEnterRoomAlert: String (read, write)
The html text displayed in the main chat area whenever a user enters the chat room.

public
userLeaveRoomAlert: String (read, write)
The html text displayed in the main chat area whenever a user leaves the chat room.

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

Constructor


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

public
clear ( ): Void
Clear the chat area.

public
refreshView ( ): Void
Refresh the ChatBox view.

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

public
setPrivateChatUserId ( userId: Number, msgQueue: Array ): Void
Set the SmartFoxServer ID of the user the ChatBox is listeng to in "private chat" mode.



Property Documentation

adminMessageHeader

public adminMessageHeader: String (read, write)
The html text displayed before an Administrator message in the main chat area.

This header is an html text that comes before 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. #user placeholder is excluded.

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

Usage:
To set header text:
chatBox_mc.adminMessageHeader = "<b>[#date - #time] The Administrator says:</b><br>"

NOTE: in this example the header will be in bold and separated by the message body by a line break. The resulting text will be, for example: [15/03/2007 - 11:23:42] The Administrator says:

See also:

chatTextArea

public chatTextArea: TextArea (read-only)
A reference to the chat TextArea component.

This reference allows you to take control over the chat TextArea mCOM component, to set its properties. Please notice that changing the component size via ActionScript won't affect the rendering on screen, as TextArea is always resized to match the component size.
Check the mCOM Flash components documentation for further details.

Usage:
To access the chat TextArea component:
import com.metaliq.controls.TextArea
 
var ta:TextArea = chatBox_mc.chatTextArea
ta.wordWrap = false

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

clearButton

public clearButton: Button (read-only)
A reference to the "clear" Button component.

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

The clear 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.ClearButtonIcon.

Usage:
To access the clear Button component:
import com.metaliq.controls.Button
 
var bt:Button = chatBox_mc.clearButton
bt.setSize(20, 20)
chatBox_mc.refreshView()

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

colorPicker

public colorPicker: ColorPicker (read-only)
A reference to the ColorPicker component.

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

Usage:
To access the ColorPicker component:
import com.metaliq.controls.ColorPicker
 
var cp:ColorPicker = chatBox_mc.colorPicker
cp.value = 0xFFCC00

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

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.

Usage:
To group messages:
chatBox_mc.groupMessages = true

See also:

height

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

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

Usage:
To set the ChatBox's height:
chatBox_mc.height = 600

See also:

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 is focused. It should be set to empty if the message field label is made visible.

Usage:
To set the initial message:
chatBox_mc.initialMessage = "Enter your message here"

See also:

labelText

public labelText: String (read, write)
The text of the label located above the message input field.

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

Usage:
To set the label:
chatBox_mc.labelText = "Enter your message here:"

See also:

messageHeader

public messageHeader: String (read, write)
The html text displayed before a message in the main chat area.

The message header is an html text that comes before 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's 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 (h:mm:ss);
  • #date - displays the date at which the message was received (dd/mm/yyyy);
  • #room - displays the room name;

Usage:
To set header text:
chatBox_mc.messageHeader = "<b>[#date - #time] #user says:</b><br>"

NOTE: in this example the header will be in bold and separated by the message body by a line break. The resulting text will be, for example: [15/03/2007 - 9:34:18] Jack says:

See also:

messageLabel

public messageLabel: Label (read-only)
A reference to the message input Label component.

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

Usage:
To access the username's Label component:
import com.metaliq.controls.Label
 
var lb:Label = chatBox_mc.messageLabel
lb.setInstanceStyle("fontColor", 0xFFCC00)

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

messageQueue

public messageQueue: Array (read-only)
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.

Usage:
To retrieve the last received message:
import it.gotoandplay.smartfoxserver.User
 
var queue:Array = chatBox_mc.messageQueue
var msgObj:Object = queue[queue.length - 1]
 
var senderName:String = msgObj.userName
var message:String = msgObj.text
 
trace("Message from " + senderName + ": " + message)

See also:

messageTextInput

public messageTextInput: TextInput (read-only)
A reference to the message TextInput component.

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

Usage:
To access the message TextInput component:
import com.metaliq.controls.TextInput
 
var ti:TextInput = chatBox_mc.messageTextInput
ti.setInstanceStyle("fontColor", 0xFFCC00)

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

moderatorMessageHeader

public moderatorMessageHeader: String (read, write)
The html text displayed before a Moderator message in the main chat area.

This header is an html text that comes before 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. #user placeholder is excluded.

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

Usage:
To set header text:
chatBox_mc.moderatorMessageHeader = "<b>[#date - #time] The Moderator says:</b><br>"

NOTE: in this example the header will be in bold and separated by the message body by a line break. The resulting text will be, for example: [15/03/2007 - 22:16:08] The Moderator says:

See also:

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 specified in the privateChatUserId property are displayed.

NOTE: also Administrator and Moderator messages and some alerts are discarded.

Usage:
To enable "private chat" mode:
chatBox_mc.privateChatMode = true

See also:

privateChatUserId

public privateChatUserId: Number (read-only)
The SmartFoxServer ID of the user 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 to know how to set it.

Usage:
To retrieve the private chat user ID:
var userId:Number = chatBox_mc.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 TextField class documentation in the Flash help for description and usage examples of this property.
By default, tag delimiters ("<" and ">" characters) are not allowed, to prevent possible html textfields corruption.

roomJoinAlert

public roomJoinAlert: String (read, write)
The html text displayed in the main chat area when the user joins the chat room.

Set this property to an empty text to disable the alert.
See the messageHeader property description to know which placeholders can be used to display dynamic data in the alert message.

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

Usage:
To set alert text:
chatBox_mc.roomJoinAlert = "<i>You entered #room room</i>"

NOTE: in this example the alert will be in italic and the resulting text will be, for example: You entered The Hall room

See also:

sendButton

public sendButton: Button (read-only)
A reference to the "send" Button component.

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

Usage:
To access the send Button component:
import com.metaliq.controls.Button
 
var bt:Button = chatBox_mc.sendButton
bt.height = 100
chatBox_mc.refreshView()

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

sendButtonText

public sendButtonText: String (read, write)
The label of the "send" button.

Usage:
To set the send button label:
chatBox_mc.sendButtonText = "Send"

showClearButton

public showClearButton: Boolean (read, write)
Show/hide the "clear" button.

Usage:
To show the clear button:
chatBox_mc.showClearButton = true

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.

Usage:
To hide the color picker:
chatBox_mc.showColorPicker = false

To set the color picker selected color programmatically:

import com.metaliq.controls.ColorPicker
 
var cp:ColorPicker = chatBox_mc.colorPicker
cp.value = 0xFFCC00

showFocusRectangle

public showFocusRectangle: Boolean (read, write)
Show/hide the focus rectangle around the input field, the color picker and the send button.

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

spacing

public spacing: Number (read, write)
The number of pixels dividing the ChatBox sub-components (message input field, color picker, send button, chat text area).

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

systemAlertsColor

public systemAlertsColor: Number (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, like messages headers, user enter/leave room alerts, room join alert, administrator messages.
You can override this default value for a specific system alert using the font tag in the alert text, setting the color property.

Usage:
To set system messages color:
chatBox_mc.systemAlertsColor = 0xCC0000

See also:

userEnterRoomAlert

public userEnterRoomAlert: String (read, write)
The html text displayed in the main chat area whenever a user enters the chat room.

Set this property to an empty text to disable the alert.
See the messageHeader property description to know which placeholders can be used to display dynamic data in the alert message.

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

Usage:
To set alert text:
chatBox_mc.userEnterRoomAlert = "<i>#user entered the room</i>"

NOTE: in this example the alert will be in italic and the resulting text will be, for example: Jack entered the room

See also:

userLeaveRoomAlert

public userLeaveRoomAlert: String (read, write)
The html text displayed in the main chat area whenever a user leaves the chat room.

Set this property to an empty text to disable the alert.
See the messageHeader property description to know which placeholders can be used to display dynamic data in the alert message.

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

Usage:
To set alert text:
chatBox_mc.userLeaveRoomAlert = "<i>#user left the room</i>"

NOTE: in this example the alert will be in italic and the resulting text will be, for example: Jack left the room

See also:

width

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

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

Usage:
To set the ChatBox's width:
chatBox_mc.width = 600

See also:


Constructor Documentation

ChatBox

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

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

clear

public function clear(): Void
Clear the chat area.

Call this method to empty the chat TextArea and the message TextInput and reset the messages queue.

refreshView

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

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

removeEventListener

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

Usage:
To remove a listener:
chatBox.removeEventListener(BitEvent.onClearClick, 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:

setPrivateChatUserId

public function setPrivateChatUserId(userId: Number,
 msgQueue: Array): Void
Set the SmartFoxServer ID of the user the ChatBox is listeng to in "private chat" mode.

Use this method to set the ID of the user 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 wasn't done 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 component, 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.

Usage:
To set the private chat user ID:
chatBox_mc.setPrivateChatUserId(15)

Or:

chatBox_mc.setPrivateChatUserId(15, previousChatMessagesArray)

Parameters:
userId
The ID of the user to enable private chatting with.
msgQueue
The initial messages queue to be displayed: an array with the same data structure of the messageQueue property.
See also:


The documentation was generated from the following file: