sproutcore 1.5.0-java → 1.6.0.beta.2-java

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

@@ -508,15 +508,11 @@ SC.State = SC.Object.extend({
     
     Method can be called in the following ways: 
     
-    {{{
-    
-      // With one argument
-      gotoState(<state>)
+        // With one argument
+        gotoState(<state>)
       
-      // With two arguments
-      gotoState(<state>, <hash>)
-    
-    }}}
+        // With two arguments
+        gotoState(<state>, <hash>)
     
     Where <state> is either a string or a SC.State object and <hash> is a regular JS hash object.
     
@@ -545,18 +541,14 @@ SC.State = SC.Object.extend({
     
     Method can be called in the following ways:
     
-    {{{
+        // With one argument
+        gotoHistoryState(<state>)
     
-      // With one argument
-      gotoHistoryState(<state>)
-      
-      // With two arguments
-      gotoHistoryState(<state>, <boolean | hash>)
-      
-      // With three arguments
-      gotoHistoryState(<state>, <boolean>, <hash>)
+        // With two arguments
+        gotoHistoryState(<state>, <boolean | hash>)
     
-    }}}
+        // With three arguments
+        gotoHistoryState(<state>, <boolean>, <hash>)
     
     Where <state> is either a string or a SC.State object and <hash> is a regular JS hash object.
     
@@ -692,10 +684,10 @@ SC.State = SC.Object.extend({
     
     There is a particular order in how an event is handled by a state:
     
-      1) Basic function whose name matches the event
-      2) Registered event handler that is associated with an event represented as a string
-      3) Registered event handler that is associated with events matching a regular expression
-      4) The unknownEvent function
+     1. Basic function whose name matches the event
+     2. Registered event handler that is associated with an event represented as a string
+     3. Registered event handler that is associated with events matching a regular expression
+     4. The unknownEvent function
       
     Use of event handlers that are associated with events matching a regular expression may
     incur a performance hit, so they should be used sparingly.
@@ -706,33 +698,29 @@ SC.State = SC.Object.extend({
     
     Example of a state using all four event handling techniques:
     
-    {{{
-    
-      SC.State.extend({
+        SC.State.extend({
       
-        // Basic function handling event 'foo'
-        foo: function(arg1, arg2) { ... },
+          // Basic function handling event 'foo'
+          foo: function(arg1, arg2) { ... },
         
-        // event handler that handles 'frozen' and 'canuck'
-        eventHandlerA: function(event, arg1, arg2) {
-          ...
-        }.handleEvent('frozen', 'canuck'),
+          // event handler that handles 'frozen' and 'canuck'
+          eventHandlerA: function(event, arg1, arg2) {
+            ...
+          }.handleEvent('frozen', 'canuck'),
         
-        // event handler that handles events matching the regular expression /num\d/
-        //   ex. num1, num2
-        eventHandlerB: function(event, arg1, arg2) {
-          ...
-        }.handleEvent(/num\d/),
+          // event handler that handles events matching the regular expression /num\d/
+          //   ex. num1, num2
+          eventHandlerB: function(event, arg1, arg2) {
+            ...
+          }.handleEvent(/num\d/),
         
-        // Handle any event that was not handled by some other
-        // method on the state
-        unknownEvent: function(event, arg1, arg2) {
+          // Handle any event that was not handled by some other
+          // method on the state
+          unknownEvent: function(event, arg1, arg2) {
         
-        }
+          }
       
-      })
-    
-    }}}
+        });
   */
   tryToHandleEvent: function(event, arg1, arg2) {
 
@@ -795,13 +783,9 @@ SC.State = SC.Object.extend({
     as an animation or fetching remote data, then you need to return an asynchronous 
     action, which is done like so:
     
-    {{{
-    
-      enterState: function() {
-        return this.performAsync('foo');
-      }
-    
-    }}}
+        enterState: function() {
+          return this.performAsync('foo');
+        }
     
     After returning an action to be performed asynchronously, the statechart will suspend
     the active state transition process. In order to resume the process, you must call
@@ -845,13 +829,9 @@ SC.State = SC.Object.extend({
     as an animation or fetching remote data, then you need to return an asynchronous 
     action, which is done like so:
     
-    {{{
-    
-      exitState: function() {
-        return this.performAsync('foo');
-      }
-    
-    }}}
+        exitState: function() {
+          return this.performAsync('foo');
+        }
     
     After returning an action to be performed asynchronously, the statechart will suspend
     the active state transition process. In order to resume the process, you must call
@@ -1055,35 +1035,21 @@ SC.State = SC.Object.extend({
   
   Example:
   
-    {{{
-    
       MyApp.statechart = SC.Statechart.create({
-      
         rootState: SC.State.design({
-        
           initialSubstate: 'a',
-          
           a: SC.State.plugin('path.to.a.state.class'),
-          
           b: SC.State.plugin('path.to.another.state.class')
-        
         })
-      
-      })
-    
-    }}}
+      });
     
   You can also supply hashes the plugin feature in order to enhance a state or
   implement required functionality:
-  
-    {{{
-    
+
       SomeMixin = { ... };
-    
+
       stateA: SC.State.plugin('path.to.state', SomeMixin, { ... })
-    
-    }}}
-  
+
   @param value {String} property path to a state class
   @param args {Hash,...} Optional. Hash objects to be added to the created state
 */
@@ -1107,39 +1073,25 @@ SC.State.design = SC.State.extend;
   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) { ... }
-    
-    })
-  
-  }}}
+      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')
-    
-    })
-  
-  }}}
-  
+
+      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 
@@ -1172,29 +1124,18 @@ Function.prototype.handleEvents = function() {
   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')
-    
-    })
-  
-  }}}
+      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
@@ -1225,10 +1166,7 @@ Function.prototype.stateObserves = function() {
   
   An example of how to use:
   
-  {{{
-  
     stateA: SC.State.design({
-    
       initialSubstate: SC.HistoryState({
         defaultState: 'stateB'
       }),
@@ -1236,12 +1174,7 @@ Function.prototype.stateObserves = function() {
       stateB: SC.State.design({ ... }),
       
       stateC: SC.State.design({ ... })
-    
     })
-  
-  }}}
-  
-  
 */
 SC.HistoryState = SC.Object.extend({
 

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

@@ -25,14 +25,10 @@ sc_require('system/state');
   
   The following example shows how states are nested within a statechart:
   
-    {{{
-    
       MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
-      
         rootState: SC.State.design({
-      
           initialSubstate: 'stateA',
-        
+
           stateA: SC.State.design({
             // ... can continue to nest further states
           }),
@@ -41,10 +37,7 @@ sc_require('system/state');
             // ... can continue to nest further states
           })
         })
-      
-      })
-    
-    }}}
+      });
   
   Note how in the example above, the root state as an explicit initial substate to enter into. If no
   initial substate is provided, then the statechart will default to the the state's first substate.
@@ -53,12 +46,9 @@ sc_require('system/state');
   on your object that represents states. Upon initialization, a root state will be constructed automatically
   by the mixin and make the states on the object substates of the root state. As an example:
   
-    {{{
-  
       MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
-    
         initialState: 'stateA',
-      
+
         stateA: SC.State.design({
           // ... can continue to nest further states
         }),
@@ -66,10 +56,7 @@ sc_require('system/state');
         stateB: SC.State.design({
           // ... can continue to nest further states
         })
-    
-      })
-  
-    }}} 
+      });
   
   If you liked to specify a class that should be used as the root state but using the above method to defined
   states, you can set the rootStateExample property with a class that extends from SC.State. If the 
@@ -80,14 +67,10 @@ sc_require('system/state');
   independent state structure from other concurrent states. The following example shows how to provide your
   statechart with concurrent states:
   
-    {{{
-    
       MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
-      
         rootState: SC.State.design({
-      
           substatesAreConcurrent: YES,
-        
+
           stateA: SC.State.design({
             // ... can continue to nest further states
           }),
@@ -96,10 +79,7 @@ sc_require('system/state');
             // ... can continue to nest further states
           })
         })
-      
-      })
-    
-    }}}
+      });
   
   Above, to indicate that a state's substates are concurrent, you just have to set the substatesAreConcurrent to 
   YES. Once done, then stateA and stateB will be independent of each other and each will manage their
@@ -108,12 +88,9 @@ sc_require('system/state');
   To define concurrent states directly on the object without explicitly defining a root, you can do the 
   following:
   
-    {{{
-
       MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
-  
         statesAreConcurrent: YES,
-    
+
         stateA: SC.State.design({
           // ... can continue to nest further states
         }),
@@ -121,94 +98,67 @@ sc_require('system/state');
         stateB: SC.State.design({
           // ... can continue to nest further states
         })
-  
-      })
-
-    }}}
+      });
   
   Remember that a startchart can have a mixture of nested and concurrent states in order for you to 
   create as complex of statecharts that suite your needs. Here is an example of a mixed state structure:
   
-    {{{
-    
       MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
-      
         rootState: SC.State.design({
-      
           initialSubstate: 'stateA',
-        
+
           stateA: SC.State.design({
-          
             substatesAreConcurrent: YES,
-          
+
             stateM: SC.State.design({ ... })
             stateN: SC.State.design({ ... })
             stateO: SC.State.design({ ... })
-          
           }),
         
           stateB: SC.State.design({
-          
             initialSubstate: 'stateX',
-          
+
             stateX: SC.State.design({ ... })
             stateY: SC.State.desgin({ ... })
-          
           })
         })
-      
-      })
-    
-    }}}
+      });
   
   Depending on your needs, a statechart can have lots of states, which can become hard to manage all within
   one file. To modularize your states and make them easier to manage and maintain, you can plug-in states
   into other states. Let's say we are using the statechart in the last example above, and all the code is 
   within one file. We could update the code and split the logic across two or more files like so:
-  
-    {{{
-      ---- state_a.js
-  
+
+      // state_a.js
+
       MyApp.StateA = SC.State.extend({
-    
         substatesAreConcurrent: YES,
-    
+
         stateM: SC.State.design({ ... })
         stateN: SC.State.design({ ... })
         stateO: SC.State.design({ ... })
-    
       });
-    
-      ---- state_b.js
-    
+
+      // state_b.js
+
       MyApp.StateB = SC.State.extend({
-    
         substatesAreConcurrent: YES,
-    
+
         stateM: SC.State.design({ ... })
         stateN: SC.State.design({ ... })
         stateO: SC.State.design({ ... })
-    
       });
-    
-      ---- statechart.js
-    
+
+      // statechart.js
+
       MyApp.Statechart = SC.Object.extend(SC.StatechartManager, {
-    
         rootState: SC.State.design({
-    
           initialSubstate: 'stateA',
-      
           stateA: SC.State.plugin('MyApp.StateA'),
-      
           stateB: SC.State.plugin('MyApp.StateB')
-        
         })
-    
-      })
-  
-    }}}
-    
+      });
+
   Using state plug-in functionality is optional. If you use the plug-in feature you can break up your statechart
   into as many files as you see fit.
 
@@ -552,22 +502,18 @@ SC.StatechartManager = {
     
     Method can be called in the following ways:
     
-    {{{
-    
-      // With one argument. 
-      gotoState(<state>)
+        // With one argument. 
+        gotoState(<state>)
       
-      // With two argument.
-      gotoState(<state>, <state | boolean | hash>)
+        // With two argument.
+        gotoState(<state>, <state | boolean | hash>)
       
-      // With three argument.
-      gotoState(<state>, <state>, <boolean | hash>)
-      gotoState(<state>, <boolean>, <hash>)
+        // With three argument.
+        gotoState(<state>, <state>, <boolean | hash>)
+        gotoState(<state>, <boolean>, <hash>)
       
-      // With four argument.
-      gotoState(<state>, <state>, <boolean>, <hash>)
-    
-    }}}
+        // With four argument.
+        gotoState(<state>, <state>, <boolean>, <hash>)
     
     where <state> is either a SC.State object or a string and <hash> is a regular JS hash object.
     
@@ -885,22 +831,18 @@ SC.StatechartManager = {
     
     Method can be called in the following ways:
     
-    {{{
-    
-      // With one arguments. 
-      gotoHistorytate(<state>)
+        // With one arguments. 
+        gotoHistorytate(<state>)
       
-      // With two arguments. 
-      gotoHistorytate(<state>, <state | boolean | hash>)
+        // With two arguments. 
+        gotoHistorytate(<state>, <state | boolean | hash>)
       
-      // With three arguments.
-      gotoHistorytate(<state>, <state>, <boolean | hash>)
-      gotoHistorytate(<state>, <boolean>, <hash>)
+        // With three arguments.
+        gotoHistorytate(<state>, <state>, <boolean | hash>)
+        gotoHistorytate(<state>, <boolean>, <hash>)
       
-      // With four argumetns
-      gotoHistorytate(<state>, <state>, <boolean>, <hash>)
-    
-    }}}
+        // With four argumetns
+        gotoHistorytate(<state>, <state>, <boolean>, <hash>)
     
     where <state> is either a SC.State object or a string and <hash> is a regular JS hash object.
     
@@ -1208,23 +1150,18 @@ SC.StatechartManager = {
     
     A few notes: 
     
-      1) Calling this is not the same as calling sendEvent or sendAction.
-         Rather, this should be seen as calling normal methods on a state that 
-         will *not* call gotoState or gotoHistoryState. 
-      
-      2) A state will only ever be invoked once per call. So if there are two 
-         or more current states that have the same parent state, then that parent 
-         state will only be invoked once if none of the current states are able
-         to invoke the given method.
+     1. Calling this is not the same as calling sendEvent or sendAction.
+        Rather, this should be seen as calling normal methods on a state that 
+        will *not* call gotoState or gotoHistoryState.
+     2. A state will only ever be invoked once per call. So if there are two 
+        or more current states that have the same parent state, then that parent 
+        state will only be invoked once if none of the current states are able
+        to invoke the given method.
     
     When calling this method, you are able to supply zero ore more arguments
     that can be pass onto the method called on the states. As an example
     
-    {{{
-    
-      invokeStateMethod('render', context, firstTime);
-    
-    }}}
+        invokeStateMethod('render', context, firstTime);
     
     The above call will invoke the render method on the current states
     and supply the context and firstTime arguments to the method. 
@@ -1235,14 +1172,10 @@ SC.StatechartManager = {
     we want to call a calculate method on the current states where the method
     will return a value when invoked. We can handle the returned values like so:
     
-    {{{
-    
-      invokeStateMethod('calculate', value, function(state, result) {
-        // .. handle the result returned from calculate that was invoked
-        //    on the given state
-      })
-    
-    }}}
+        invokeStateMethod('calculate', value, function(state, result) {
+          // .. handle the result returned from calculate that was invoked
+          //    on the given state
+        })
     
     If the method invoked does not return a value and a callback function is
     supplied, then result value will simply be undefined. In all cases, if
@@ -1414,9 +1347,9 @@ SC.StatechartManager = {
     it based on properties found on this state that derive from a SC.State class. For the
     root state to be successfully built, the following much be met:
     
-      - The rootStateExample property must be defined with a class that derives from SC.State
-      - Either the initialState or statesAreConcurrent property must be set, but not both
-      - There must be one or more states that can be added to the root state
+     - The rootStateExample property must be defined with a class that derives from SC.State
+     - Either the initialState or statesAreConcurrent property must be set, but not both
+     - There must be one or more states that can be added to the root state
       
   */
   _constructRootStateClass: function() {
@@ -1585,25 +1518,21 @@ SC.Async.mixin({
     
     Examples:
     
-    {{
+        SC.State.extend({
     
-      SC.State.extend({
-    
-        enterState: function() {
-          return SC.Async.perform('foo');
-        },
+          enterState: function() {
+            return SC.Async.perform('foo');
+          },
       
-        exitState: function() {
-          return SC.Async.perform('bar', 100);
-        }
+          exitState: function() {
+            return SC.Async.perform('bar', 100);
+          }
       
-        foo: function() { ... },
+          foo: function() { ... },
       
-        bar: function(arg) { ... }
-    
-      });
+          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