Go to the first, previous, next, last section, table of contents.

Customizing Agroups Environment

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.

Setting Options

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:

Option: 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".

Option: 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".

Option: 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.

Option: 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".

Options: dont-ask-for-new-entry-keys 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 and 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.

Changing Predefined Keys

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.

Creating New Agroups Commands

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 agroups 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 agroups-g. Since we want to share the existing command agroups global 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 agroups to C-zC-a lets bind this new command to C-za

(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

C-z a

would now be equivalent to typing

C-z C-a C-a .

Go to the first, previous, next, last section, table of contents.