Class: SC.StatechartManager

The startchart manager mixin allows an object to be a statechart. By becoming a statechart, the object can then be manage a set of its own states.

This implementation of the statechart manager closely follows the concepts stated in D. Harel's original paper "Statecharts: A Visual Formalism For Complex Systems" (www.wisdom.weizmann.ac.il/~harel/papers/Statecharts.pdf).

The statechart allows for complex state heircharies by nesting states within states, and allows for state orthogonality based on the use of concurrent states.

At minimum, a statechart must have one state: The root state. All other states in the statechart are a decendents (substates) of the root state.

The following example shows how states are nested within a statechart:

MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
  rootState: SC.State.design({
    initialSubstate: 'stateA',

    stateA: SC.State.design({
      // ... can continue to nest further states
    }),

    stateB: SC.State.design({
      // ... can continue to nest further states
    })
  })
});

Note how in the example above, the root state as an explicit initial substate to enter into. If no initial substate is provided, then the statechart will default to the the state's first substate.

You can also defined states without explicitly defining the root state. To do so, simply create properties on your object that represents states. Upon initialization, a root state will be constructed automatically by the mixin and make the states on the object substates of the root state. As an example:

MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
  initialState: 'stateA',

  stateA: SC.State.design({
    // ... can continue to nest further states
  }),

  stateB: SC.State.design({
    // ... can continue to nest further states
  })
});

If you liked to specify a class that should be used as the root state but using the above method to defined states, you can set the rootStateExample property with a class that extends from SC.State. If the rootStateExample property is not explicitly assigned the then default class used will be SC.State.

To provide your statechart with orthogonality, you use concurrent states. If you use concurrent states, then your statechart will have multiple current states. That is because each concurrent state represents an independent state structure from other concurrent states. The following example shows how to provide your statechart with concurrent states:

MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
  rootState: SC.State.design({
    substatesAreConcurrent: YES,

    stateA: SC.State.design({
      // ... can continue to nest further states
    }),

    stateB: SC.State.design({
      // ... can continue to nest further states
    })
  })
});

Above, to indicate that a state's substates are concurrent, you just have to set the substatesAreConcurrent to YES. Once done, then stateA and stateB will be independent of each other and each will manage their own current substates. The root state will then have more then one current substate.

To define concurrent states directly on the object without explicitly defining a root, you can do the following:

MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
  statesAreConcurrent: YES,

  stateA: SC.State.design({
    // ... can continue to nest further states
  }),

  stateB: SC.State.design({
    // ... can continue to nest further states
  })
});

Remember that a startchart can have a mixture of nested and concurrent states in order for you to create as complex of statecharts that suite your needs. Here is an example of a mixed state structure:

MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
  rootState: SC.State.design({
    initialSubstate: 'stateA',

    stateA: SC.State.design({
      substatesAreConcurrent: YES,

      stateM: SC.State.design({ ... })
      stateN: SC.State.design({ ... })
      stateO: SC.State.design({ ... })
    }),

    stateB: SC.State.design({
      initialSubstate: 'stateX',

      stateX: SC.State.design({ ... })
      stateY: SC.State.design({ ... })
    })
  })
});

Depending on your needs, a statechart can have lots of states, which can become hard to manage all within one file. To modularize your states and make them easier to manage and maintain, you can plug-in states into other states. Let's say we are using the statechart in the last example above, and all the code is within one file. We could update the code and split the logic across two or more files like so:

// state_a.js

MyApp.StateA = SC.State.extend({
  substatesAreConcurrent: YES,

  stateM: SC.State.design({ ... })
  stateN: SC.State.design({ ... })
  stateO: SC.State.design({ ... })
});

// state_b.js

MyApp.StateB = SC.State.extend({
  substatesAreConcurrent: YES,

  stateM: SC.State.design({ ... })
  stateN: SC.State.design({ ... })
  stateO: SC.State.design({ ... })
});

// statechart.js

MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
  rootState: SC.State.design({
    initialSubstate: 'stateA',
    stateA: SC.State.plugin('MyApp.StateA'),
    stateB: SC.State.plugin('MyApp.StateB')
  })
});

Using state plug-in functionality is optional. If you use the plug-in feature you can break up your statechart into as many files as you see fit.

Defined in: statechart.js

Field Summary

Instance Methods

• createRootState(state, attrs)
• currentStateCount()
• currentStates()
• destroyMixin()
• details()
• doesContainState(value)
• enteredStates()
• enterState(state, context)
• exitState(state, context)
• firstCurrentState()
• getState(value)
• gotoHistoryState(state, fromCurrentState, recursive, context)
• gotoState(state, fromCurrentState, useHistory, context)
• gotoStateActive()
• gotoStateSuspended()
• initMixin()
• initStatechart()
• invokeStateMethod(methodName, args, func)
• respondsTo(event)
• resumeGotoState()
• sendEvent(event, arg1, arg2)
• statechartDelegate()
• statechartLogError(msg)
• statechartLogPrefix()
• statechartLogTrace(msg, style)
• statechartLogWarning(msg)
• stateDidTryToHandleEvent(state, event, handler, handled)
• stateIsCurrentState(state)
• stateIsEntered(state)
• stateWillTryToHandleEvent(state, event, handler)
• toStringWithDetails()
• tryToPerform(event, arg1, arg2)

// With one arguments.
gotoHistoryState(<state>)

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

// With three arguments.
gotoHistoryState(<state>, <state>, <boolean | hash>)
gotoHistoryState(<state>, <boolean>, <hash>)

// With four argumetns
gotoHistoryState(<state>, <state>, <boolean>, <hash>)

// With one argument.
gotoState(<state>)

// With two argument.
gotoState(<state>, <state | boolean | hash>)

// With three argument.
gotoState(<state>, <state>, <boolean | hash>)
gotoState(<state>, <boolean>, <hash>)

// With four argument.
gotoState(<state>, <state>, <boolean>, <hash>)

invokeStateMethod('render', context, firstTime);

invokeStateMethod('calculate', value, function (state, result) {
  // .. handle the result returned from calculate that was invoked
  //    on the given state
})