Here are some things that users can do to change the behavior of Agroups. It is possible to set options for various preferences. You can set the accelerator keys for all given predefined operations and actions to suit your typing. And finally for what ever reason you may want, you can create your own styled new Agroups command.
You can set various kinds of options with the operations
Set Options (keys: s o) Set Options back to defaults (keys: s O)
When you select the first operation above, Agroups prompts you to choose an option. The choice is a toggle between "no" and "yes", so each time you choose a particular option it will toggle back and forth between "no" and "yes". All choices default to "no". When you select the second operation above it sets all options back to the predefined "no" defaults. When you make the choice it is persistence between Emacs sessions. These options have the following meanings:
show-groups-when-change-current: When you change
the current group Agroups notifies you in the minibuffer. If you also
want to automatically see a list of top level groups (like the "Display
all groups" operation) every time you change the current group,
toggle this option to "yes".
show-matching-action-entries: Some actions will
ask you if you want to update existing entries if there are entries in
the current group of the same kind. For example the Point Actions do
this, See section Point Actions. If such existing entries exist they will
prompt in the minibuffer
Do you want to update existing? (y or n)
If in addition to this prompt you also want to see a list of such existing entries each time, then set this option to "yes".
numeric-choice-always-get-return: Many menus ask
the user to type a number to select a choice. If the number of menu
choices is 10 or less then just hitting the keys 0-9 will cause the
choice to take effect. When more than 10 choices a RET is required
after the number is entered. If the user prefers to always have to
consistently enter a RET after the number then set this option to "yes".
Note that in all cased and with this option or not, hitting a RET alone will always select the default choice.
resolve-keys-to-zzzap-target: Normally when
moving entries to the zzzap group accelerator keys resolution does not
take place, See section Ambiguous Keys Resolution. If If don't want this you
can set this option to "yes".
dont-ask-for-new-group-keys: Normally when creating a new entry or
group the user is asked for accelerator keys for that entry or group.
Some users may prefer to use only completion for selecting an
entry or group. If this is their choice it may be annoying to have to
respond to this "asking for accelerator keys" every time. If you set
these options to "yes",
dont-ask-for-new-entry-keys for entries
dont-ask-for-new-group-keys for groups, then Agroups will not
ask. The default on creation of an entry or group then will be no
accelerator keys. When this is done accelerator keys can still be added
by editing entries.
Accelerator keys help speed up executing actions and part of the philosophy of Agroups is to do what ever it can to ease executing actions. But part of this concept is the how well predefined accelerator keys combine with user defined accelerator keys. So Agroups adopts the same philosophy of Emacs to allow the user to completely customize all keys bindings.
You can change any existing predefined keys with the operation
Set predefined Keys (keys: s k)
When you select this operation you are asked which keys to change with the prompt
The following type of changes on predefined keys are possible: The Clear types require a reload of agroups to take effect. 0 = Change Meta key 1 = Remap Operation key 2 = Remap Predefined Action key 3 = Clear all Operation key Remaps 4 = Clear all Predefined Action key Remaps
Choosing "Change Meta key" allows you to persistently change the default Meta key bindings that we refer to in this document as KO, KG, and KC and explain in an earlier section, See section Must Read First. After choosing "Change Meta key" you get prompted with the choices
Meta key choices: 0 = Select an operation 1 = Group selection operations 2 = Enter completion mode
which correspond to KO KG KC respectively. There are many reasons why you might want to change these, but one may be that if you define KA as a control key sequence it may be convenient to also have KO and KG bound to something close to the control key sequence. In the Must Read First section we give an example of binding KA to "\C-z\C-a". In this case it might be convenient then to bind KO to "\C-z" and KG to \C-a" for example. It is not recommended to change the KC, completion, binding which defaults to SPC since the Emacs default for word by word completion is bound to SPC and it combines nicely when using completion in Agroups.
The "Remap Operation key" and "Remap Predefined Action key" choices in the "changes on predefined keys" menu above work exactly the same except that the first allows you to remap keys from the collection of Operations and the second allows you to remap keys from the collection of Predefined Actions. These work by first asking you to select an operation (or action) which you can do by using accelerator keys or by completion. Then they ask for a keys to remap to.
Again when you make these mappings they are saved persistently for you so that the next time you run Emacs you will get the new key bindings. The "Clear all Operation key Remaps" and "Clear all Predefined Action key Remaps" choices allow you to undo all of one of the two remaps described above respectively. It does this by removing all key mappings for that collection in your Agroups save file so that you can start over with the default predefined key bindings.
Much like the
agroups command that we bound to "\C-z\C-a" as an
example in an earlier section, See section Must Read First, it is possible to
create new Agroups commands. This can be done with the
agroups-command macro. In fact the
agroups command itself
is created with this macro. The form of this macro is
(agroups-command <command symbol> <save file> &optional <existing command symbol> <prefix keys>)
where <command symbol> is the function symbol that you want your new Agroups command called and <save file> is a string representing the new Agroups save file. The optional arguments allow creating an Agroups command that shares a piece of an existing Agroups command where <existing command symbol> is the existing command function symbol and <prefix keys> is a string of accelerator keys that can take you into the existing piece of the existing Agroups command group structure. When you create a shared command in this way you should use the same save file that the existing command uses.
First, lets take the simpler example. Suppose that we want to create a
new Agroups command called
agroups-1. The default
command save file is "~/.agroups" so lets call our new save file
"~/.agroups-1". We would then create the new Agroups command with
(agroups-command agroups-1 "~/.agroups-1")
We should then be able to execute the new Agroups command with "M-x agroups-1" or bind agroups-1 to some keys in the standard Emacs way.
Second, lets take a shared example using a prefix. Using the prefix is equivalent to "KA <prefix keys>" of the existing command. Which allows you to bind any operation, entry or group of the existing Agroups command to your new Agroups command. In our introduction examples we showed how Agroups gives you a staring group called global that by default has accelerator keys ".". One useful thing to do is to create a new Agroups command that shares the global group with your existing Agroups command. We can do this easily with
(agroups-command agroups-g agroups-file agroups "\C-a.")
After doing this we will have a new command function
Since we want to share the existing command
group we want to also use the same Agroups save file. Since the
default save for
agroups is stored in the variable
agroups-file we want to use that for the <save file> argument
instead of a string since if we change this variable for the existing
command we want the shared command to change as well. We next give
the <existing command symbol> argument as
agroups which is the
agroups command that we have been using in this document that
we are going to share. And finally the <prefix keys> argument which
is "\C-a." assumes that we changed the KG meta key in this chapter
from the default of TAB to C-a, so that "C-a." would take us into the
global group. Finally to complete this idea, since in our
Introduction examples we bound
bind this new command to
(global-set-key "\C-za" 'agroups-g)
Now, if you followed our key binding example including the change of key bindings example in this chapter, then typing
would now be equivalent to typing
C-z C-a C-a .
Go to the first, previous, next, last section, table of contents.