CHANGED: bindings groups documentation

Author: nkh

documentation/mdbook_asciio/src/config/binding_format.md

@@ -118,7 +118,72 @@ register_action_handlers
 'group_other_group_name' => GROUP ( ...), # note that 'group_' is needed in the declaration of groups referred to by USE_GROUP
 ```
 
-#### Macros
+### Navigating groups programatically
+
+There are two possibilities:
+
+- run_actions
+- run_actions_by name
+
+*run_actions* runs actions in the current binding (it is used by *Asciio* to handle keyboard events).
+
+*run_actions_by_name* executes one of more named functions (with optional arguments); the functions are registered in the default config.
+
+*Asciio* looks up keyboard events and run the correxponding function in the current binding group. 
+
+Groups are also registered functions, functions that manipulates the current binding group.
+
+We can programmatically manipulate the current bindings but it's much easier to define a group of bindings that we can make the active binding group; that's exactly what GROUP does.
+
+To change the current keyboard bindings, we just need to run the right GROUP. 
+
+```perl
+$self->run_actions_by_name("the GROUP name") ;
+```
+
+That's available anywhere but the right way to do it is in the config so we get a keyboard driven flow rather than a code driven flow with if-then-else.
+
+The configuration below is to get in group 'x' from group 'Insert ->' and back.
+
+Two solutions are presented, the difference is explained below.
+
+Note: the normal behavior when exiting a GROUP, is to reset to the default keyboard bindings. 
+
+```perl
+
+'Insert ->' => GROUP
+	(
+	SHORTCUTS => '000-i',
+	'X ->'    => ['000-x', USE_GROUP('x')] ,
+	),
+
+	'group_x' => GROUP
+		(
+		SHORTCUTS    => 'group_x',
+		ESCAPE_KEYS  => '000-Escape',
+		        
+		# solution 1
+		ESCAPE_GROUP => sub { $_[0]->run_actions_by_name("Insert ->") ;},
+		
+		#solution 2
+		'return to Insert'   => ['000-Escape', sub{ $_[0]->run_actions_by_name("Insert ->") ; }, undef , {HIDE => 1}], 
+		),
+```
+
+
+- if you decide to use *solution 1*, the code for *solution 2* is not needed
+- if you decide to use *solution 2*, the code for *solution 1* is not needed
+- you can use *solution 1* and *solution 2* together but in this case there is no gain
+
+Difference:
+- *solution 1* will change the current bindings but the bindings help
+- *solution 2* will change the current bindings and display the bindings help
+
+Note:
+- we stop capturing keyboard input to GROUP(X) bindings because both solutions use '000-Escape'.
+- we're not forced to jump "back" to the previous group, we could jump anywhere, that's what USE_GROUP does.
+
+### Macros
 
 Macros allows ***Single Action Definition*** to run multiple commands.