Events Flow

Events Flow is a language extension of ActionScript3, that is designed for creating finite-state machines, to describe a “pathway” of an application and to automate event subscription. Useful for event maps creation in games and complicated interfaces. ##Annotations

###[Flow]

Events flow method annotation, that makes the execution flow “stop” until some event(s) have completed.

[Flow] 
public function eventsFlowTest() : void { 

}

###[Flow( result= result1[, result2 … resultN] )]

Extended syntax with enumerated results (see also exit statement and result type).

[Flow(result=sucess,fail)] 
public function eventsFlowTest() : void { 

}

##Work with Events

###catch dispatcher[.event.eventType]

Catch-the-event expression is a special expression that stops the execution flow of an application until the event is completed.After completion, it automatically unsubscribes from the event. Returns event type (see also event type reference).

Please, note that catch expression has a limitation: it can be placed into a while… cycle, but it will not work inside a for… cycle.

[Flow] 
public function eventsFlowTest() : void { 
  catch stage.event<KeyboardEvent.KEY_DOWN>; 
  trace "key down"; 
}

###catch dispatcher[.keystroke.< modifier, symbol >]

A variation of catch-the-event expression. Keystroke is a custom event-listener that allows to specify two parameters: modifier and symbol.

[Flow] 
public function eventsFlowTest() : void { 
  catch stage.keystroke<ctrl+shift, A>; // catch Ctrl+Shift+A keystroke 
  trace "key down"; 
}

Modifiers: ctrl, alt, shift, ctrl+alt+shift, ctrl+alt, ctrl+shift, alt+shift.

###catch dispatcher[.event.eventType].where(condition ( Event ) )

Kind of simple “query” syntax for building conditional levels in events handling.

[Flow] 
public function eventsFlowTest() : void { 
 catch stage.event<KeyboardEvent.KEY_DOWN>.where{e => e.ctrlKey} //  key pressed with ctrl modifier
}

###event type

Custom type designed for event subscription. Is returned by the catch expression. See also Catch expression reference.

[Flow] 
public function flow() : void { 

 // way 1 
 var e : event<KeyboardEvent.KEY_DOWN> = catch stage.event<KeyboardEvent.KEY_DOWN>; 
  
 if (e.ctrlKey) { 
   trace "e: " + e; // trace the event information if Ctrl key is pressed
 } 
  
 // way 2 (NOT recommended, see more compact syntax below)   
 or { 
   var e1 : event<KeyboardEvent.KEY_DOWN> = catch stage.event<KeyboardEvent.KEY_DOWN>; 
   var e2 : event<MouseEvent.CLICK> = catch stage.event<MouseEvent.CLICK>; 
 } 
  
 if (e1 != null) { 
   // key down 
 } 
 if (e2 != null) { 
   // mouse click 
 } 
  
 // way 3 (recommended)
  
 or { 
   catch stage.event<KeyboardEvent.KEY_DOWN>{ 
     trace event; 
   } 
   catch stage.event<MouseEvent.CLICK>{ 
     trace event; 
   } 
 } 
}

##Conditional Jumps

###exit [ result ]

Stop execution flow and return a result if applicable (see Flow annotation). Can be used with chain concept (see below).

[Flow(result=success, fail)]
public function eventsFlowTest() : void {
  exit success; // returns one of the two possible results
}

###jump label

Conditional jump to the one of declared states (see state reference). Behaves similar to “goto”.

jump start; // jumps to state start

###state label

State declaration (see also jump reference).

state start; // set a new label to jump to

##Composite Events Handling

###and { … }

Set a condition if all the events in a block have occurred.

and { 
  catch stage.event<MouseEvent.MOUSE_UP>; 
  catch stage.event<KeyboardEvent.KEY_UP>; 
} 
trace "mouse and key are not up";

###not { … }

Set a condition if none of the events in a block have occurred.

not { 
  catch stage.event<MouseEvent.MOUSE_DOWN>; 
  catch stage.event<KeyboardEvent.KEY_DOWN>; 
} 
trace "mouse and key are down";

###or { … }

Set a condition if at least one of the events in a block have occurred.

or {
  catch answerButton.event
<MouseEvent.CLICK> 
{ 
// TODO: some code here 
}
  catch giveUpButton.event
<MouseEvent.CLICK>
{ 
// TODO: some code here 
}
}

###composite { … }

A wrapper for conditions blocks to handle with composite events. If you have a single and/not/or conditions block, you may skip this wrapper to make your code more concise. (See also and, not and or references).

composite { 
  and { 
    catch stage.event<MouseEvent.MOUSE_DOWN>; 
    catch stage.event<KeyboardEvent.KEY_DOWN>;
  } 
  not { 
    catch stage.event<MouseEvent.MOUSE_UP>; 
    catch stage.event<KeyboardEvent.KEY_UP>; 
  } 
} 
trace "mouse and key are down and not up";

##Time Concepts

###timeout time

Pause the execution flow for a specified number of milliseconds.

timeout 10000; // pause for 10 sec.

###do … expire( time ) …

Set a time limit for waiting an event or event block.

do {
  // wait for something here
  catch answerButton.event<MouseEvent.CLICK> 
} expire (60000) { 
  // give up after a minute and exit
  exit giveup;
}

##Chain Concepts

###result reference

Flow method result reference expression, that gets all possible results from the annotation.

[Flow]
public function flow1() : void {
  var result : result<Main.flow2> = chain flow2();
  switch (result) { 
    case result<+.flow2>.success :
      // trace "success" on success in flow2()
      break;
  }
}

/**                               
 * method has two possible results
 */
[Flow(result=success, fail)]
public function flow2() : void {
// some action here
} 

###result type

Custom type to store result of a flow method. See also Flow(result=...) reference.

[Flow] 
public function simpleFlowMethod() : void { 
  var v : result<+.methodWithResult> = chain methodWithResult(); // get result of methodWithResult()
}

[Flow(result=success, fail)] 
public function methodWithResult() : void { 
  exit success; 
}

###chain flowMethod

Expression for binding a few different flow methods in a “chain” (i.e. waiting for another flow method result). In the sample code chain expression is used to get the result from the flow2() method. Please note, that the flow1() method uses a variable of a special type result which is described in the result type reference.

[Flow]
public function flow1() : void { 
  var result : result<Main.flow2> = chain flow2(); //wait for success or fail
  switch (result) { 
    case result<+.flow2>.success : // trace "success" on success in flow2()
      trace "success"
      break;
    case result<+.flow2>.fail :	// trace "fail" on fail in flow2()
      trace "fail";
      break;
  } 
}

/**                               
 * method has two possible results
 * success when key is pressed, fail when mouse is down
 */                               
[Flow(result=success, fail)]
public function flow2() : void {
 or { 
   catch stage.event<KeyboardEvent.KEY_DOWN>{ 
     exit success; // this will be got by result variable in flow1()
   } 
   catch stage.event<MouseEvent.MOUSE_DOWN>{ 
     exit fail; // this will be got by result variable in flow1()
   } 
 } 
}