2.2. Summary of Communication Components

Here are some guidelines to help you understand the following sections on the individual components:

• The corresponding client-side ActionScript class for a FlashCom communication component has a name of the form FCComponentNameClass; for example, the class name of the AudioConference component is FCAudioConferenceClass.

• Most of the communication components have parameters that can be configured in the Properties panel or the Component Inspector panel. If there are parameters that are configurable through the UI for a component, we cover them in the description of each component. All component parameters can also be configured using ActionScript properties of the component as noted. For example, the LatencyThreshold parameter of the ConnectionLight component is configurable using the component's threshold property. Some component parameters are configurable only via ActionScript, such as the username property of the Chat component. It is up to the component developer to determine which properties of a component are exposed in the Properties panel or the Component Inspector panel. The communication components' parameters can be exposed in the Component Definition dialog box (available by right-clicking or Cmd-clicking the component symbol in the Library). For any component written in ActionScript 2.0 (AS 2.0), such as the Flash MX 2004 UI Components, parameters can also be exposed by defining inspectable properties in its .as class file. The Macromedia communication components are not written in AS 2.0; therefore, configurable parameters can't be exposed to the UI via their .as files.

• Unless otherwise specified, the component does not include (nest) any other Flash UI components (see Table 2-1). If a component does require other components, they will be included with the Flash movie automatically.

2.2.1. AudioConference

The AudioConference component enables two or more users to communicate with each other by subscribing to one or more audio-only streams. Each user who wants to publish an audio stream must have a microphone that is compatible with Flash Player 6 or higher. The interface of the component (see Figure 2-2) displays all the connected users. It allows each user to click a Talk button to start sending the audio stream, or the user can select an Auto checkbox wherein the component automatically starts and stops an audio stream when the user begins or stops talking. When a user is talking, a light to the left of the user's name turns green. When the user stops talking, the light reverts to gray.

Figure 2-2. The AudioConference component

2.2.1.1 Nested Flash UI components

The AudioConference component uses four Flash MX UI components: CheckBox, ListBox, PushButton, and ScrollBar.

2.2.1.2 Component process overview

When the AudioConference component loads into a Flash movie, the component uses an existing NetConnection object (which can be provided by a SimpleConnect component) to create or connect to a non-persistent RSO named FCAudioConference.audio.

Whenever a communication component instance uses an RSO, any changes made to the RSO are broadcast to all connected users (or participants) of the same application instance. The communication components do not prohibit or exclude users of the same application instance from sharing data with one another.

This RSO keeps track of each connected user. When a user clicks the Talk button, the component attaches his microphone output to a NetStream instance and sets a property within the RSO to true. This property's name is based on the user's ID, which is provided by the server-side component framework. When other clients receive this updated value in the SharedObject.onSync( ) handler, the audio stream from the other user is played. When the user releases the Talk button, the component sets the RSO's property to false, and the user's microphone output detaches from the stream.

2.2.2. AVPresence

The AVPresence component, by far one of the more popular communication components, allows a user connected to a FlashCom application to send an audio and/or video stream to other users. An AVPresence instance presents a masked area of the user's camera output as shown in Figure 2-3. The user can selectively mute the audio and/or video output. The component displays the microphone's activity level along the right border.

Figure 2-3. The AVPresence component

One of the special attributes of the AVPresence component is that it can be used to either send a user's audio/video stream or receive another user's audio/video stream. The AVPresence instance name establishes a unique identifier within the FlashCom application. If you place an AVPresence component instance named user_1_mc within a Flash movie (a .swf file), anyone who loads the Flash movie and connects to the FlashCom application can engage the user_1_mc instance to begin streaming audio/video. Once a user has started to publish a stream with the user_1_mc instance, any other users who have loaded the same Flash movie will start to see that user's stream in their instance of user_1_mc. If you want to provide multiple users simultaneous access to the functionality of the AVPresence component, you will need to create a unique instance of the AVPresence component for each user.

Once a user relinquishes control of an AVPresence instance, another user can use that same instance to start publishing her audio/video stream.

In order for a user to gain access to the AVPresence component, the following events must occur:

2.2.2.1 Client-side component parameters

An instance of the AVPresence component has six unique settings in the Properties panel or the Parameters tab of the Component Inspector (aka the Component Parameters panel). These settings control the quality and data rates of the streams utilized by the component:

Sync Speed

Controls the frequency (in frames per second) at which data is updated from the client to the server. It controls the update frequency of the RSO used by the AVPresence component. Higher values consume more data bandwidth and update the microphone-level display more quickly. The default value is 3 fps. The ActionScript equivalent for this property is updateFps.

Video Width

Sets the capture area width, in pixels, of the camera source used by the AVPresence component. This width should not be confused with scale; the Video Width value establishes the cropping area of the local camera's video. For example, if the native capture area of a camera is 640 x 480 pixels, a Video Width setting of 320 would crop 160 pixels from the left and right margins of the capture frame. The default value for this setting is 120 pixels. The ActionScript equivalent for this property is vidWidth.

Video Height

Sets the capture area height, in pixels, of the local camera source. Like Video Width, Video Height establishes the cropping border of the capture frame. The default value is 120 pixels. The ActionScript equivalent for this property is vidHeight.

Video Bandwidth

Limits the amount of data, in bits per second, that can be consumed by the video portion of the NetStream object used by the AVPresence component. A value of 0 allows the video portion to use the maximum bandwidth available over the Flash movie's connection to the FlashCom Server. The default value is 12,000 bps, equivalent to 11.7 Kbps. The ActionScript equivalent of this property is vidBandwidth.

Video Quality

Sets the quality (0 to 100) of the video portion of the NetStream object used by the AVPresence component. Higher values yield better quality but increase the bandwidth required per frame of video. If you exceed the available bandwidth, the camera source will drop video frames as they are sent over the NetStream object. The default value is 0, which allows the stream to use the maximum quality for the bandwidth allocated to the stream. The ActionScript equivalent for this property is vidQuality.

Video FPS

This value controls the frame rate of the video portion of the NetStream object used by the AVPresence component. Faster frame rates yield smoother motion captured from the user's camera but increase the amount of bandwidth required for the stream. The default value is 10 fps. The ActionScript equivalent for this property is vidFps.

The Video Width, Video Height, Video Bandwidth, Video Quality, and Video FPS settings in the Properties panel for an AVPresence instance are ignored if the SetBandwidth component is also used in the Flash movie. In that case, the SetBandwidth instance's settings override those of the AVPresence instance.

2.2.2.2 Component process overview

The AVPresence component's client-side ActionScript creates several objects within the connect( ) method. These objects allow multiple instances of the AVPresence component to communicate with one another, provided they are connected to the same FlashCom application.

The connect( ) method creates a NetStream instance named ns, which is used to either publish or subscribe to an audio/video stream.

Like most communication components, the AVPresence instance creates an RSO whose name is formed from the prefix value of the component. For an AVPresence instance, the prefix value is of the form:

"FCAVPresence." + instance name + "."

This value is then concatenated to the prototype's soName value, "av". For example, if you place an instance of the AVPresence component on stage and named it speaker_mc in the Properties panel, the name of the RSO created by the AVPresence instance is FCAVPresence.speaker_mc.av.

This RSO tracks two primary properties: broadcast and speakerID. The broadcast property is a Boolean (either true or false). If the AVPresence instance is publishing a stream, broadcast is set to TRue. If the stream is open (that is, no one is publishing on the stream), broadcast is set to false. The speakerID property keeps track of an identification string, indicating which user is publishing on the stream. The ID string for each user is stored within the client-side AVPresence instance, and named userID. The string is determined by the Server-Side ActionScript code built for the AVPresence component.

2.2.3. Chat

The Chat component creates a text-based messaging interface for a Flash movie. The interface of the component, as shown in Figure 2-4, provides a text history area with a scrollbar, a user input text field, and a Send button. You can use the Chat component in combination with the PeopleList component to create a basic chat application as discussed later under "Building a Simple Chat Room." The UserColor component can also be used in conjunction with the Chat component, to assign a color to each user's text in the text history area.

Figure 2-4. The Chat component

2.2.3.1 Nested Flash UI components

The Chat component uses variations of two Flash UI components: PushButton and ScrollBar. You can alter the look of these components by changing the appropriate skin symbols in the Component Skins folder within the Flash document's Library panel.

2.2.3.2 Component process overview

When you place an instance of the Chat component into a Flash movie, the instance needs to be connected to your FlashCom application. As with all communication components, this connection can be made by a SimpleConnect instance, or you can create your own NetConnection object and invoke the Chat.connect( ) method directly.

If you elect to create your own custom connection, you must set up a global client object within the Server-Side ActionScript of your FlashCom application. If you use the SimpleConnect component, this client object is already created for your application. The Server-Side ActionScript code contained with the chat.asc document retrieves each user's name with the Component.getClientGlobalStorage( ) method. The name of each user is stored within a property named username. The value of username is appended to each message that is transferred to each connected client. For more information on getClientGlobalStorage( ), see Chapter 14.

Two RSOs are created by the Server-Side ActionScript of the Chat component: message and history. The full names of these RSOs are created using the same type of formula discussed for the AVPresence component. The prefix value of each shared object begins with "FCChat.", followed by the client-side instance name of the component.

Whenever a user enters a message into the input text field of the Chat component and clicks the Send button, a call( ) method from the client-side Chat instance sends the text of the message to the server-side FCChat.sendMessage( ) method. The Send button of the Chat component is already set up to listen for Enter key events when the input text field has focus. If the user enters a message into the input text field, pressing the Enter (or Return) key automatically sends the message to the FlashCom application.

Once the sendMessage( ) method receives the message text, the server-side code processes the message, inserting the sender's username value and converting any text beginning with "http:" or "www." to HTML-enabled links. The complete message text is then sent to the message( ) method of the message shared object. This shared object carries the message text to each connected client.

The history remote shared object is also instantiated by the server-side FCChat component class. This shared object has one property, also named history, which stores an array wherein each index is a message that has been sent by a client. Whenever a new message is sent over the Chat instance, the message text is pushed into the history array.

2.2.3.3 Configurable server-side attributes

Unlike other communication components, the Chat component has a few features that can be controlled by settings in the server-side chat.asc document. You can find this document in the scriptlib/components folder of your FlashCom installation. The following code appears between lines 33 and 35 of scriptlib/components/chat.asc:

FCChat.prototype.histlen    = 250;    // Maximum history length.
FCChat.prototype.persist    = true;   // Whether to save history.
FCChat.prototype.allowClear = true;   // Allow clients to clear history.

The histlen property controls the maximum length of the history array, which represents the maximum number of messages stored (the default is 250). Increase this number to allow a longer chat history to be stored.

The persist property, as the code comment indicates, determines whether to save the state of the history shared object. If persist is set to TRue (the default), the history of the chat session is saved from one session to the next. Even after an application instance using the Chat component unloads, the history is saved. The history is then reloaded whenever a new application instance starts. If the persist property is set to false, each chat session starts with a blank slateno past messages are loaded into the client-side Chat instance when it starts up.

The allowClear property determines whether the server-side FCChat.clearHistory( ) method can be invoked by client-side ActionScript. By default, the value is TRue, allowing client-side ActionScript to clear the history. To prevent client-side code from clearing the history, set allowClear to false.

2.2.4. ConnectionLight

The ConnectionLight component provides a visual aid to indicate the status of the connection to the server-side FlashCom application.

The status is shown as a colored circle with one of four color states:

Gray

Indicates a connection has yet to be attempted or a prior connection is closed.

Green

Indicates a stable connection (via a NetConnection instance) to the FlashCom application.

Red

Indicates an attempt to connect to the FlashCom application failed or was rejected. This color can also indicate that the current connection was unexpectedly lost or intentionally closed.

Yellow

After making a successful connection to the FlashCom application, the client movie may experience delays with packet submissions. If the delay period exceeds the specified threshold, the light turns yellow.

The ConnectionLight component rechecks the connection's status (connected or disconnected) every half second (500 milliseconds).

If the user clicks the ConnectionLight instance (the colored circle), Flash displays the information overlay shown in Figure 2-5.

Figure 2-5. The information overlay of the ConnectionLight component

The overlay contains more detailed information about the connection status:

Latency

Average time, in milliseconds (ms), for packets to be transmitted from the client movie to the FlashCom Server. Higher latency values can indicate a slow connection (usually on the client side), temporary network congestion, or an overtaxed FlashCom Server.

Up

The bit rate of data sent from the client movie to the FlashCom Server. Use this to monitor bandwidth consumed by shared object connections and when publishing audio and video over a NetStream instance.

Down

The bit rate of data received by the client from the FlashCom Server. Synchronization operations with shared object data and subscribed streams contribute to the overall value.

The Up and Down values are automatically displayed in units of bit/s (bits per second), kbit/s (kilobits per second), or mbit/s (megabits per second) based on the connection speed.

2.2.4.1 Client-side component parameters

The ConnectionLight component has two settings that can be configured at an instance level in the Properties panel or Component Parameters panel:

Measurement Interval

This parameter, corresponding to the interval property, specifies the time, in seconds, that the instance waits to poll the FlashCom Server for updated connection statistics. The default value is 2 seconds. If you set a higher value, such as 5 or 10 seconds, the component will not consume as much bandwidth for data transfers as a lower interval such as 1 second. If you do not want to add to the bandwidth overhead for your application, use higher values.

Latency Threshold

If a packet's travel time between the Flash movie and FlashCom Server exceeds this value, in seconds, the ConnectionLight instance's icon changes from green to yellow. This parameter corresponds to the tHReshold property; the default value is 0.1 second (100 milliseconds). This value adequately lets you know if audio/video streaming will have noticeable delays to other participants subscribing to the stream or if text messages between users in a chat will be delayed.

Any time a Flash movie connects to a FlashCom application, data packets are sent back and forth to the client in order for the FlashCom Server to know that a client still exists. As such, the FlashCom Server always knows how much latency is present between itself and any connected client.

2.2.4.2 How the component works

In order for the ConnectionLight component to function properly, an instance of it must be connected to the NetConnection object used by the Flash movie using ConnectionLight.connect( ). Using a SimpleConnect instance and specifying the ConnectionLight instance in its list of communication components invokes ConnectionLight.connect( ) automatically. Otherwise, you need to invoke connect( ) on the ConnectionLight instance manually in your client-side ActionScript code.

Unlike other communication components, the ConnectionLight component does not use any remote shared objects or NetStream objects. It uses only call( ) to invoke methods between client-side and server-side ActionScript. The client-side ConnectionLight.connect( ) method issues a call( ) method to the server-side FCConnectionLight.connect( ) method. The server-side connect( ) method uses the measurement interval passed in to calculate a ping interval between the FlashCom application and the Flash movie client. Based on the ping interval, Client.getStats( ) periodically calculates the bandwidth statistic data and sends it to the Flash client via a server-side Client.call( ) method. This continues until the client disconnects or until the client-side ConnectionLight.close( ) method is invoked.

2.2.4.3 Enabling ConnectionLight without SimpleConnect

To use the ConnectionLight component without the help of the SimpleConnect component, invoke ConnectionLight.connect( ) in your client-side ActionScript. The following code example invokes the connect( ) method of the ConnectionLight instance named connLight_mc when the first onStatus( ) message is received over a NetConnection object named app_nc:

var app_nc:NetConnection = new NetConnection(  );
app_nc.onStatus = function (info) {
  if (info.code == "NetConnection.Connect.Success") {
    trace("--successful connection");
  }
  if (!initConnLight) {
    initConnLight = true;
    connLight_mc.connect(this);
  }
};
app_nc.connect("rtmp:/my_app");

For more on this technique, see Section 2.6 at the end of this chapter.

2.2.5. Cursor

The Cursor component provides a visual representation of each connected user's mouse position within the Flash movie. The component displays each user's login name below a cursor indicating the position of the user's mouse on stage, as seen in Figure 2-6. The cursor is also shown in the user's preferred color when used in conjunction with the UserColor component, discussed later in this chapter.

Figure 2-6. The Cursor component displays cursor positions for each user

2.2.5.1 How the component works

When a Cursor instance initializes, it creates two RSOs, cursors and mov, to add the client's cursor to the FlashCom application and to track its movements. When a new client loads the Flash movie and connects to the same FlashCom application, the cursors shared object is updated with the username and color of the earlier Flash client(s). FlashCom broadcasts this update to all subscribers of the cursors shared object, enabling each client to add a new cursor for every participant. Likewise, if a participant moves his mouse cursor, the mov shared object is updated and each subscriber receives the new coordinates of that participant's mouse cursor.

2.2.6. PeopleList

The PeopleList component displays the name of each user connected to a given FlashCom application, as shown in Figure 2-7. When a new user joins the application, her name is added to the PeopleList instance. When a user leaves, his name is removed from the list. If this component is used in conjunction with the SimpleConnect component, the displayed name of the user is the same as the text she entered into the text field of the SimpleConnect component when logging in.

If you want to enable actions for specific users, you can add a change handler for the ListBox instance, named people_lb, within the PeopleList component. For an example of this functionality, see Chapter 13.

Figure 2-7. The PeopleList component lists participants

2.2.6.1 Nested Flash UI components

The PeopleList component uses two Flash UI components: ListBox and ScrollBar. ScrollBar is used within the ListBox component, just as the regular Flash MX UI ScrollBar component is nested within the ListBox component (or the UIScrollBar component within the List component in Flash MX 2004). You can alter the look of these components by changing the appropriate skin symbols in the Component Skins folder within the Flash document's Library panel.

2.2.6.2 Component process overview

The PeopleList component adheres to a similar server-side initiation process as the Chat component. Like the Chat component, the PeopleList component uses the server-side Component.getClientGlobalStorage( ) method to retrieve the name of each connected user. When a client-side PeopleList instance is loaded into a Flash movie, a users RSO is created. The users RSO stores the user ID value, created by the Server-Side ActionScript in scriptlib/components/people.asc, along with the corresponding username. When an update occurs to this shared object, the people_lb instance within the PeopleList component removes the existing set of displayed usernames and adds the new list of usernames. By default, the label and data value of each item in the people_lb instance is the name (as a string value) of a given user.

To store the user ID value of each connected user as the data value of each item in the people_lb instance, you can modify line 46 of the client-side ActionScript code found on the actions layers of the PeopleList component to read:

this.owner.people_lb.addItem(this.data[i], i);

The new code applies the user ID string, i, as the data value to the new ListBox item.

What Is Lurker Mode? If you look through the PeopleList component's client-side and server-side ActionScript code, you'll notice references to " fc_lurker" (note the leading space). The PeopleList component supports a lurker mode, allowing a user to hide his presence from the PeopleList component if a username is not returned in the result object from Component.getClientGlobalStorage( ). In that case, the PeopleList component assigns the value " fc_lurker" to that user's slot in the users RSO. When the client-side onSync( ) method of the users RSO processes updates, a user's name will not be added to the people_lb instance if its value is " fc_lurker".

2.2.7. PresentationSWF

The PresentationSWF component allows you to create a live slideshow environment for multiple users to watch. The component synchronizes the playback of a secondary Flash movie (a .swf file) between a speaker's version and that of the viewers' version, as indicated in Figure 2-8. The Flash movie containing the slideshow will be loaded into the speaker's and viewers' primary Flash movie by the PresentationSWF component.

Figure 2-8. The PresentationSWF component in its two modes: (a) speaker and (b) viewer; both modes load the same (c) content movie

2.2.7.1 Nested Flash UI components

The PresentationSWF component uses the PushButton Flash UI component. The PushButton component is used as the Sync button within the user interface of the PresentationSWF component. You can alter the look of the PushButton component by changing the appropriate skin symbol in the Component Skins folder within the Flash document's Library panel.

2.2.7.2 Client-side component parameters

An instance of the PresentationSWF component has two settings in the Properties panel or Component Parameters panel:

PresentationSWF

The filename of the content Flash movie to be loaded by the PresentationSWF component. This parameter, corresponding to the swfFile property, should be identical in the speaker and viewer versions of the component. You can use a relative or absolute path to the location of the content movie. The default value is simple_preso.swf (a sample movie included with FlashCom).

Viewer Buttons Enabled

This value, corresponding to the viewerButtons property, determines whether viewers can navigate the already-viewed frames of the slideshow with Forward, Back, and Sync buttons. The default value is true, which displays these buttons to the viewer. Viewers can jump to the speaker's current frame using the Sync button, but they cannot move past it. If false, viewers cannot independently navigate frames of the slideshow, and they always see the same slide as the speaker.

2.2.7.3 Component process overview

The typical usage of this component requires the following assets:

Content Movie

The movie containing the slideshow. Its main timeline must have one slide per frame and a stop( ) action on the first frame. For example, a presentation with 10 slides should have 10 frames in its timeline.

Speaker Movie

The person controlling the slideshow must have _global.speakerMode set to true in her version of the primary Flash movie holding the PresentationSWF component. There can be only one controller (or speaker) per application using the PresentationSWF component.

Viewer Movie

Everyone else who is watching the slideshow needs to use a Flash movie with _global.speakerMode set to false.

You don't need two separate Flash movies for the speaker and viewer versions. You can create one Flash movie with a login interface that allows a specific user to have control over the presentation, while other users are set in viewer mode.

Regardless of whether you use the SimpleConnect component or create your own custom NetConnection object to connect to a FlashCom application, you need to set a global variable named speakerMode to TRue or false within the Flash movie(s) containing the PresentationSWF component. In the speaker version, the following code should be invoked before or at the same time the PresentationSWF instance is loaded onto the Stage:

_global.speakerMode = true;

For the viewer version, the variable needs to be set to false:

_global.speakerMode = false;

The PresentationSWF instance looks for this value to determine which controls are displayed within the component's user interface.

When the PresentationSWF component initializes, it creates an RSO named presentation. When the speaker moves forward or backward in the slideshow, a data slot named frameNum is updated within the presentation RSO. Then, the onSync( ) method of the client-side shared object instance named so instructs any connected Flash movies to respond accordingly.

2.2.8. PresentationText

The PresentationText component is very similar to the PresentationSWF component discussed in the previous section. With the PresentationText component, you can create a FlashCom application wherein a set of text slides is controlled by a speaker and is synchronized with all other connected viewers. Unlike the PresentationSWF component, however, the PresentationText component does not require a secondary Flash movie to provide the context of the slideshow, nor does it provide a Viewer Buttons Enabled parameter. The Forward and Back buttons are visible only if the user is a presenter, and not to non-presenter participants. The PresentationText component is actually a text slide creator and editor. Like the PresentationSWF component, the speaker version can create and edit the text, while the viewer version can only watch and navigate already-viewed slides within the presentation. The speaker version of the component also provides a list of slide titles within a navigation listbox, as seen in Figure 2-9.

Figure 2-9. The PresentationText component in its two modes: (a) speaker and (b) viewer

2.2.8.1 Nested Flash UI Components

The PresentationText component uses three Flash MX UI components: ListBox, PushButton, and ScrollBar. You can alter the look of the PushButton component by changing the appropriate skin symbol in the Component Skins folder within the Flash document's Library panel. If you want to change the look of the forward and back arrows, you can alter the graphics within the movie clip symbols found in the Communication Components Core Assets - Developer Only PresentationText Assets fc_presentationtext_arrow_elements folder.

2.2.8.2 Client-side component parameters

An instance of the PresentationText component has only one setting in the Properties panel or Component Parameters panel.

Speaker Mode

Whereas the PresentationSWF component uses a global variable named speakerMode, the PresentationText component provides the speaker/viewer toggle value at the instance level. For the speaker version of the PresentationText component, set the parameter to true. For the viewer version, set the parameter to false. This parameter corresponds to the speakerMode property of the PresentationText component, not the global variable of the same name.

2.2.8.3 How the component works

The PresentationText component uses the same overall structure as the PresentationSWF component, in that both of them use an RSO to synchronize slide information among connected users. However, the presentation RSO created by the PresentationText component is persistentthe data used for the slides, once created by a user in speaker mode, can exist in perpetuity. This feature allows the speaker to create the outline and text slides of a presentation before the live presentation. For example, a professor could create the headings and text for each slide days in advance; each text slide's information would be stored within the persistent presentation RSO. When the professor is ready to conduct his online course, the speaker-enabled PresentationText component automatically loads the existing slide information and displays it to the viewers.

2.2.9. RoomList

The RoomList component is perhaps the most advanced communication component. Of all the communication components, it requires the most manual codingyou can't simply drag and drop this component onto the Stage, even with the use of SimpleConnect, and be on your way. The RoomList component enables you to create a gateway to other application instances running on your FlashCom Server. Remember, when you create a FlashCom application, a Flash movie can connect to the default instance or a specific named instance of the application. For a chat application, you can equate an application instance with a room within the chat application. The RoomList component enables a Flash movie to show each of these instances. The movie containing the RoomList component, however, must connect to an application entirely separate from the chat application. As shown in Figure 2-10, the user interface of the RoomList component displays a list of running FlashCom applications and allows a Flash client to join, create, or delete instances of those applications.

Figure 2-10. The RoomList component provides a lobby

Unlike other communication components, the RoomList component is used with an entirely separate FlashCom application instance than the one to which the clients will ultimately connect.

The following steps outline a standard user experience with an application using the RoomList component:

See the Developing Communication Applications documentation that accompanies Flash Communication Server MX 1.5 (available in both LiveDocs and PDF format from http://www.macromedia.com/support/documentation/en/flashcom/index.html) for more information about the specific server-side event handlers that are necessary for two FlashCom applications to use the RoomList component.

2.2.9.1 Nested Flash UI components

The RoomList component uses three Flash MX UI components: ListBox, PushButton, and ScrollBar. You can alter the look of these component by changing the appropriate skin symbol in the Component Skins folder within the Flash document's Library panel.

2.2.9.2 Client-side component parameters

An instance of the RoomList component has one setting in the Properties panel or Component Parameters panel:

Room Application Path

Using the previous example as a guide, this parameter specifies the URL of the HTML document containing the second Flash movie (SWF file #2), which connects to FlashCom application B. This HTML document receives two parameters from the Flash movie hosting the RoomList component: the user's name and the application instance path used to connect to application A. The HTML document must use either client-side scripting, such as JavaScript or VBScript, or server-side scripting, such as ColdFusion, to process the passed parameters in the URL string and append them to the <OBJECT> and <EMBED> tags for the second Flash movie connecting to application B.

2.2.9.3 Component process overview

As mentioned earlier, the RoomList component is designed to work in a scenario of two FlashCom applications, with separate HTML and SWF files for each application. A more detailed explanation of utilizing the RoomList component follows.

This is intended to be a technical overview of the requirements and steps necessary to use the RoomList component. See Developing Communication Applications for an introductory exercise to using the RoomList component:

2.2.10. SetBandwidth

The SetBandwidth component allows a user to control how much bandwidth can be used by Camera and Microphone objects utilized by other communication components, such as the AVPresence and AudioConference components. The SetBandwidth component limits the byte throughput of a client Flash movie to a FlashCom application. The component's UI consists of a combo box with labelsModem, DSL, LAN, and Customas shown in Figure 2-11, indicating four connection types. These labels are associated with preset bandwidth caps (typical connection speeds), which can be set in the Properties panel or in client-side ActionScript.

Figure 2-11. The SetBandwidth component menu

Selecting Custom opens a separate window, shown in Figure 2-12, in which the user can customize the Up and Down bandwidth limits.

Figure 2-12. The Custom options for the SetBandwidth component

Whenever a user chooses an item in the SetBandwidth component, the quality and attributes of Camera and Microphone objects managed by other communication components will change. As more bandwidth is allocated to the movie, the quality of the audio/video output improves.

2.2.10.1 Nested Flash UI components

The SetBandwidth component uses three Flash MX UI components: ComboBox, PushButton, and ScrollBar. You can alter the look of these components by changing the appropriate skin symbol in the Component Skins folder within the Flash document's Library panel.

2.2.10.2 Client-side component parameters

An instance of the SetBandwidth component has six settings in the Properties panel or Component Parameters panel, as listed in Table 2-2.

These parameters establish the preferred bandwidth limit for the incoming and outgoing connection when the user chooses the specified connection type (Modem, DSL, or LAN) in the SetBandwidth component. The connection type also affects the capture attributes of the Camera object (as used by the AVPresence component) and the sampling rate of the Microphone object (as used by the AVPresence or AudioConference component).

Note that:

• The practical throughput for a typical 56 Kbps dial-up modem is only 33 Kbps.

• The DSL options reflect the typical upper limit of household ADSL (asymmetric DSL) connections. The default DSL Down value is greater than DSL Up; therefore, the quality of incoming streams to the Flash movie client can be more than twice the quality of the user's outgoing stream.

• The default value for the LAN option is 10,000 Kbps, which reflects a typical 10 Mbps network.

• You can change the values to be more restrictive or lax. For example, if you'd prefer the DSL rates to be higher and identical, you could use a value of 512 Kbps for DSL Up and DSL Down.

Table 2-2. SetBandwidth defaults for each connection parameter

Parameter name	Default	Camera settings	Microphone sampling rate	Property
Modem Up	33 Kbps	120 x 90 capture area, 6 fps, 60 quality, keyframe interval of 12	5 kHz	modemUp
Modem Down	33 Kbps	Same as Modem Up	5 kHz	modemDown
DSL Up	128 Kbps	160 x 120 capture area, 12 fps, 80 quality, keyframe interval of 7	11 kHz	dslUp
DSL Down	384 Kbps	Same as DSL Up	11 kHz	dslDown
LAN Up	10,000 Kbps	320 x 240 capture area, 15 fps, 90 quality, keyframe interval of 5	22 kHz	lanUp
LAN Down	10,000 Kbps	Same as LAN Up	22 kHz	lanDown

Keep in mind that the limits established by the SetBandwidth component are secondary to the limits of the practical speed available by a user's Internet (or network) connection. For example, if a user chooses the LAN option but is transmitting over a DSL connection, the outgoing stream will transmit only at the quality limit dictated by the actual connection. The degradation of the quality may not affect the user experience markedly. However, if a user chooses the LAN option despite the fact that she's using a dial-up modem connection, the bandwidth won't support the increased video capture area and frame rate. In that case, FlashCom will drop video frames, causing the image to stutter noticeably. The audio stream will use 22 kHz, and that's just too much data to push over a dial-up connection. Therefore, the audio will stutter as well, resulting in a fairly incomprehensible stream of audio and video to other participants.

2.2.10.3 Component process overview

The SetBandwidth component performs two overall functions within a Flash movie. It creates a Notifier instance within a gFlashCom object that broadcasts changes to other components that are subscribed. The gFlashCom object is simply an object created in the _global namespace for the explicit purpose of sharing parameters, such as bandwidth preferences, between client-side communication components. For example, when you add an AVPresence component or AudioConference room component, each instance is added as a listener to the Notifier instance. At runtime, when a user chooses an option in the SetBandwidth component, any subscribers will receive the new updates, instructing them to change capture attributes of the Camera and/or Microphone object.

The SetBandwidth component also sends these changes to the FlashCom application. When the server-side FCSetBandwidth component receives updates, it invokes Client.setBandwidthLimit( ) to restrict the bandwidth for streams managed by the server. Note that this method controls both the bandwidth to the client from the server and the bandwidth from the client to the server. The server changes override any settings established by client-side ActionScript code.

2.2.11. SimpleConnect

The SimpleConnect component establishes the primary connection to a FlashCom application from a Flash movie client. As you have undoubtedly gathered, other communication components often use the connection established by the SimpleConnect component to communicate with a FlashCom application. As its name implies, this component is very simple to use from both authoring and runtime viewpoints. At runtime, this component displays a username field and a Login button, as shown in Figure 2-13.