Packagecom.worlize.api.data
Classpublic dynamic class StateHistory
InheritanceStateHistory Inheritance flash.utils.Proxy
Implements flash.events.IEventDispatcher

Product Version : Worlize APIv.1

Synchronizes the app's state across all connected clients.

The StateHistory class provides a list of objects, each of which make up a single entry in a list of past actions that can be used to reconstitute the application's current state.

This class subclasses flash.utils.Proxy so you can access state history entries directly using bracket notation like stateHistory[4] or use it in for or for each loops.

This class facilitates the app's ability to reconstitute the current app state based on a history of sequential events for new users who enter the room.

Imagine, for example, that you're writing an app that allows multiple users to draw on a shared canvas. You want new lines to appear in real time as they are being drawn, and new users who come into the room should see the same drawing as those who have already been interacting with the app for a while.

You could broadcast new line segments using the message broadcasting facilities provided by methods like api.thisObject.sendMessage() but when a new user entered the room, they would see a blank canvas because they would be missing the data about all the existing lines that have already been drawn. Instead, it is better to push each line segment into the app's SharedHistory instance and listen for the itemAdded events that it emits to do the actual drawing.

The StateHistory class guarantees the following:

Because of this, it's the perfect way to synchronize application state that is derived from a history of events.

When a user does something in the application that should be reflected on all connected clients, it's best to just push() information about the action to your app's StateHistory instead of updating the display directly. Then listen for the itemAdded event and handle the display updates there, based on the state history data that was received. In this way, the display updates are tied to the state history and will be consistent across all connected clients.

See also

com.worlize.api.event.StateHistoryEvent
com.worlize.api.data.SyncedDataStore


Public Properties
 PropertyDefined By
  length : uint
[read-only] Get the number of entries in the state history list.
StateHistory
Public Methods
 MethodDefined By
  
StateHistory(sourceItems:Array = null)
Constructor.
StateHistory
  
addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void
Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.
StateHistory
  
clear(initialItem:Object = null):void
Clears the state history.
StateHistory
  
dispatchEvent(event:Event):Boolean
Dispatches an event into the event flow.
StateHistory
  
getItemAt(index:int):*
Get the state history entry at index.
StateHistory
  
hasEventListener(type:String):Boolean
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
StateHistory
  
push(item:Object):void
Adds a new state history entry.
StateHistory
  
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
StateHistory
  
shift():void
Removes the oldest state history.
StateHistory
  
willTrigger(type:String):Boolean
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
StateHistory
Events
 Event Summary Defined By
  Dispatched when the state history is cleared.StateHistory
  Dispatched when a new state history entry is added.StateHistory
  Dispatched when a state history entry is removed.StateHistory
Property Detail
lengthproperty
length:uint  [read-only]

Product Version : Worlize APIv.1

Get the number of entries in the state history list.


Implementation
    public function get length():uint
Constructor Detail
StateHistory()Constructor
public function StateHistory(sourceItems:Array = null)

Product Version : Worlize API.v1

Constructor.

The StateHistory instance is created and managed by the WorlizeAPI class. You do not instantiate this object yourself.

Parameters
sourceItems:Array (default = null)

See also


Example
How to get a reference to the StateHistory instance
         
         var api:WorlizeAPI = WorlizeAPI.getInstance();
         var history:StateHistory = api.stateHistory;
         
         
Method Detail
addEventListener()method
public function addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void

Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event.

Parameters

type:String
 
listener:Function
 
useCapture:Boolean (default = false)
 
priority:int (default = 0)
 
useWeakReference:Boolean (default = false)

See also

clear()method 
public function clear(initialItem:Object = null):void

Product Version : Worlize APIv.1

Clears the state history.

This method does not immediately clear the local copy of the state history, but rather just sends a request to the server to clear the history. The local copy will be cleared when the server broadcasts the update to all connected clients.

Therefore, you cannot count on the list to be emptied immediately after calling this method. You must wit for the corresponding cleared event.

You can optionally specify a value for the initialItem property to atomically add an initial entry to the newly cleared list. This may be useful for consolidating long state histories into a single composite entry to save space and bandwidth for new users entering the room if the history becomes long through extended usage of the app by other users in the room

Parameters

initialItem:Object (default = null) — an AMF3 serializable object representing the first state entry to add immediately after clearing the list.

See also

dispatchEvent()method 
public function dispatchEvent(event:Event):Boolean

Dispatches an event into the event flow. The event target is the EventDispatcher object upon which the dispatchEvent() method is called.

Parameters

event:Event

Returns
Boolean

See also

getItemAt()method 
public function getItemAt(index:int):*

Product Version : Worlize APIv.1

Get the state history entry at index.

Alternatively, you can use bracket notation as you would with a normal Array.

Parameters

index:int — the index of the entry to retrieve

Returns
* — a state entry object

Example
Get the third item in the state history list
         
         var api:WorlizeAPI = WorlizeAPI.getInstance();
         
         var item:= api.stateHistory.getItemAt(2);
         
         // Equivalently:
         var item:= api.stateHistory[2];
         
         
hasEventListener()method 
public function hasEventListener(type:String):Boolean

Checks whether the EventDispatcher object has any listeners registered for a specific type of event.

Parameters

type:String

Returns
Boolean

See also

push()method 
public function push(item:Object):void

Product Version : Worlize APIv.1

Adds a new state history entry.

This method does not immediately add the new entry to the local copy of the list, but simply sends it to the server. The entry will be added to the local copy when the server sends back confirmation that the update has been broadcast to all connected clients.

Therefore, you cannot immediately access the newly pushed item until its corresponding itemAdded event.

Parameters

item:Object — an AMF3 serializable object representing the new state history entry to add

See also

removeEventListener()method 
public function removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void

Removes a listener from the EventDispatcher object. If there is no matching listener registered with the EventDispatcher object, a call to this method has no effect.

Parameters

type:String
 
listener:Function
 
useCapture:Boolean (default = false)

See also

shift()method 
public function shift():void

Product Version : Worlize APIv.1

Removes the oldest state history.

This method does not immediately remove the old entry from the local copy of the list, but simply sends the request to the server. The entry will be removed from the local copy when the server sends back confirmation that the update has been broadcast to all connected clients.

Therefore, you cannot rely upon the local list to be updated until the corresponding itemRemoved event.

See also

willTrigger()method 
public function willTrigger(type:String):Boolean

Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.

Parameters

type:String

Returns
Boolean

See also

Event Detail
cleared Event
Event Object Type: com.worlize.api.event.StateHistoryEvent
StateHistoryEvent.type property = com.worlize.api.event.StateHistoryEvent.CLEARED

Product Version : Worlize API.v1

Dispatched when the state history is cleared.

The StateHistoryEvent.CLEARED constant defines the value of the type property of the event object for a cleared event.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.
entryAdded Event  
Event Object Type: com.worlize.api.event.StateHistoryEvent
StateHistoryEvent.type property = com.worlize.api.event.StateHistoryEvent.ENTRY_ADDED

Product Version : Worlize API.v1

Dispatched when a new state history entry is added.

The StateHistoryEvent.ENTRY_ADDED constant defines the value of the type property of the event object for a entryAdded event.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
entryThe object representing the state data being added.
indexAn integer indicating the zero-based position of the state data being added.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.
entryRemoved Event  
Event Object Type: com.worlize.api.event.StateHistoryEvent
StateHistoryEvent.type property = com.worlize.api.event.StateHistoryEvent.ENTRY_REMOVED

Product Version : Worlize API.v1

Dispatched when a state history entry is removed.

The StateHistoryEvent.ENTRY_REMOVED constant defines the value of the type property of the event object for a entryRemoved event.

The properties of the event object have the following values:

PropertyValue
bubblesfalse
cancelablefalse
currentTargetThe Object that defines the event listener that handles the event. For example, if you use myButton.addEventListener() to register an event listener, myButton is the value of the currentTarget.
entryThe object representing the state data being removed.
indexAn integer indicating the zero-based position of the state data being removed.
targetThe Object that dispatched the event; it is not always the Object listening for the event. Use the currentTarget property to always access the Object listening for the event.