Pointer to the State Engine instance. This is set at the time the engine is first activate, or, if the developer does not want to delay at that point, the developer can call prepareNetwork() once.

Boolean flag used to determine if the State has handled the current event. It is reset to false when the State has a chance to handle a given event. Developers will rarely (if ever) use this.

String identifier for the state. Must be unique in the entire state network.

Pointer to this State's State Manager instance.

An optional name for the State to give to the State Manager, used for display purposes only. If no name is set, we use id by default.

An array containing the pulse activities (PulseActivity) for this state.

An Object, keyed by target state id, that contains all the transitions for this State.

The value of transitions is itself an array of transitions, because it's possible to have multiple transitions with the same target state (though they must have different event types).

The constructor for the state class. Pass in a name, an ID (typically numeric), and a pointer to the state network manager. If this state is the topmost in the whole network, the manager is null.

Use this method to add an activity to the state that fires at a specified interval. You can specify a function or method to call. Note: if you need to refer to the timeline from within a function, use the last example to call your function.

Parameters

Add an 'external' transition, i.e., from this State to a target state.

Use this method to transition out of the current state, up any number of parent state levels, then re-enter the path down towards the current state. The difference between this method and addTransitionToTarget() is that the latter does not give the developer the ability to leave parent states of the target and return to the target, but this method does. This method would be used in the following situation. The source is a descendent of the target state. The source wants to transition to the target state, leave the parent of the target state, and then re-enter the parent of the target state and finally go to the target state. This would be accomplished by giving a final parameter value of 1 (up 1 level above the target). If ulfxt == 0, this method is equivalent to addTransitionToTarget().

If the developer wants to manually code the event handler, then the developer uses chgSt() to fire this transition when it is triggered (just remember to hold onto the transition instance, which is the return value of this method).

By default, when the developer creates a transition with this method, the actual determination of transition path (through which nodes, up/down how many levels, etc.) is postponed until the first activation of the State Engine. This avoids the problem of defining a transition to a state that does not exist yet, for example, when two states have reciprocal transitions. However, if the developer has activated the state engine already, or called the state engine's prepareNetwork(), he can add a transition and have its path resolved immediately by first calling transPtr = addTransition(), then, calling transPtr.determineTransition().

Parameters

Add a transition from the current state to the history pseudo-state of a state.

The history pseudo-state is an automatic element part of an HState or HStateC. Conceptually, a transition to history makes the current state the last state visited in that state network. Therefore, you specify the target state that contains the history state. For example, if you have three states in the same network, A, B, and C, and A is current but C was the last state visited, you could add a transition from A -> history, and when that was triggered, the state engine would leave A and enter C.

If the developer wants to manually code the event handler, then the developer uses chgSt() to fire this transition when it is triggered (just remember to hold onto the transition instance, which is the return value of this method).

By default, when the developer creates a transition with this method, the actual determination of transition path (through which nodes, up/down how many levels, etc.) is postponed until the first activation of the State Engine. This avoids the problem of defining a transition to a state that does not exist yet, for example, when two states have reciprocal transitions. However, if the developer has activated the state engine already, or called the state engine's prepareNetwork(), he can add a transition and have its path resolved immediately by first calling transPtr = addTransition(), then, calling transPtr.determineTransition().

Parameters

Add a transition from this State to itself, specifying parents to exit and re-enter.

Use this method to transition out of the current state, up any number of parent state levels, then re-enter the state.

If the developer wants to manually code the event handler, then the developer uses chgSt() to fire this transition when it is triggered (just remember to hold onto the transition instance, which is the return value of this method).

By default, when the developer creates a transition with this method, the actual determination of transition path (through which nodes, up/down how many levels, etc.) is postponed until the first activation of the State Engine. This avoids the problem of defining a transition to a state that does not exist yet, for example, when two states have reciprocal transitions. However, if the developer has activated the state engine already, or called the state engine's prepareNetwork(), he can add a transition and have its path resolved immediately by first calling transPtr = addTransition(), then, calling transPtr.determineTransition().

Parameters

Add a transition from this State to a target state other than history.

Use this method to define a transition from one State to another. If the target state is the same as the source, this method exits the source and re-enters it. If the developer wants to exit parent states, use addTransitionToSelf which allows the developer to specify exactly how many levels to exit and re-enter.

To transition to the history pseudo-state, use addTransitionToHistory.

If the developer wants to manually code the event handler, then the developer uses chgSt() to fire this transition when it is triggered (just remember to hold onto the transition instance, which is the return value of this method).

By default, when the developer creates a transition with this method, the actual determination of transition path (through which nodes, up/down how many levels, etc.) is postponed until the first activation of the State Engine. This avoids the problem of defining a transition to a state that does not exist yet, for example, when two states have reciprocal transitions. However, if the developer has activated the state engine already, or called the state engine's prepareNetwork(), he can add a transition and have its path resolved immediately by first calling transPtr = addTransition(), then, calling transPtr.determineTransition().

Parameters

Change state using transition trans_i, with an optional value for the transition function as a second argument. If you look at the code, this function passes the information to the chgSt method of the state manager to do the real work. The reason we define this dummy is so that modelers see the direct relationship to the transition id, which is unique by state. For example, if a caller wants to change the current state, state 2, using transition 0, the caller would write:

This implies that the transition 0 is relative to the state. The same unaltered call would be

in which 'sm' is the state manager of state 2 and its siblings. It is less obvious from the second form that the processor is using the current state (2)'s transition 0, as opposed to, perhaps, state 1 or 6's transition with id 0.

The second argument, val, is an optional value to send in to the transition function.

Parameters

Called when a state is entered. This routine is for internal use, not for developers to override for executing actions on entry. 'hist' is true to use state history, false to use default start state. When we're told to jump into a specific sub-state, we don't want to allow the default start state or the history to get invoked. 'specIDs' tells us which sub-state, if not == null, we're jumping into. Therefore, for the state manager of that sub-state, we call activate() with this special sub-state id.

Parameters

convenience function. Returns true if this state is currently active, false if not.

isSubstate allows the caller to ask if a state is a substate of the state being called. It returns true if it is a substate, false if it is not. For simple states, it always returns false since there are no substates.

Parameters

Called when the state is exited (deactivated). This is a private routine and should not be overriden by developers.

This is a new feature of FStEng v1.5, which provides an easy way to direct and process events. Rather than having the developer provide an ieh() method, which determines the current state and which transitions or actions should be triggered, the new mechanism automatically routes the event to the most specific (deepest in network) active state's onEvent handler. The handler, by default, looks through the triggers of the transitions and internal actions on the state. If a trigger is true, it then fires the transition or action. The default routine passes the event to the state's parent to check its transitions and actions as well. If a transition gets fired, then parent states do not evaluate their transitions, but still evaluate their internal action triggers.

This extra processing can add time because all triggers are checked in the chain of active states, regardless of their chance of success. The beauty of this system is that if a state wants to optimize event handling for itself and its sub-networks, it merely needs to override onEvent and follow the rules about passing up the event once finished. If you really need to optimize the event handling, you can still override ieh() and bypass this feature completely, and do it as described in our book.

Parameters

Goes through substates to register them with the state engine.

Parameters

Removes the specified pulse activity from the state.

Parameters

Deletes memory associated with this state.

Remove the given transition from this State.

Unhook the given transition from the source state.

Parameters

Event generated on entry to a state.

Listeners will be notified when the state becomes active (is entered).

Event generated when the state is no longer active.

Listeners will be notified when the state is no longer an active state.