1 // ==========================================================================
  2 // Project:   SC.Statechart - A Statechart Framework for SproutCore
  3 // Copyright: ©2010, 2011 Michael Cohen, and contributors.
  4 //            Portions @2011 Apple Inc. All rights reserved.
  5 // License:   Licensed under MIT license (see license.js)
  6 // ==========================================================================
  7 
  8 /*globals SC */
  9 
 10 sc_require('system/state');
 11 
 12 /**
 13   @class
 14 
 15   Represents a history state that can be assigned to a SC.State object's
 16   initialSubstate property.
 17 
 18   If a SC.HistoryState object is assigned to a state's initial substate,
 19   then after a state is entered the statechart will refer to the history
 20   state object to determine the next course of action. If the state has
 21   its historyState property assigned then the that state will be entered,
 22   otherwise the default state assigned to history state object will be entered.
 23 
 24   An example of how to use:
 25 
 26     stateA: SC.State.design({
 27 
 28       initialSubstate: SC.HistoryState({
 29         defaultState: 'stateB'
 30       }),
 31 
 32       stateB: SC.State.design({ ... }),
 33 
 34       stateC: SC.State.design({ ... })
 35 
 36     })
 37 
 38   @author Michael Cohen
 39   @extends SC.Object
 40 */
 41 SC.HistoryState = SC.Object.extend(
 42   /** @scope SC.HistoryState.prototype */{
 43 
 44   /**
 45     Used to indicate if the statechart should recurse the
 46     history states after entering the this object's parent state
 47 
 48     @type Boolean
 49   */
 50   isRecursive: NO,
 51 
 52   /**
 53     The default state to enter if the parent state does not
 54     yet have its historyState property assigned to something
 55     other than null.
 56 
 57     The value assigned to this property must be the name of an
 58     immediate substate that belongs to the parent state. The
 59     statechart will manage the property upon initialization.
 60 
 61     @type String
 62   */
 63   defaultState: null,
 64 
 65   /** @private
 66     Managed by the statechart
 67 
 68     The statechart that owns this object.
 69   */
 70   statechart: null,
 71 
 72   /** @private
 73     Managed by the statechart
 74 
 75     The state that owns this object
 76   */
 77   parentState: null,
 78 
 79   /**
 80     Used by the statechart during a state transition process.
 81 
 82     Returns a state to enter based on whether the parent state has
 83     its historyState property assigned. If not then this object's
 84     assigned default state is returned.
 85   */
 86   state: function() {
 87     var defaultState = this.get('defaultState'),
 88         historyState = this.getPath('parentState.historyState');
 89     return !!historyState ? historyState : defaultState;
 90   }.property().cacheable(),
 91 
 92   /** @private */
 93   parentHistoryStateDidChange: function() {
 94     this.notifyPropertyChange('state');
 95   }.observes('*parentState.historyState')
 96 
 97 });
 98