Simple Chat

 Previous Next Print

Before you read

  • It may be useful to read Connect and Login
  • Find the Simple Chat example files in [installation folder]/code_examples/SimpleChat

Overview

In this tutorial we'll look at an existing chat example to see how it was constructed. This uses the Flex Framework so that we can easily make use of scroll bars, list boxes, and buttons. We'll focus on the code relevant to chatting and assume you know the basics of MXML.

 

The UI

This is a Flex application and uses MXML to define the UI. There are three states to this UI that are all added to a view stack. We just tell the view stack which state to show at the appropriate time. At any given time one of the following will be showing:

  • waitingPanel - This shows whenever the client is waiting. So, when the client is waiting for a connection response, login response, or JoinRoomEvent.
  • loginPanel - Shows after a successful connection response to allow the user to login.
  • chatPanel - Shows after a JoinRoomEvent so the user can view other users in the room and participate in a chat.

Event listeners

Since connecting and logging in is talked about in detail in the Connect and Login tutorial and Understanding Connections, we won't here. Instead we'll look at the event listeners used and then move on to the message objects that are used to build this chat.

The ConnectionResponse and LoginResponse are used to capture the connection event and the response to the LoginRequest. The JoinRoomEvent is fired when the user is joined to a room (see below for the CreateRoomRequest ). The PublicMessagEvent occurs whenever a message is sent by anyone in the room. And the UserUpdateEvent occurs whenever the user list changes or someone updates their user variables - which is not part of this example.

 

Joining a room

A room can be joined in one of three ways:

  • The client creates a CreateRoomRequest as is done here.
  • The client joins an already existing room using the JoinRoomRequest.
  • The server puts the client in a room via custom code.

No matter how the room is joined, it will result in a JoinRoomEvent.

 

In this application when a successful LoginResponse is received the code in the onLoginResponse event handler calls the joinRoom() function.

First a CreateRoomRequest is created, and then the roomName and zoneName properties are populated. These can be anything. If the room being created already exists then the user will be joined to that room.  The CreateRoomRequest only requires that roomName and zoneName be populated. However, it is the most flexible request in the entire API. There many other properties that can be modified to achieve a variety of customized room behaviors. You can learn more about that by reading the code-level documentation of the CreateRoomRequest here.

 

A zone is nothing more than a collection of rooms. A room must exist in a zone. The zone is automatically created as needed to hold a room. A room's name must be unique within that zone, and room names can be reused in other zones.

 

onJoinRoomEvent

The onJoinRoomEvent function is fired when the user joins a room. We use this event to grab a reference to the Room object that represents this room, call a function to show the user list, and display the chat panel.

You'll notice in the first line within the function we are setting the _room property. It uses the managerHelper to do this. Here is what is going on:

  • The event object contains the id of the room and the id of the zone that holds that room.
  • We use this zone id and room id to locate the Room instance being managed by the managerHelper.
  • We store that reference as the _room variable so it can be used later when we send chat messages.

The managerHelper (which is described in the Client API at a Glance tutorial) is a very useful class. It internally listens for important server messages and uses those to maintain a list of all zones, rooms, and users that you can "see". It also keeps track of the online/offline state of your buddies, and keeps user variables and room variables up to date.

 

So, the line of code above access the zoneManager and grabs the Zone instance off of it by specifying the zoneId. It then grabs the Room instance off of the Zone instance by specifying the roomId.

 

Showing the user list

Showing the user list using the Flex Framework and a List component is very simple.

The _room instance maintains an array of User instances that represent all of the users in your room. It stores these in an array, _room.users. To use this list to populate a List component, just set the array as the value of the List's dataProvider. But you have to tell it which field on the User instance to use for the display. You do that by setting the List's labelField property to "userName".

 

This function is called when you join the room and whenever the UserUpdateEvent is fired.

 

Chatting

To send a chat message to the room you create PublicMessageRequest, tell it which roomId and zoneId to go to, give it a message, and then send it. Here is the function that does that in this application.

This code uses the _room instance to get access to the room id and zone id. It pulls the message string from the text field on screen. It then clears out the text field (since the message was sent).

 

Displaying a chat message is straight forward. Capture the PublicMessagEvent and then use the information on the event object to add a chat message to the screen. Here is the function that does that in this application.

This code simply adds a new line to the historyField which is on screen, using the userName and message properties of the event object. Then the scroll property is updated so that the latest message is always shown.