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 /**
 11   @class
 12   
 13   Apply to objects that are to represent a delegate for a SC.Statechart object.
 14   When assigned to a statechart, the statechart and its associated states will
 15   use the delegate in order to make various decisions.
 16   
 17   @see SC.Statechart#delegate 
 18 
 19   @author Michael Cohen
 20 */
 21 
 22 SC.StatechartDelegate = /** @scope SC.StatechartDelegate.prototype */ {
 23   
 24   // Walk like a duck
 25   isStatechartDelegate: YES,
 26   
 27   // Route Handling Management
 28   
 29   /**
 30     Called to update the application's current location. 
 31     
 32     The location provided is dependent upon the application's underlying
 33     routing mechanism.
 34     
 35     @param {SC.StatechartManager} statechart the statechart
 36     @param {String|Hash} location the new location 
 37     @param {SC.State} state the state requesting the location update
 38   */
 39   statechartUpdateLocationForState: function(statechart, location, state) {
 40     SC.routes.set('location', location);
 41   },
 42   
 43   /**
 44     Called to acquire the application's current location.
 45     
 46     @param {SC.StatechartManager} statechart the statechart
 47     @param {SC.State} state the state requesting the location
 48     @returns {String} the location 
 49   */
 50   statechartAcquireLocationForState: function(statechart, state) {
 51     return SC.routes.get('location');
 52   },
 53   
 54   /**
 55     Used to bind a state's handler to a route. When the application's location
 56     matches the given route, the state's handler is to be invoked. 
 57     
 58     The statechart and states remain completely independent of how the underlying 
 59     routing mechanism works thereby providing a looser coupling and more flexibility 
 60     in how routing is to work. Given this flexiblity, it is important that a route
 61     assigned (using the {@link SC.State#representRoute} property) to a state strictly 
 62     conforms to the underlying routing mechanism's criteria in order for the given 
 63     handler to be properly invoked.
 64     
 65     By default the {@link SC.routes} mechanism is used to bind the state's handler with
 66     the given route.
 67     
 68     @param {SC.StatechartManager} statechart the statechart
 69     @param {SC.State} state the state to bind the route to
 70     @param {String|Hash} route the route that is to be bound to the state
 71     @param {Function|String} handler the method on the state to be invoked when the route
 72       gets triggered.
 73       
 74     @see SC.State#representRoute
 75   */
 76   statechartBindStateToRoute: function(statechart, state, route, handler) {
 77     SC.routes.add(route, state, handler);
 78   },
 79   
 80   /**
 81     Invoked by a state that has been notified to handle a triggered route. The state
 82     asks if it should go ahead an actually handle the triggered route. If no then
 83     the state's handler will no longer continue and finish by calling this delegate's
 84     `statechartStateCancelledHandlingTriggeredRoute` method. If yes then the state will 
 85     continue with handling the triggered route.
 86     
 87     By default `YES` is returned.
 88     
 89     @param {SC.StatechartManager} statechart the statechart
 90     @param {SC.State} state the state making the request
 91     @param {SC.StateRouteHandlerContext} routeContext contextual information about the handling 
 92       of a route
 93     
 94     @see #statechartStateCancelledHandlingTriggeredRoute
 95   */
 96   statechartShouldStateHandleTriggeredRoute: function(statechart, state, context) {
 97     return YES;
 98   },
 99   
100   /**
101     Invoked by a state that has been informed by the delegate to not handle a triggered route.
102     Used this for any additional clean up or processing that you may wish to perform.
103     
104     @param {SC.StatechartManager} statechart the statechart
105     @param {SC.State} state the state making the request
106     @param {SC.StateRouteHandlerContext} routeContext contextual information about the handling 
107       of a route
108     
109     @see #statechartShouldStateHandleTriggeredRoute
110   */
111   statechartStateCancelledHandlingTriggeredRoute: function(statechart, state, context) { }
112   
113 };