| Package | widgetfactory.communication |
| Class | public class BaseRoom |
| Inheritance | BaseRoom  flash.events.EventDispatcher |
| Implements | IRoom |
| Subclasses | BaseSlideRoom |
Widget rooms are like a club that widgets can join. The club has a room where they can catch up, debate about what to do, and take synchronized action. The club has different roles for different members allowing the widgets that join it to be organized and structured.
A widget room could just be used to get direct references to another widget instance, or the room itself could be part of the operations of the widget, moderating conflicts between widgets and taking direct action.
Every widget room has a list of members (that is, widgets that have registered with the room),
this list is sorted by each member's role and name. You can search the room's list by using methods such as:
getMemberByName(), and getMembersByRole(). A member's role is defined when
it is joining the room via the WidgetRooms class.
Just because they're called 'Widget Rooms' doesn't mean that the room members have to be objects that extend one of the widget classes. Usually, members will be separate classes which are specifically built to communicate with the widget room.
The BaseRoom class is meant for rooms that are global to the Captivate Movie;
rooms that any widget in the movie could join. Quite often this room will be located on the Captivate Main Timeline.
There is also a BaseSlideRoom class which creates a room local to a particular slide in the movie.
For more information see the BaseSlideRoom class.
One of the problems with sharing objects between widget instances is that Captivate loads each widget
into its own Application Domain. The result of this is you can't assign a widget room object to a variable typed to
BaseRoom or BaseSlideRoom. Instead you must assign the room to an untyped variable.
For more information on this, and how to get around the loose typing, see the BaseRoomProxy class.
See also
| Property | Defined By | ||
|---|---|---|---|
| isRoom : Boolean [read-only]
A property that WidgetRooms looks for when it is trying to locate a room object. | BaseRoom | ||
| location : MovieClip [read-only]
The location where the room has been created. | BaseRoom | ||
| name : String [read-only]
The name given to the room when it was created. | BaseRoom | ||
| numMembers : int [read-only]
The number of members that are registered with the room. | BaseRoom | ||
| Property | Defined By | ||
|---|---|---|---|
| allMembers : Array [read-only]
A list of all the members that have joined the room. | BaseRoom | ||
| onNoMembersDeleteRoom : Boolean
Indicates whether this room should delete itself if all its members deregister. | BaseRoom | ||
| Method | Defined By | ||
|---|---|---|---|
BaseRoom(name:String, location:MovieClip)
Creates a new instance of the BaseRoom class. | BaseRoom | ||
deregister(member:Object):void
Removes a member from the member list so that it can no longer be found with getMemberByName or getMembersByRole. | BaseRoom | ||
getMemberByName(memberName:String, role:String):Object
Returns the member object that matches the name and role that are passed in. | BaseRoom | ||
getMemberRole(member:Object):String
Takes the member object and finds what role it belongs it. | BaseRoom | ||
getMembersByRole(role:String):Array
Returns a list of all members that belong to a particular role. | BaseRoom | ||
register(member:Object, memberName:String, role:String):void
Registers a member with the room's member list. | BaseRoom | ||
| Event | Summary | Defined By | ||
|---|---|---|---|---|
| Dispatched when a member leaves the room. | BaseRoom | |||
| Dispatched when a new member joins the room. | BaseRoom | |||
| Dispatched in the case where a member is added to the room which has the same name as another member. | BaseRoom | |||
| Dispatched when the room is about to be deleted. | BaseRoom | |||
| Constant | Defined By | ||
|---|---|---|---|
| COMMON_ROLE : String = commonRole [static]
The string representation the Common Role. | BaseRoom | ||
| allMembers | property |
allMembers:Array [read-only] A list of all the members that have joined the room.
protected function get allMembers():Array| isRoom | property |
isRoom:Boolean [read-only]
A property that WidgetRooms looks for when it is trying to locate a room object.
public function get isRoom():Boolean| location | property |
location:MovieClip [read-only] The location where the room has been created. Normally this would be the Captivate Main Timeline (cpVariables). However, for Slide Rooms this should be the slide the room is attached to.
public function get location():MovieClip| name | property |
name:String [read-only] The name given to the room when it was created.
public function get name():String| numMembers | property |
numMembers:int [read-only] The number of members that are registered with the room.
public function get numMembers():int| onNoMembersDeleteRoom | property |
onNoMembersDeleteRoom:Boolean
Indicates whether this room should delete itself if all its members deregister.
The delete operation is taken care of by the WidgetRooms class.
The default value is false.
protected function get onNoMembersDeleteRoom():Boolean protected function set onNoMembersDeleteRoom(value:Boolean):voidSee also
| BaseRoom | () | Constructor |
public function BaseRoom(name:String, location:MovieClip)
Creates a new instance of the BaseRoom class.
name:String — The name that this widget room has been given.
| |
location:MovieClip — The place where the widget room has been set up. For global rooms this should be the Captivate Main Timeline.
|
| deregister | () | method |
public function deregister(member:Object):void
Removes a member from the member list so that it can no longer be found with getMemberByName or getMembersByRole.
This does not guarantee that the member will lose all references to the room, or that it will no longer be able to make changes.
Parameters
member:Object — The member object that you wish to remove from the member list.
|
See also
| getMemberByName | () | method |
public function getMemberByName(memberName:String, role:String):ObjectReturns the member object that matches the name and role that are passed in.
Parameters
memberName:String — The name of the member
| |
role:String — The role that the member has (Will default to the common role)
|
Object — The member object
|
| getMemberRole | () | method |
public function getMemberRole(member:Object):StringTakes the member object and finds what role it belongs it.
Parameters
member:Object — The member object.
|
String — The role the member belongs to.
|
| getMembersByRole | () | method |
public function getMembersByRole(role:String):ArrayReturns a list of all members that belong to a particular role. By default, it will return a list of all members under the Common Role.
Parameters
role:String — The role that you wish to create the list from.
|
Array — An array of all members that belong to that role.
|
| register | () | method |
public function register(member:Object, memberName:String, role:String):voidRegisters a member with the room's member list. The member is categorized by its name and role. If no role is provided, it is categorized under the default common role.
Parameters
member:Object — The literal member object
| |
memberName:String — The name that identifies the member object
| |
role:String — The role that the member object will be categorized under
|
See also
| memberQuiting | Event |
widgetfactory.events.WidgetRoomEventwidgetfactory.events.WidgetRoomEvent.MEMBER_QUITINGDispatched when a member leaves the room.
See also
| newMember | Event |
widgetfactory.events.WidgetRoomEventwidgetfactory.events.WidgetRoomEvent.MEMBER_JOININGDispatched when a new member joins the room.
See also
| replaceDuplicateMember | Event |
widgetfactory.events.WidgetRoomEventwidgetfactory.events.WidgetRoomEvent.REPLACE_DUPLICATE_MEMBERDispatched in the case where a member is added to the room which has the same name as another member. In this case, the old member will be deregistered, and the new member put in its place.
| roomDeleted | Event |
widgetfactory.events.WidgetRoomEventwidgetfactory.events.WidgetRoomEvent.ROOM_DELETEDDispatched when the room is about to be deleted.
See also
| COMMON_ROLE | Constant |
public static const COMMON_ROLE:String = commonRoleThe string representation the Common Role.
All roles are actually strings that widget rooms can use to sort members by. If the member when joining the room does not specify a specific role, then it will be assigned to the Common Role by default.
WidgetRooms class's join() method.
The join method will attempt to locate the room and add the member to it. If it can't find the room,
then it will create it.
You must pass the following information into the join() method for it to successfully connect
to the room.
BaseRoom class.The join() method will then return the room object which can be stored in a variable.
Say we had a series of widgets that were supposed to be different cooking appliances, and we all wanted them to connect to a widget room as if it was the 'kitchen'. In that case the information would be:
SlideRoom so the location would be the widget's
home slide.WidgetKitchenRoomSo altogether in code it would look like this:
// Create member
var toasterObject:Toaster = new Toaster();
// Join room
var room = WidgetRooms.join("kitchen", widgetSlide, toasterObject, "toaster", WidgetKitchenRoom, "appliance");
The member has now joined the room, and you have a reference to the room object in the room variable.
For more information on rooms, stay tuned to the Widget King blog