sproutcore 1.6.0.beta.3-java → 1.6.0-java

data/lib/frameworks/sproutcore/frameworks/statechart/debug/sequence_matcher.js

@@ -0,0 +1,189 @@
+// ==========================================================================
+// 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 */
+
+SC.StatechartSequenceMatcher = SC.Object.extend({
+  
+  statechartMonitor: null,
+  
+  match: null,
+  
+  MISMATCH: {},
+  
+  begin: function() {
+    this._stack = [];
+    this.beginSequence();
+    this._start = this._stack[0];
+    return this;
+  },
+  
+  end: function() {
+    this.endSequence();
+    
+    if (this._stack.length > 0) {
+      throw "can not match sequence. sequence matcher has been left in an invalid state";
+    }
+    
+    var monitor = this.statechartMonitor,
+        result = this._matchSequence(this._start, 0) === monitor.sequence.length;
+
+    this.set('match', result);
+    
+    return result;
+  },
+  
+  entered: function() {
+    this._addStatesToCurrentGroup('entered', arguments);
+    return this;
+  },
+  
+  exited: function() {
+    this._addStatesToCurrentGroup('exited', arguments);
+    return this;
+  },
+  
+  beginConcurrent: function() {
+    var group = {
+      type: 'concurrent',
+      values: []
+    };
+    if (this._peek()) this._peek().values.push(group);
+    this._stack.push(group);
+    return this;
+  },
+  
+  endConcurrent: function() {
+    this._stack.pop();
+    return this;
+  },
+  
+  beginSequence: function() {
+    var group = {
+      type: 'sequence',
+      values: []
+    };
+    if (this._peek()) this._peek().values.push(group);
+    this._stack.push(group);
+    return this;
+  },
+  
+  endSequence: function() {
+    this._stack.pop();
+    return this;
+  },
+  
+  _peek: function() {
+    var len = this._stack.length;
+    return len === 0 ? null : this._stack[len - 1];
+  },
+  
+  _addStatesToCurrentGroup: function(action, states) {
+    var group = this._peek(), len = states.length, i = 0;
+    for (; i < len; i += 1) {
+      group.values.push({ action: action, state: states[i] });
+    }
+  },
+  
+  _matchSequence: function(sequence, marker) {
+    var values = sequence.values, 
+        len = values.length, 
+        i = 0, val,
+        monitor = this.statechartMonitor;
+        
+    if (len === 0) return marker;
+    if (marker > monitor.sequence.length) return this.MISMATCH;
+        
+    for (; i < len; i += 1) {
+      val = values[i];
+      
+      if (val.type === 'sequence') {
+        marker = this._matchSequence(val, marker);
+      } else if (val.type === 'concurrent') {
+        marker = this._matchConcurrent(val, marker);
+      } else if (!this._matchItems(val, monitor.sequence[marker])){
+        return this.MISMATCH;
+      } else {
+        marker += 1;
+      }
+      
+      if (marker === this.MISMATCH) return this.MISMATCH;
+    }
+    
+    return marker;
+  },
+
+  // A
+  // B (concurrent [X, Y])
+  //   X
+  //     M
+  //     N
+  //   Y
+  //     O
+  //     P
+  // C
+  // 
+  // 0 1  2 3 4   5 6 7  8
+  //      ^       ^
+  // A B (X M N) (Y O P) C
+  //      ^       ^
+  // A B (Y O P) (X M N) C
+  
+  _matchConcurrent: function(concurrent, marker) {
+    var values = SC.clone(concurrent.values), 
+        len = values.length, 
+        i = 0, val, tempMarker = marker, match = false,
+        monitor = this.statechartMonitor;
+        
+    if (len === 0) return marker;
+    if (marker > monitor.sequence.length) return this.MISMATCH;
+    
+    while (values.length > 0) {
+      for (i = 0; i < len; i += 1) {
+        val = values[i];
+      
+        if (val.type === 'sequence') {
+          tempMarker = this._matchSequence(val, marker);
+        } else if (val.type === 'concurrent') {
+          tempMarker = this._matchConcurrent(val, marker);
+        } else if (!this._matchItems(val, monitor.sequence[marker])){
+          tempMarker = this.MISMATCH;
+        } else {
+          tempMarker = marker + 1;
+        }
+      
+        if (tempMarker !== this.MISMATCH) break;
+      }
+      
+      if (tempMarker === this.MISMATCH) return this.MISMATCH;
+      values.removeAt(i);
+      len = values.length;
+      marker = tempMarker;
+    }
+    
+    return marker;
+  },
+  
+  _matchItems: function(matcherItem, monitorItem) {
+    if (!matcherItem || !monitorItem) return false;
+  
+    if (matcherItem.action !== monitorItem.action) {
+      return false;
+    }
+    
+    if (SC.typeOf(matcherItem.state) === SC.T_OBJECT && matcherItem.state === monitorItem.state) {
+      return true;      
+    }
+    
+    if (matcherItem.state === monitorItem.state.get('name')) {
+      return true;
+    }
+  
+    return false;
+  }
+  
+});

data/lib/frameworks/sproutcore/frameworks/statechart/ext/function.js

@@ -0,0 +1,122 @@
+// ==========================================================================
+// 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 */
+
+/**
+  Extends the JS Function object with the handleEvents method that
+  will provide more advanced event handling capabilities when constructing
+  your statechart's states.
+  
+  By default, when you add a method to a state, the state will react to 
+  events that matches a method's name, like so:
+  
+  {{{
+  
+    state = SC.State.extend({
+    
+      // Will be invoked when a event named "foo" is sent to this state
+      foo: function(event, sender, context) { ... }
+    
+    })
+  
+  }}}
+  
+  In some situations, it may be advantageous to use one method that can react to 
+  multiple events instead of having multiple methods that essentially all do the
+  same thing. In order to set a method to handle more than one event you use
+  the handleEvents method which can be supplied a list of string and/or regular
+  expressions. The following example demonstrates the use of handleEvents:
+  
+  {{{
+  
+    state = SC.State.extend({
+    
+      eventHandlerA: function(event, sender, context) {
+      
+      }.handleEvents('foo', 'bar'),
+      
+      eventHandlerB: function(event, sender, context) {
+      
+      }.handleEvents(/num\d/, 'decimal')
+    
+    })
+  
+  }}}
+  
+  Whenever events 'foo' and 'bar' are sent to the state, the method eventHandlerA
+  will be invoked. When there is an event that matches the regular expression
+  /num\d/ or the event is 'decimal' then eventHandlerB is invoked. In both 
+  cases, the name of the event will be supplied to the event handler. 
+  
+  It should be noted that the use of regular expressions may impact performance
+  since that statechart will not be able to fully optimize the event handling logic based
+  on its use. Therefore the use of regular expression should be used sparingly. 
+  
+  @param {(String|RegExp)...} args
+*/
+Function.prototype.handleEvents = function() {
+  this.isEventHandler = YES;
+  this.events = arguments;
+  return this;
+};
+
+/**
+  Extends the JS Function object with the stateObserves method that will
+  create a state observe handler on a given state object. 
+  
+  Use a stateObserves() instead of the common observes() method when you want a 
+  state to observer changes to some property on the state itself or some other 
+  object. 
+  
+  Any method on the state that has stateObserves is considered a state observe
+  handler and behaves just like when you use observes() on a method, but with an
+  important difference. When you apply stateObserves to a method on a state, those
+  methods will be active *only* when the state is entered, otherwise those methods
+  will be inactive. This removes the need for you having to explicitly call
+  addObserver and removeObserver. As an example:
+  
+  {{{
+  
+    state = SC.State.extend({
+    
+      foo: null,
+      
+      user: null,
+    
+      observeHandlerA: function(target, key) {
+        
+      }.stateObserves('MyApp.someController.status'),
+      
+      observeHandlerB: function(target, key) {
+      
+      }.stateObserves('foo'),
+      
+      observeHandlerC: function(target, key) {
+      
+      }.stateObserves('.user.name', '.user.salary')
+    
+    })
+  
+  }}}
+  
+  Above, state has three state observe handlers: observeHandlerA, observeHandlerB, and
+  observeHandlerC. When state is entered, the state will automatically add itself as
+  an observer for all of its registered state observe handlers. Therefore when
+  foo changes, observeHandlerB will be invoked, and when MyApp.someController's status
+  changes then observeHandlerA will be invoked. The moment that state is exited then
+  the state will automatically remove itself as an observer for all of its registered
+  state observe handlers. Therefore none of the state observe handlers will be
+  invoked until the next time the state is entered. 
+  
+  @param {String...} args
+*/
+Function.prototype.stateObserves = function() {
+  this.isStateObserveHandler = YES;
+  this.args = SC.A(arguments);
+  return this;
+};

data/lib/frameworks/sproutcore/frameworks/statechart/system/async.js

@@ -0,0 +1,88 @@
+// ==========================================================================
+// 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
+
+  Represents a call that is intended to be asynchronous. This is
+  used during a state transition process when either entering or
+  exiting a state.
+
+  @extends SC.Object
+  @author Michael Cohen
+*/
+SC.Async = SC.Object.extend(
+  /** @scope SC.Async.prototype */{
+  
+  func: null,
+  
+  arg1: null,
+  
+  arg2: null,
+  
+  /** @private
+    Called by the statechart
+  */
+  tryToPerform: function(state) {
+    var func = this.get('func'),
+        arg1 = this.get('arg1'),
+        arg2 = this.get('arg2'),
+        funcType = SC.typeOf(func);
+      
+    if (funcType === SC.T_STRING) {
+      state.tryToPerform(func, arg1, arg2);
+    } 
+    else if (funcType === SC.T_FUNCTION) {
+      func.apply(state, [arg1, arg2]);
+    }
+  }
+  
+});
+
+/**
+  Singleton
+*/
+SC.Async.mixin(/** @scope SC.Async */{
+  
+  /**
+    Call in either a state's enterState or exitState method when you
+    want a state to perform an asynchronous action, such as an animation.
+    
+    Examples:
+    
+    {{
+    
+      SC.State.extend({
+    
+        enterState: function() {
+          return SC.Async.perform('foo');
+        },
+      
+        exitState: function() {
+          return SC.Async.perform('bar', 100);
+        }
+      
+        foo: function() { ... },
+      
+        bar: function(arg) { ... }
+    
+      });
+    
+    }}
+    
+    @param func {String|Function} the functio to be invoked on a state
+    @param arg1 Optional. An argument to pass to the given function
+    @param arg2 Optional. An argument to pass to the given function
+    @return {SC.Async} a new instance of a SC.Async
+  */
+  perform: function(func, arg1, arg2) {
+    return SC.Async.create({ func: func, arg1: arg1, arg2: arg2 });
+  }
+  
+});

data/lib/frameworks/sproutcore/frameworks/statechart/system/empty_state.js

@@ -0,0 +1,34 @@
+// ==========================================================================
+// 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 */
+
+sc_require('system/state');
+
+/** 
+  The default name given to an empty state
+*/
+SC.EMPTY_STATE_NAME = "__EMPTY_STATE__";
+
+/**
+  @class
+  
+  Represents an empty state that gets assigned as a state's initial substate 
+  if the state does not have an initial substate defined.
+
+  @extends SC.State
+*/
+SC.EmptyState = SC.State.extend(/** @scope SC.EmptyState.prototype */{
+  
+  name: SC.EMPTY_STATE_NAME,
+  
+  enterState: function() {
+    var msg = "No initial substate was defined for state %@. Entering default empty state";
+    this.stateLogWarning(msg.fmt(this.get('parentState')));
+  }
+  
+});

data/lib/frameworks/sproutcore/frameworks/statechart/system/history_state.js

@@ -0,0 +1,97 @@
+// ==========================================================================
+// 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 */
+
+sc_require('system/state');
+
+/**
+  @class
+
+  Represents a history state that can be assigned to a SC.State object's
+  initialSubstate property. 
+  
+  If a SC.HistoryState object is assigned to a state's initial substate, 
+  then after a state is entered the statechart will refer to the history 
+  state object to determine the next course of action. If the state has 
+  its historyState property assigned then the that state will be entered, 
+  otherwise the default state assigned to history state object will be entered.
+  
+  An example of how to use:
+  
+    stateA: SC.State.design({
+    
+      initialSubstate: SC.HistoryState({
+        defaultState: 'stateB'
+      }),
+      
+      stateB: SC.State.design({ ... }),
+      
+      stateC: SC.State.design({ ... })
+    
+    })
+  
+  @author Michael Cohen
+  @extends SC.Object
+*/
+SC.HistoryState = SC.Object.extend(
+  /** @scope SC.HistoryState.prototype */{
+
+  /**
+    Used to indicate if the statechart should recurse the 
+    history states after entering the this object's parent state
+    
+    @property {Boolean}
+  */
+  isRecursive: NO,
+  
+  /**
+    The default state to enter if the parent state does not
+    yet have its historyState property assigned to something 
+    other than null.
+    
+    The value assigned to this property must be the name of an
+    immediate substate that belongs to the parent state. The
+    statechart will manage the property upon initialization.
+    
+    @property {String}
+  */
+  defaultState: null,
+  
+  /** @private
+    Managed by the statechart 
+    
+    The statechart that owns this object.
+  */
+  statechart: null,
+  
+  /** @private
+    Managed by the statechart 
+  
+    The state that owns this object
+  */
+  parentState: null,
+  
+  /**
+    Used by the statechart during a state transition process. 
+    
+    Returns a state to enter based on whether the parent state has
+    its historyState property assigned. If not then this object's
+    assigned default state is returned.
+  */
+  state: function() {
+    var defaultState = this.get('defaultState'),
+        historyState = this.getPath('parentState.historyState');
+    return !!historyState ? historyState : defaultState;
+  }.property().cacheable(),
+  
+  /** @private */
+  parentHistoryStateDidChange: function() {
+    this.notifyPropertyChange('state');
+  }.observes('*parentState.historyState')
+  
+});