This chapter formally describes the semantics of executing actions and operations and escaping to operations and groups. It assumes that you have read the Must Read First section about Meta Keys, See section Must Read First. Recall the notations for Meta Keys: KO KG and KC. We use those notations here and describe their semantics. Normally when a user types KA, Agroups prompts for an entry selection from the current group. The Meta Keys allow an escape from this.
The Agroups user executes actions and operations by entering
where <something> can be any combination of meta keys, group and entry selections but must always terminate with an entry action selection or operation. This is not completely true since at any time during the entry of <something> the user can abort with a C-g.
You can also supply a prefix argument that will be interpreted by various actions in different ways when an action specializes on an operation such as a action specific editor or when an action entry is executed as follows
<prefix argument> KA <something>
And each action described in this manual will state whether it can take a prefix argument and what it means in that context. For example if we had a group action that inserts some text, See section Insert Text Action, and lets say, "i" was the accelerator keys for that action. Then the following
ESC 10 KA i
would insert that text into the current buffer 10 times by virtue of the prefix argument of 10. An example of a prefix argument where an action specializes on an operation is the keyboard macro action that specializes on the edit operation, See section Keyboard Macro Action, where it passes its prefix argument to the standard Emacs keyboard macro editor.
The <something> after the KA above by default is to select and execute an action entry in the current group. The philosophy of Agroups was to make this the least effort since the majority of time spent in an activity flow is that of executing actions in the current group. All others like operations and cross group actions are done by escaping which are described in the following sections, See section Operation Escaping, See section Group Escaping.
KO allows a user to escape from selecting an entry to selecting an Agroups operation. As an example you can display the entries of the current group with
KA KO d
After entering KO another entry of KO will also show the list of all operations above but will still keep prompting for an operation. So
KA KO KO d
will do the same as "KA KO d" but will first display the list of operations in the Agroups buffer as a reminder. The third and subsequent repeat of KO will scroll the Agroups buffer to make it easy to find the operation you are looking for.
You can also see a list of all operations with the operation
View agroups Version and operations (keys: v v)
This operation also shows the version of Agroups that is being used.
KG allows a user to escape from selecting an entry in the current group to one operation or entry selection of another group other than the current group. For example if the current group is g1 then
KA KG g2 e1
will select and execute entry e1 in group g2. This is useful when you don't want to switch contexts but need to execute an operation or entry in some other group just once. Similarly, if you wanted to display a list of the entries in group g2 you could do that with
KA KG g2 KO d
Similar to KO a second repeated entry of KG will display all groups as a reminder before the user types the desired operation or selection. So instead of the above if you type
KA KG KG g2 KO d
You will get a list of all top level groups displayed before you select the d operation. You can also see a list of all top level groups with the operation
Display top level groups (keys: D)
Also similar to KO, the third and subsequent repeated entries of KG will scroll the display of all top level groups.
At all times it is possible to use completion instead of accelerator keys. This applies to selecting entries, groups, and operations. Completion is used to select one of these based on the id component of an entry or operation. That is, when you use completion to select then it overrides using accelerator keys. In fact if the user does not want to use accelerator keys at all he can set the options
and only use completion, See section Setting Options. This is not recommended since it requires more typing, but some people may prefer to do this. A nice feature of Agroups is that even when you use accelerator keys you can still use completion when it's needed. This is done in one of two ways.
First, if the user starts typing and there are no accelerator keys that match what the user has typed so far then completion mode will start automatically with the keys typed so far as a beginning of an id to use completion on. For example if we type
KA c a t
and there are only entries with keys "ca1" and "ca2" then by virtue of the "t", completion mode will initiate. So for example if there is an entry with id "cats and dogs" it could easily be selected with completion at this point.
Second, a user can always force completion by entering KC. For example
KA KC cats SPC
might be used to select the entry with the "cats and dogs" id. As mentioned in other parts of this document you can change even the meta key bindings, but it is strongly advised that you do not change the binding of KC which is by default SPC. This is because SPC is used for the standard Emacs word by word completion.
Agroups makes no attempts to automatically force accelerator keys to be unambiguous for entries of a group or top level groups. If the user intentionally defines two entries with the same accelerator keys then he might need to use completion to get himself out of trouble. However Agroups does detect ambiguous accelerator keys when defined or moved and gives the user a chance to resolve the ambiguous keys.
As an example of accelerator keys resolution suppose that we have an entry in a group called "junk test" and with accelerator keys "jt" and then we create a new entry their called "junk text" but we make the mistake of assigning to the new entry the accelerator keys "jt" as well. Agroups would recognize the ambiguous situation and give us a chance to resolve the situation with the following prompt
This entry's accelerator keys (keys: j t) are ambiguous with other entry: junk test (keys: j t) The following resolutions are possible: 0 = Allow both entries to have ambiguous keys 1 = Try entering keys for this entry again 2 = Change other entry's keys 3 = Replace other entry with this entry
This gives us the opportunity to either allow the ambiguous situation, reenter this entry's keys, change the other entry's keys, or replace the other entry with the new entry. In the case of the replace, resolution 3, the other entry is automatically moved into the zzzap group.
Lets say for the sake of illustration that at this point we choose resolution 0 so that both entries will have accelerator keys of "jt". Then we can still access the entries for some operation like editing using completion. But we can also access one of the entries by its accelerator keys. The rule is that when there are ambiguous keys the first entry in a displayed entry list will be the one selected.
One should notice at this point that since there is no terminator required for accelerator key typing that two accelerator keys don't have to be the same length to be ambiguous. In the above example two entry's accelerator keys of "jt" and "jtx" would still be ambiguous.
By default, accelerator keys resolution does not happen when the target
group is the zzzap group. If don't want this you can set the
resolve-keys-to-zzzap-target option, See section Setting Options.
Go to the first, previous, next, last section, table of contents.