Class: SC.State


Extends SC.Object.

Represents a state within a statechart.

The statechart actively manages all states belonging to it. When a state is created, it immediately registers itself with it parent states.

You do not create an instance of a state itself. The statechart manager will go through its state heirarchy and create the states itself.

For more information on using statecharts, see SC.StatechartManager.

Defined in: state.js

Field Summary

Class Methods

Instance Methods

Field Detail

currentSubstates
An array of this state's current substates. Managed by the statechart
enteredSubstates Array

An array of this state's substates that are currently entered. Managed by the statechart.

historyState State
This state's history state. Can be null. Managed by the statechart.
initialSubstate

Used to indicate the initial substate of this state to enter into.

You assign the value with the name of the state. Upon creation of the state, the statechart will automatically change the property to be a corresponding state object

The substate is only to be this state's immediate substates. If no initial substate is assigned then this states initial substate will be an instance of an empty state (SC.EmptyState).

Note that a statechart's root state must always have an explicity initial substate value assigned else an error will be thrown.

name String
The name of the state
parentState State
This state's parent state. Managed by the statechart
representRoute

Can optionally assign what route this state is to represent.

If assigned then this state will be notified to handle the route when triggered any time the app's location changes and matches this state's assigned route. The handler invoked is this state's #routeTriggered method.

The value assigned to this property is dependent on the underlying routing mechanism used by the application. The default routing mechanism is to use SC.routes.

See:
#routeTriggered
#location
SC.StatechartDelegate
statechart Statechart

The statechart that this state belongs to. Assigned by the owning statechart.

stateIsInitialized
Indicates if this state has been initialized by the statechart
substates Array
The immediate substates of this state. Managed by the statechart.
substatesAreConcurrent Boolean

Used to indicates if this state's immediate substates are to be concurrent (orthogonal) to each other.

Class Method Detail

plugin(value, args)

Use this when you want to plug-in a state into a statechart. This is beneficial in cases where you split your statechart's states up into multiple files and don't want to fuss with the sc_require construct.

Example:

MyApp.statechart = SC.Statechart.create({
  rootState: SC.State.design({
    initialSubstate: 'a',
    a: SC.State.plugin('path.to.a.state.class'),
    b: SC.State.plugin('path.to.another.state.class')
  })
});

You can also supply hashes the plugin feature in order to enhance a state or implement required functionality:

SomeMixin = { ... };

stateA: SC.State.plugin('path.to.state', SomeMixin, { ... })
Parameters:
value
{String} property path to a state class
args
{Hash,...} Optional. Hash objects to be added to the created state

Instance Method Detail

addSubstate(name, state, attr)

Used to dynamically add a substate to this state. Once added successfully you are then able to go to it from any other state within the owning statechart.

A couple of notes when adding a substate:

  • If this state does not have any substates, then in addition to the substate being added, an empty state will also be added and set as the initial substate. To make the added substate the initial substate, set this object's initialSubstate property.

  • If this state is a current state, the added substate will not be entered.

  • If this state is entered and its substates are concurrent, the added substate will not be entered.

If this state is either entered or current and you'd like the added substate to take affect, you will need to explicitly reenter this state by calling its reenter method.

Be aware that the name of the state you are adding must not conflict with the name of a property on this state or else you will get an error. In addition, this state must be initialized to add substates.

Parameters:
name String
a unique name for the given substate.
state SC.State
a class that derives from `SC.State`
attr Object Optional
literal to be applied to the substate
Returns:
SC.State
an instance of the given state class
createStateRouteHandlerContext(attr)
Constructs a new instance of a state routing context object.
Parameters:
attr Hash
attributes to apply to the constructed object
Returns:
SC.StateRouteContext
See:
#handleRoute
createSubstate(state, attr)
creates a substate for this state
Parameters:
state
attr
destroy()
enterState(context)

Called whenever this state is to be entered during a state transition process. This is useful when you want the state to perform some initial set up procedures.

If when entering the state you want to perform some kind of asynchronous action, such as an animation or fetching remote data, then you need to return an asynchronous action, which is done like so:

enterState: function() {
  return this.performAsync('foo');
}

After returning an action to be performed asynchronously, the statechart will suspend the active state transition process. In order to resume the process, you must call this state's resumeGotoState method or the statechart's resumeGotoState. If no asynchronous action is to be perform, then nothing needs to be returned.

When the enterState method is called, an optional context value may be supplied if one was provided to the gotoState method.

In the case that the context being supplied is a state context object ({@link SC.StateRouteHandlerContext}), an optional enterStateByRoute method can be invoked on this state if the state has implemented the method. If enterStateByRoute is not part of this state then the enterState method will be invoked by default. The enterStateByRoute is simply a convenience method that helps removes checks to determine if the context provide is a state route context object.

Parameters:
context Hash Optional
value if one was supplied to gotoState when invoked
See:
#representRoute
exitState(context)

Called whenever this state is to be exited during a state transition process. This is useful when you want the state to peform some clean up procedures.

If when exiting the state you want to perform some kind of asynchronous action, such as an animation or fetching remote data, then you need to return an asynchronous action, which is done like so:

exitState: function() {
  return this.performAsync('foo');
}

After returning an action to be performed asynchronously, the statechart will suspend the active state transition process. In order to resume the process, you must call this state's resumeGotoState method or the statechart's resumeGotoState. If no asynchronous action is to be perform, then nothing needs to be returned.

When the exitState method is called, an optional context value may be supplied if one was provided to the gotoState method.

Parameters:
context
{Hash} Optional value if one was supplied to gotoState when invoked
findFirstRelativeCurrentState(anchor)

Will attempt to find a current state in the statechart that is relative to this state.

Ordered set of rules to find a relative current state:

  1. If this state is a current state then it will be returned

  2. If this state has no current states and this state has a parent state then return parent state's first relative current state, otherwise return null

  3. If this state has more than one current state then use the given anchor state to get a corresponding substate that can be used to find a current state relative to the substate, if a substate was found.

  4. If (3) did not find a relative current state then default to returning this state's first current substate.

Parameters:
anchor
{State|String} Optional. a substate of this state used to help direct finding a current state
Returns:
SC.State
a current state
fullPath()

Returns the path for this state relative to the statechart's root state.

The path is a dot-notation string representing the path from this state to the statechart's root state, but without including the root state in the path. For instance, if the name of this state if "foo" and the parent state's name is "bar" where bar's parent state is the root state, then the full path is "bar.foo"

getState(value)

Will attempt to get a state relative to this state.

A state is returned based on the following:

  1. First check this state's substates for a match; and
  2. If no matching substate then attempt to get the state from this state's parent state.

Therefore states are recursively traversed up to the root state to identify a match, and if found is ultimately returned, otherwise null is returned. In the case that the value supplied is ambiguous an error message is returned.

The value provided can either be a state object or a state path expression. For path expression syntax, refer to the {@link SC.StatePathMatcher} class.

Parameters:
value
getSubstate(value, callback, target)

Used to get a substate of this state that matches a given value.

If the value is a state object, then the value will be returned if it is indeed a substate of this state, otherwise null is returned.

If the given value is a string, then the string is assumed to be a path expression to a substate. The value is then parsed to find the closest match. For path expression syntax, refer to the {@link SC.StatePathMatcher} class.

If there is no match then null is returned. If there is more than one match then null is return and an error is generated indicating ambiguity of the given value.

An optional callback can be provided to handle the scenario when either no substate is found or there is more than one match. The callback is then given the opportunity to further handle the outcome and return a result which the getSubstate method will then return. The callback should have the following signature:

function(state, value, paths)

  • state: The state getState was invoked on
  • value: The value supplied to getState
  • paths: An array of substate paths that matched the given value

If there were no matches then paths is not provided to the callback.

You can also optionally provide a target that the callback is invoked on. If no target is provided then this state is used as the target.

Parameters:
value
{State|String} used to identify a substate of this state
callback Optional
{Function} the callback
target Optional
{Object} the target
gotoHistoryState(value, recusive, context)

Used to go to a given state's history state in the statechart either directly from this state if it is a current state or from one of this state's current substates.

If the value given is a string then it is considered a state path expression. The path is then used to find a state relative to this state based on rules of the #getState method.

Method can be called in the following ways:

// With one argument
gotoHistoryState(<value>)

// With two arguments
gotoHistoryState(<value>, <boolean | hash>)

// With three arguments
gotoHistoryState(<value>, <boolean>, <hash>)

Where is either a string or a SC.State object and is a regular JS hash object.

Parameters:
value
{SC.State|String} the state whose history state to go to
recusive Optional
{Boolean} indicates whether to follow history states recusively starting from the given state
context Optional
{Hash|Object} context object that will be supplied to all states that are exited entered during the state transition process. Context can not be an instance of SC.State.
gotoState(value, context)

Used to go to a state in the statechart either directly from this state if it is a current state, or from the first relative current state from this state.

If the value given is a string then it is considered a state path expression. The path is then used to find a state relative to this state based on rules of the #getState method.

Parameters:
value
{SC.State|String} the state to go to
context Optional
{Hash|Object} context object that will be supplied to all states that are exited and entered during the state transition process. Context can not be an instance of SC.State.
handleTriggeredRoute(context)

Invoked by this state's #routeTriggered method if the state is actually allowed to handle the triggered route.

By default the method invokes a state transition to this state.

Parameters:
context
hasCurrentSubstates()
Indicates if this state has any current substates
hasEnteredSubstates()
Indicates if this state has any currently entered substates
hasSubstates()
Indicate if this state has any substates
init()
initState()
Used to initialize this state. To only be called by the owning statechart.
isConcurrentState()
Indicates if this state is a concurrent state
isCurrentState()
Indicates if this state is a current state of the statechart.
isEnteredState()

Indicates if this state is a currently entered state.

A state is currently entered if during a state transition process the state's enterState method was invoked, but only after its exitState method was called, if at all.

isRootState()
Indicates if this state is the root state of the statechart.
location(key, value)

A volatile property used to get and set the app's current location.

This computed property defers to the the statechart's delegate to actually update and acquire the app's location.

Note: Binding for this particular case is discouraged since in most cases we need the location value immediately. If we were to use bindings then the location value wouldn't be updated until at least the end of one run loop. It is also advised that the delegate not have its statechartUpdateLocationForState and statechartAcquireLocationForState methods implemented where bindings are used since they will inadvertenly stall the location value from propogating immediately.

Parameters:
key
value
See:
SC.StatechartDelegate#statechartUpdateLocationForState
SC.StatechartDelegate#statechartAcquireLocationForState
owner()

Indicates who the owner is of this state. If not set on the statechart then the owner is the statechart, otherwise it is the assigned object. Managed by the statechart.

See:
SC.StatechartManager#owner
pathRelativeTo(state)

Will generate path for a given state that is relative to this state. It is required that the given state is a substate of this state.

If the heirarchy of the given state to this state is the following: A > B > C, where A is this state and C is the given state, then the relative path generated will be "B.C"

Parameters:
state
performAsync(func, arg1, arg2)

Call when an asynchronous action need to be performed when either entering or exiting a state.

Parameters:
func
arg1
arg2
See:
enterState
exitState
reenter()

Used to re-enter this state. Call this only when the state a current state of the statechart.

respondsToEvent(event)
Parameters:
event
{String} the value to check
Returns:
Boolean
resumeGotoState()
Resumes an active goto state transition process that has been suspended.
routeTriggered(params)

Main handler that gets triggered whenever the app's location matches this state's assigned route.

When invoked the handler will first refer to the statechart delegate to determine if it should actually handle the route via the delegate's {@see SC.StatechartDelegate#statechartShouldStateHandleTriggeredRoute} method. If the delegate allows the handling of the route then the state will continue on with handling the triggered route by calling the state's #handleTriggeredRoute method, otherwise the state will cancel the handling and inform the delegate through the delegate's {@see SC.StatechartDelegate#statechartStateCancelledHandlingRoute} method.

The handler will create a state route context ({@link SC.StateRouteContext}) object that packages information about what is being currently handled. This context object gets passed along to the delegate's invoked methods as well as the state transition process.

Note that this method is not intended to be directly called or overridden.

Parameters:
params
See:
#representRoute
SC.StatechartDelegate#statechartShouldStateHandleRoute
SC.StatechartDelegate#statechartStateCancelledHandlingRoute
#createStateRouteHandlerContext
#handleTriggeredRoute
statechartDelegate()

Returns the statechart's assigned delegate. A statechart delegate is one that adheres to the {@link SC.StatechartDelegate} mixin.

See:
SC.StatechartDelegate
stateDidBecomeEntered(context)

Notification called just after enterState is invoked.

Note: This is intended to be used by the owning statechart but it can be overridden if you need to do something special.

Parameters:
context
{Hash} Optional value if one was supplied to gotoState when invoked
See:
#enterState
stateDidBecomeExited(context)

Notification called just after exitState is invoked.

Note: This is intended to be used by the owning statechart but it can be overridden if you need to do something special.

Parameters:
context
{Hash} Optional value if one was supplied to gotoState when invoked
See:
#exitState
stateIsCurrentSubstate(state)

Used to check if a given state is a current substate of this state. Mainly used in cases when this state is a concurrent state.

Parameters:
state
{State|String} either a state object or the name of a state
Returns:
Boolean
true is the given state is a current substate, otherwise false is returned
stateIsEnteredSubstate(state)
Used to check if a given state is a substate of this state that is currently entered.
Parameters:
state
{State|String} either a state object of the name of a state
Returns:
Boolean
true if the given state is a entered substate, otherwise false is returned
stateLogError(msg)
Used to log a state error message
Parameters:
msg
stateLogTrace(msg, style)
Used to log a state trace message
Parameters:
msg
style
stateLogWarning(msg)
Used to log a state warning message
Parameters:
msg
stateWillBecomeEntered(context)

Notification called just before enterState is invoked.

Note: This is intended to be used by the owning statechart but it can be overridden if you need to do something special.

Parameters:
context Hash Optional
value if one was supplied to gotoState when invoked
See:
#enterState
stateWillBecomeExited(context)

Notification called just before exitState is invoked.

Note: This is intended to be used by the owning statechart but it can be overridden if you need to do something special.

Parameters:
context
{Hash} Optional value if one was supplied to gotoState when invoked
See:
#exitState
toString()
trace()

Indicates if this state should trace actions. Useful for debugging purposes. Managed by the statechart.

See:
SC.StatechartManager#trace
tryToHandleEvent(event, arg1, arg2)

Called by the statechart to allow a state to try and handle the given event. If the event is handled by the state then YES is returned, otherwise NO.

There is a particular order in how an event is handled by a state:

  1. Basic function whose name matches the event
  2. Registered event handler that is associated with an event represented as a string
  3. Registered event handler that is associated with events matching a regular expression
  4. The unknownEvent function

Use of event handlers that are associated with events matching a regular expression may incur a performance hit, so they should be used sparingly.

The unknownEvent function is only invoked if the state has it, otherwise it is skipped. Note that you should be careful when using unknownEvent since it can be either abused or cause unexpected behavior.

Example of a state using all four event handling techniques:

SC.State.extend({

  // Basic function handling event 'foo'
  foo: function(arg1, arg2) { ... },

  // event handler that handles 'frozen' and 'canuck'
  eventHandlerA: function(event, arg1, arg2) {
    ...
  }.handleEvent('frozen', 'canuck'),

  // event handler that handles events matching the regular expression /num\d/
  //   ex. num1, num2
  eventHandlerB: function(event, arg1, arg2) {
    ...
  }.handleEvent(/num\d/),

  // Handle any event that was not handled by some other
  // method on the state
  unknownEvent: function(event, arg1, arg2) {

  }

});
Parameters:
event
arg1
arg2
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)