From 779228cda998943a04c125e6bfc3b501465fb5a2 Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Mon, 16 May 2016 01:16:48 +0300
Subject: [PATCH] cleanup and docs...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 ui (gen4)/features/ui.js |  3 +-
 ui (gen4)/lib/actions.js | 95 +++++++++++++++++++++++++++-------------
 2 files changed, 65 insertions(+), 33 deletions(-)

diff --git a/ui (gen4)/features/ui.js b/ui (gen4)/features/ui.js
index 8f2d9346..520069f8 100755
--- a/ui (gen4)/features/ui.js	
+++ b/ui (gen4)/features/ui.js	
@@ -1820,7 +1820,7 @@ var ControlActions = actions.Actions({
 			// Not for direct use.
 		})],
 
-	// XXX this is really slow on IE...
+	// XXX this is really slow/buggy on IE and odd on FF...
 	toggleRibbonPanHandling: ['Interface/Toggle ribbon pan handling',
 		toggler.Toggler(null,
 			function(){ 
@@ -1916,7 +1916,6 @@ var ControlActions = actions.Actions({
 
 							// when done...
 							if(g.isFinal){
-
 								var central = that.ribbons.getImageByPosition('center', r)
 
 								// check if central if off screen, if yes, 
diff --git a/ui (gen4)/lib/actions.js b/ui (gen4)/lib/actions.js
index 8eeb3573..26e7e141 100755
--- a/ui (gen4)/lib/actions.js	
+++ b/ui (gen4)/lib/actions.js	
@@ -79,10 +79,13 @@ var object = require('lib/object')
 //
 //
 //
-// The action system provides these components:
+// The action system main protocols:
 //
 // 1) Documentation generation and introspection (MetaActions)
 //
+// 		<action>.toString()
+// 				-> code of original action function
+// 	
 // 		<action-set>.getDoc()
 // 		<action-set>.getDoc(<action-name>[, ..])
 // 				-> dict of action-name, doc
@@ -95,7 +98,7 @@ var object = require('lib/object')
 //
 // 		<action-set>.length
 // 				-> number of actions
-// 	
+//
 //
 // 2) Event-like callbacks for actions (MetaActions, Action)
 //
@@ -128,7 +131,31 @@ var object = require('lib/object')
 //		referenced and called from any object and still chain correctly.
 //
 //
-// 4) A mechanism to chain/wrap actions or an action and a function.
+//
+// Secondary action protocols:
+//
+// 1) A mechanism to manually call the pre/post stages of an action
+// 
+// 		Pre phase...
+// 		 <action>.pre(<context>)
+// 		 <action>.pre(<context>, [<arg>, ..])
+// 			-> <call-data>
+//
+// 		Post phase...
+// 		 <action>.post(<context>, <call-data>)
+// 			-> <result>
+//
+// 	This is internally used to implement the action call as well as the
+// 	chaining callbacks (see below).
+//
+// 	All action protocol details apply.
+//
+// 	NOTE: there is not reliable way to call the post phase without first
+// 		calling the pre phase due to how the pre phase is defined (i.e.
+// 		pre phase functions can return post phase functions).
+//
+//
+// 2) A mechanism to chain/wrap actions or an action and a function.
 // 	This enables us to call a callback or another action (inner) between 
 // 	the root action's (outer) pre and post stages.
 //
@@ -183,7 +210,7 @@ var object = require('lib/object')
 //		really necessary.
 //
 //
-// 5) .__call__ action / handler
+// 3) .__call__ action / handler
 // 	This action if defined is called for every action called. It behaves
 // 	like any other action but with a fixed signature, it always receives 
 // 	the action name as first argument and a list of action arguments as
@@ -366,33 +393,6 @@ function Action(name, doc, ldoc, func){
 // this will make action instances behave like real functions...
 Action.prototype.__proto__ = Function
 
-// XXX revise the structure....
-// 		...is it a better idea to define these in an object and assign that???
-Action.prototype.chainApply = function(context, inner, args){
-	args = [].slice.call(args || [])
-	var res = context
-	var outer = this.name
-
-	var data = this.pre(context, args)
-
-	// call the inner action/function if preset....
-	if(inner){
-		//res = inner instanceof Function ? 
-		inner instanceof Function ? 
-				inner.call(context, args)
-			: inner instanceof Array && inner.length > 0 ? 
-				context[inner.pop()].chainCall(context, inner, args)
-			: typeof(inner) == typeof('str') ?
-				context[inner].chainCall(context, null, args)
-			: null
-	}
-
-	return this.post(context, data)
-}
-Action.prototype.chainCall = function(context, inner){
-	return this.chainApply(context, inner, args2array(arguments).slice(2))
-}
-
 // The pre/post stage runners...
 //
 // 	.pre(context, args)	
@@ -401,6 +401,9 @@ Action.prototype.chainCall = function(context, inner){
 // 	.post(context, data)
 // 		-> result
 //
+// XXX revise the structure....
+// 		...is it a better idea to define action methods in an object 
+// 		and assign that???
 Action.prototype.pre = function(context, args){
 	args = args || []
 
@@ -515,6 +518,36 @@ Action.prototype.post = function(context, data){
 	return res
 }
 
+// Chaining...
+Action.prototype.chainApply = function(context, inner, args){
+	args = [].slice.call(args || [])
+	var res = context
+	var outer = this.name
+
+	var data = this.pre(context, args)
+
+	// call the inner action/function if preset....
+	if(inner){
+		//res = inner instanceof Function ? 
+		inner instanceof Function ? 
+				inner.call(context, args)
+			: inner instanceof Array && inner.length > 0 ? 
+				context[inner.pop()].chainCall(context, inner, args)
+			: typeof(inner) == typeof('str') ?
+				context[inner].chainCall(context, null, args)
+			: null
+	}
+
+	return this.post(context, data)
+}
+Action.prototype.chainCall = function(context, inner){
+	return this.chainApply(context, inner, args2array(arguments).slice(2))
+}
+
+
+
+//---------------------------------------------------------------------
+
 // A base action-set object...
 //
 // This will define a set of action-set specific methods and helpers.