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