// ========================================================================== // Project: SC.Statechart - A Statechart Framework for SproutCore // Copyright: ©2010, 2011 Michael Cohen, and contributors. // Portions @2011 Apple Inc. All rights reserved. // License: Licensed under MIT license (see license.js) // ==========================================================================

/*globals SC */

/**

@class

Apply to objects that are to represent a delegate for a SC.Statechart object.
When assigned to a statechart, the statechart and its associated states will
use the delegate in order to make various decisions.

@see SC.Statechart#delegate 

@author Michael Cohen

*/

SC.StatechartDelegate = /** @scope SC.StatechartDelegate.prototype */ {

// Walk like a duck
isStatechartDelegate: YES,

// Route Handling Management

/**
  Called to update the application's current location. 

  The location provided is dependent upon the application's underlying
  routing mechanism.

  @param {SC.StatechartManager} statechart the statechart
  @param {String|Hash} location the new location 
  @param {SC.State} state the state requesting the location update
*/
statechartUpdateLocationForState: function(statechart, location, state) {
  SC.routes.set('location', location);
},

/**
  Called to acquire the application's current location.

  @param {SC.StatechartManager} statechart the statechart
  @param {SC.State} state the state requesting the location
  @returns {String} the location 
*/
statechartAcquireLocationForState: function(statechart, state) {
  return SC.routes.get('location');
},

/**
  Used to bind a state's handler to a route. When the application's location
  matches the given route, the state's handler is to be invoked. 

  The statechart and states remain completely independent of how the underlying 
  routing mechanism works thereby providing a looser coupling and more flexibility 
  in how routing is to work. Given this flexiblity, it is important that a route
  assigned (using the {@link SC.State#representRoute} property) to a state strictly 
  conforms to the underlying routing mechanism's criteria in order for the given 
  handler to be properly invoked.

  By default the {@link SC.routes} mechanism is used to bind the state's handler with
  the given route.

  @param {SC.StatechartManager} statechart the statechart
  @param {SC.State} state the state to bind the route to
  @param {String|Hash} route the route that is to be bound to the state
  @param {Function|String} handler the method on the state to be invoked when the route
    gets triggered.

  @see SC.State#representRoute
*/
statechartBindStateToRoute: function(statechart, state, route, handler) {
  SC.routes.add(route, state, handler);
},

/**
  Invoked by a state that has been notified to handle a triggered route. The state
  asks if it should go ahead an actually handle the triggered route. If no then
  the state's handler will no longer continue and finish by calling this delegate's
  `statechartStateCancelledHandlingTriggeredRoute` method. If yes then the state will 
  continue with handling the triggered route.

  By default `YES` is returned.

  @param {SC.StatechartManager} statechart the statechart
  @param {SC.State} state the state making the request
  @param {SC.StateRouteHandlerContext} routeContext contextual information about the handling 
    of a route

  @see #statechartStateCancelledHandlingTriggeredRoute
*/
statechartShouldStateHandleTriggeredRoute: function(statechart, state, context) {
  return YES;
},

/**
  Invoked by a state that has been informed by the delegate to not handle a triggered route.
  Used this for any additional clean up or processing that you may wish to perform.

  @param {SC.StatechartManager} statechart the statechart
  @param {SC.State} state the state making the request
  @param {SC.StateRouteHandlerContext} routeContext contextual information about the handling 
    of a route

  @see #statechartShouldStateHandleTriggeredRoute
*/
statechartStateCancelledHandlingTriggeredRoute: function(statechart, state, context) { }

};