Stage (Votorola Java API)

java.lang.Object
- Stage

All Implemented Interfaces:

HasHandlers, WarningSink, TheatrePage
```
public final class Stage
extends Object
implements HasHandlers, TheatrePage, WarningSink
```
The Crossforum Theatre stage. The purpose of the stage is to support the decoration of web pages (scenes) with specialized views and controls (props) for the purpose of broad-based system guidance. Any web page may be "staged" in this manner. The props are typically deployed in containers known as "tracks" that are layed out along the edges of the browser viewport. See StageV for layout examples. The stage itself provides support to the props in the form of common variables that model the core state of the application. This enables the props to function in a coordinated manner while remaining independent of each other, which in turn frees the user to make a personal choice of props based on need or preference. Although such personal customization is not yet supported by current implementations of the stage, it remains a design requirement for the future.
Persistence of state in a single page

The staged state of each page is persisted to ensure that changes by the user (selections and so forth) are not lost due to page reload during back and forth navigation, refresh, and so forth. (A memory cache such as Firefox's BFCache, or WebKit's page cache will also do this, but is not available for all browsers, nor enabled for all pages.) For this to work correctly, scenes and props must initialize on page load vis-a-vis the stage only via theatre initializers that are registered with the stage.

To clear the persisted state and load a pristine page either (A) close and reopen the window or tab, or otherwise restart the browsing session; or (B) clear the web store (also known as DOM or HTML5 storage) by whatever means the browser provides (e.g. entering sessionStorage.clear() in the Firebug console); or (C) use the following procedure to clear the state for a single page: (1) ensure the URL has a fragment '#' delimiter by appending it if necessary; (2) also append "voStage.clear" to the end of the URL; (3) press return as if to navigate to that fragment; and finally (4) reload the page. For example here's a URL in its original form and with the necessary appendage:
```
   http://somewhere.com/fu#bar
   http://somewhere.com/fu#bar&voStage.clear
```
Persistence of state across pages

The stage provides a mechanism for the selective transfer of state during transit from one page (referrer) to another via hypertext links. This allows user selections and such to persist across pages. This persistence is controlled by the props that depend upon it via the initTo(stage,referrer) methods of their registered initializers.

State changes during ordinary use

Subsequent state changes such as those initiated by the user are generally expected as late as the "finally" phase of each event dispatch. The associated change events are then dispatched in the "deferred" phase where they appear atomic regardless of the number of state variables involved. There is a minor exception to this rule: late registration of an initializer (i) will nevertheless flush pending events immediately, as stipulated by i.initFromComplete and initToComplete.

Events are propagated via the common event bus. Each event is pre-dispatched from the suppressable prompter first. The event is cancelled if it gets suppressed, otherwise it is re-dispatched from the ordinary source.

Defaulting properties and masked changes

A defaulting property is one that has a default mechanism, such as "difference". A defaulting property that changes from null to the default value, or from the default value to null, exhibits no effective change in its value. The value remains at the default and the change is said to be masked. No change event "NAME" is fired in this case, but rather a change event "NAME masked".

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`(package private) static class`	`Stage.StateChunker` Utilities for dealing with a chunk of state that may persist across time and/or pages and sites.

Constructor Summary

Constructors
Constructor and Description

Stage()
Creates the single instance of Stage.

Constructors
Constructor and Description
`Stage()` Creates the single instance of Stage.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`addInitializer(TheatreInitializer i)` Adds a theatre initializer to be run either immediately or later, depending on the current state of initialization.
`void`	`addWarning(String warning)` Adds a plain text warning for the user.
`(package private) void`	`appendJSON(StringBuilder b)` Appends a string that encodes the state of this stage as a sequence of JSON name/value pairs suitable for underwriting an instance of TheatrePageJS, all but for the pageLocation and the surrounding curly braces.
`boolean`	`areDifferencesShadowed()` Answers whether the page is a position draft to be decorated by difference shadows, once the necessary differences are fetched from the server.
`void`	`fireEvent(GwtEvent<?> e)`
`String`	`getActorName()` The username of the actor who is shown, or null if nobody in particular is shown and no default is set.
`String`	`getDefaultActorName()` The username of the default actor, or null if there is none.
`DiffLook`	`getDefaultDifference()` The key of the default difference, or null if there is none.
`String`	`getDefaultPollName()` The default poll name, or null if there is none.
`DiffLook`	`getDifference()` The key of the difference that is shown, or null if none in particular is shown and no default is set.
`Message`	`getMessage()` The message that is shown, or null if none in particular is shown.
`String`	`getPollName()` The name of the poll that is shown, or null if none in particular is shown and no default is set.
`static Stage`	`i()` The single instance of Stage.
`(package private) void`	`init0()` Begins initialization of the stage.
`(package private) void`	`init1(TheatrePageJS _referrer, ReferrerRelayer _referrerRelayer, boolean _isReferencePending)` Continues initialization of the stage.
`(package private) void`	`init2b_async(TheatrePageJS latelyResolvedReferrer)` Continues initialization of the stage in the case of a deferred referrer resolution.
`LightBank`	`lightBank()` The light bank for this stage.
`String`	`pageLocation()` The URL of the page without a fragment.
`SuppressableSource`	`prompter()` The source from which stage events are pre-dispatched.
`static void`	`setActorName(String newActorName)` Sets the username of the actor who is shown, or effectively resets it to the default.
`static void`	`setDefaultActorName(String newDefault)` Sets the username of the default actor, firing a change event if it affects the bound property "actorName".
`static void`	`setDefaultDifference(DiffLook newDefault)` Sets the key of the default difference, firing a change event if it affects the bound property "difference".
`static void`	`setDefaultPollName(String newDefault)` Sets the default poll name, firing a change event if it affects the bound property "pollName".
`void`	`setDifference(DiffLook k)` Sets the key of the difference that is shown, or effectively resets it to the default.
`void`	`setDifferencesShadowed()` Specifies that the page is a position draft to be decorated by difference shadows.
`void`	`setMessage(Message newMessage)` Sets the message that is shown.
`void`	`setPollName(String newPollName)` Sets the name of the poll that is shown, or effectively resets it to the default.
`String`	`toString()`
`List<Track>`	`tracks()` The list of all tracks on stage.
`List<String>`	`warnings()` A list of warnings for the user.
`(package private) void`	`wrapJSON(StringBuilder b)` Wraps a sequence of name/value pairs to form a proper JSON object, after removing any trailing comma (,).

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Stage
```
Stage()
```
    Creates the single instance of Stage.
- Method Detail
  - i
```
public static Stage i()
```
    The single instance of Stage.
  - init0
```
void init0()
```
    Begins initialization of the stage.
  - init1
```
void init1(TheatrePageJS _referrer,
         ReferrerRelayer _referrerRelayer,
         boolean _isReferencePending)
```
    Continues initialization of the stage.
    
    Parameters:
    _isReferencePending - whether the referrer (if any) remains to be resolved asynchronously. When true, _referrer must be null.
  - init2b_async
```
void init2b_async(TheatrePageJS latelyResolvedReferrer)
```
    Continues initialization of the stage in the case of a deferred referrer resolution.
  - addInitializer
```
public void addInitializer(TheatreInitializer i)
```
    Adds a theatre initializer to be run either immediately or later, depending on the current state of initialization. Initializers are automatically removed after they are run.
  - appendJSON
```
void appendJSON(StringBuilder b)
```
    Appends a string that encodes the state of this stage as a sequence of JSON name/value pairs suitable for underwriting an instance of TheatrePageJS, all but for the pageLocation and the surrounding curly braces. The value is effectively bound via the event bus to all named properties "NAME" and "NAME masked" of the stage. An event of either form signals a probable change to the JSON value, subject only to the possibility that multiple changes might cancel each other by the time the events are fired.
    
    See Also:
    wrapJSON(StringBuilder), Defaulting properties and masked changes
  - areDifferencesShadowed
```
public boolean areDifferencesShadowed()
```
    Answers whether the page is a position draft to be decorated by difference shadows, once the necessary differences are fetched from the server. The value may only transit from false to true and is bound via the event bus to property name differencesShadowed. When true, the style class voDifferencesShadowed is set on the page body.
    
    See Also:
    setDifferencesShadowed(), DifferenceShadows, Category:Draft
  - setDifferencesShadowed
```
public void setDifferencesShadowed()
```
    Specifies that the page is a position draft to be decorated by difference shadows.
    
    See Also:
    areDifferencesShadowed()
  - lightBank
```
public LightBank lightBank()
```
    The light bank for this stage.
  - prompter
```
public SuppressableSource prompter()
```
    The source from which stage events are pre-dispatched. Most handlers will name the stage itself as the event source. Only those handlers that suppress events should name the prompter.
    
    See Also:
    GWTX.bus()
  - tracks
```
public List<Track> tracks()
```
    The list of all tracks on stage.
  - wrapJSON
```
void wrapJSON(StringBuilder b)
```
    Wraps a sequence of name/value pairs to form a proper JSON object, after removing any trailing comma (,).
    
    See Also:
    appendJSON(StringBuilder)
  - fireEvent
```
public void fireEvent(GwtEvent<?> e)
```
    Specified by:
    
    fireEvent in interface HasHandlers
  - toString
```
public final String toString()
```
    Overrides:
    
    toString in class Object
  - pageLocation
```
public String pageLocation()
```
    Description copied from interface: TheatrePage
    
    The URL of the page without a fragment.
    
    Specified by:
    
    pageLocation in interface TheatrePage
  - getActorName
```
public String getActorName()
```
    The username of the actor who is shown, or null if nobody in particular is shown and no default is set. The effective value is bound via the event bus to property name "actorName".
    
    Specified by:
    
    getActorName in interface TheatrePage
    
    See Also:
    setActorName(String), IDPair.username()
  - setActorName
```
@GWTInitCallback
public static void setActorName(String newActorName)
```
    Sets the username of the actor who is shown, or effectively resets it to the default. Call this method from the global initialization function voGWTConfig.s_gwt_stage_Stage_initFrom or initTo like this for example:
```
   s_gwt_stage_Stage_setActorName( 'Joe-GmailCom' ); // otherwise null
```
    Parameters:
    newActorName - the name to set, or null to effectively reset it to the default name.
    See Also:
    getActorName()
  - getDefaultActorName
```
public String getDefaultActorName()
```
    Description copied from interface: TheatrePage
    
    The username of the default actor, or null if there is none.
    
    Specified by:
    
    getDefaultActorName in interface TheatrePage
    
    See Also:
    getActorName(), setDefaultActorName(String)
  - setDefaultActorName
```
@GWTInitCallback
public static void setDefaultActorName(String newDefault)
```
    Sets the username of the default actor, firing a change event if it affects the bound property "actorName". Call this method from the global initialization function voGWTConfig.s_gwt_stage_Stage_initFrom or initTo like this for example:
```
   s_gwt_stage_Stage_setDefaultActorName( 'Joe-GmailCom' ); // otherwise null
```
    See Also:
    getDefaultActorName()
  - getDifference
```
public DiffLook getDifference()
```
    The key of the difference that is shown, or null if none in particular is shown and no default is set. The difference may be nominal. The effective value is bound via the event bus to property name "difference".
    
    Specified by:
    
    getDifference in interface TheatrePage
    
    See Also:
    setDifference(DiffLook)
  - setDifference
```
public void setDifference(DiffLook k)
```
    Sets the key of the difference that is shown, or effectively resets it to the default.
    
    Parameters:
    k - the key to set, or null to effectively reset it to the default.
    See Also:
    getDifference()
  - getDefaultDifference
```
public DiffLook getDefaultDifference()
```
    Description copied from interface: TheatrePage
    
    The key of the default difference, or null if there is none.
    
    Specified by:
    
    getDefaultDifference in interface TheatrePage
    
    See Also:
    getDifference(), setDefaultDifference(DiffLook)
  - setDefaultDifference
```
@GWTInitCallback
public static void setDefaultDifference(DiffLook newDefault)
```
    Sets the key of the default difference, firing a change event if it affects the bound property "difference". Call this method from the global initialization function voGWTConfig.s_gwt_stage_Stage_initFrom or initTo like this for example:
```
   s_gwt_stage_Stage_setDefaultDifference( // otherwise null
   {
      key: '5270.5284', selectand: 'b'
   });
```
    See Also:
    getDefaultDifference()
  - getMessage
```
public Message getMessage()
```
    The message that is shown, or null if none in particular is shown. The value is bound via the event bus to property name "message".
    
    Specified by:
    
    getMessage in interface TheatrePage
    
    See Also:
    setMessage(Message)
  - setMessage
```
public void setMessage(Message newMessage)
```
    Sets the message that is shown.
    
    See Also:
    getMessage()
  - getPollName
```
public String getPollName()
```
    The name of the poll that is shown, or null if none in particular is shown and no default is set. The effective value is bound via the event bus to property name "pollName".
    
    Specified by:
    
    getPollName in interface TheatrePage
    
    See Also:
    Category:Poll, setPollName(String)
  - setPollName
```
public void setPollName(String newPollName)
```
    Sets the name of the poll that is shown, or effectively resets it to the default.
    
    Parameters:
    newPollName - the new name to set, or null to effectively reset it to the default name.
    See Also:
    getPollName()
  - getDefaultPollName
```
public String getDefaultPollName()
```
    Description copied from interface: TheatrePage
    
    The default poll name, or null if there is none.
    
    Specified by:
    
    getDefaultPollName in interface TheatrePage
    
    See Also:
    getPollName(), setDefaultPollName(String)
  - setDefaultPollName
```
@GWTInitCallback
public static void setDefaultPollName(String newDefault)
```
    Sets the default poll name, firing a change event if it affects the bound property "pollName". Call this method from the global initialization function voGWTConfig.s_gwt_stage_Stage_initFrom or initTo like this for example:
```
   s_gwt_stage_Stage_setDefaultPollName( 'Sys/p/Sandbox' ); // otherwise null
```
    See Also:
    getDefaultPollName()
  - addWarning
```
public void addWarning(String warning)
```
    Description copied from interface: WarningSink
    
    Adds a plain text warning for the user. Format the warning as though for display in a simple alert window. Do not include trailing newlines.
    
    Specified by:
    
    addWarning in interface WarningSink
    
    See Also:
    warnings()
  - warnings
```
public List<String> warnings()
```
    A list of warnings for the user. Additions to the list are bound via the event bus to property name warnings.
    
    See Also:
    addWarning(String)

Class Stage

Persistence of state in a single page

Persistence of state across pages

State changes during ordinary use

Defaulting properties and masked changes

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Stage

Method Detail

i

init0

init1

init2b_async

addInitializer

appendJSON

areDifferencesShadowed

setDifferencesShadowed

lightBank

prompter

tracks

wrapJSON

fireEvent

toString

pageLocation

getActorName

setActorName

getDefaultActorName

setDefaultActorName

getDifference

setDifference

getDefaultDifference

setDefaultDifference

getMessage

setMessage

getPollName

setPollName

getDefaultPollName

setDefaultPollName

addWarning

warnings