Appendix C: Customization

Introduction

As illustrated throughout this document and the on-line help files, keys that are pressed are actually translated into sequences of Ce commands. Furthermore, you can customize those command sequences to suit your own editing style and purposes.

When you ran "ce_init", it created in your home directory a file called ".Cekeys". (If you did not run "ce_init", please refer to Chapter 1, Editing Basics, which describes the initialization process.)

".Cekeys" contains two sets of key definitions:

• One set assigns definitions only to keys that are common to all keyboards (F1, F2, ..., F8, Escape, Tab, Backspace, Delete, Ctrl, Shift, and Return). The advantage of such a key definition set is that you can use Ce on several different platforms and get the same behavior from the keys.
• Another set assigns definitions to keys that are special for the keyboard you are using. For example, the Sun Type 5 keyboard contains keys that are labeled "Cut", "Copy", "Paste", and "Undo", among others. Since you indicate to "ce_init" the type of workstation you are using, it can copy those extended key definitions into your ".Cekeys" file so that those special keys function properly while using Ce.

Key Names

Each key has a name, also known as a "keysym" in X terminology. When you create your own key definitions, you will need to know the names of the keys to which you are assigning those definitions. You should be aware that key names vary from system to system, even if those names refer to the same key. For example, the traditional "return" key might be known as "Return" on one system and "Enter" on another system. Ce provides the "kk" command to find the names of keys on the system you are using. You can also execute the command "xmodmap -pk" from a shell to get a listing of the keysyms currently recognized by the X server.

Key Modifiers

A pressed key can be modified by simultaneously pressing Shift, Ctrl, Mod1, Mod2, Mod3, or Mod4 keys. Modified key presses are treated distinctly from unmodified key presses. For example, Ce will treat "<Shift> F8" differently than "F8". You should also realize that modifier keys can be combined, so that "<Shift><Ctrl> F8" is another distinct key press. The epitome of such key presses is when you press all six modifier keys along with a non-modifier key, e.g., "Mod1/Mod2/Mod3/Mod4<Shift><Ctrl> F8".

Since the X environment is very flexible, you can define any key on your keyboard to mean "Shift" or "Ctrl". However, "Shift" and "Ctrl" are universally assigned to the physical keys with those labels. The remaining four modifier keys (Mod1, Mod2, Mod3, Mod4) are not assigned to keys in a way that is consistent across platforms. You should run the command "/usr/bin/X11/xmodmap" to learn which keys on your keyboard serve as the Mod1, Mod2, Mod3, and Mod4 keys.

Modified Key Names

The key name is required when assigning a Ce command sequence to a key. If you want to assign a command sequence to a modified key, you need to add prefixes and/or suffixes to the name to arrive at a modified name. For example, if the key name for the function key F8 is "F8", the correct name for the F8 key modified by Shift is "F8S". Table 8.1 lists the prefixes and suffixes used to modify key names:

Table C-1. Key Name Prefixes and Suffixes

Table C-2. Key Name Prefix and Suffix Examples

The order of appearance of the prefix modifier symbols is not important. What is important is that you press all of the modifier keys and hold them immediately prior to pressing the primary key.

The terms Mod1, Mod2, etc. can be confusing. These are the names the "X" documentation uses. In general, Mod1 is the <Alt> key. This is pretty consistent across vendors and keyboards. On Sun, the diamond key is usually Mod4 although on some older releases of SunOS, Alt is mod4 and the diamond key is Mod1. The Ce "kk" command can be used to sort this out for your keyboard. See the online KK command help and the description below for more information.

The "kd" (Key Definition) Command

You use the "kd" command to assign a command sequence to a key. Your ".Cekeys" file is simply a series of "kd" commands that are processed when you start Ce. The following lines are taken directly from a typical ".Cekeys" file:

The basic syntax for the "kd" command is "kd <name> <commands> ke", where <name> is an unmodified or modified key name according to the rules in the previous section, and where <command> is a valid sequence of Ce commands, separated by semicolons.

If you want a key definition to be in effect every time you run Ce, you should place the definition in your ".Cekeys" file. Ce processes the key definitions in that file before handling events from your keyboard or mouse.

You can also issue "kd" commands in the command window at the "Command: " prompt during your edit session. Such key definitions, however, apply only to the current session and are not saved across edit sessions.

The "kk" (Key Key) Command

The Ce "kk" command is used to determine the name you would use in a key definition for a particular key or combination of keys. After a "kk" is executed the keysym name corresponding to the next key pressed is displayed in Ce's output window. If two "kk" commands are stacked, as in "kk;kk", the next two keystrokes are displayed. One of these may be the pressing of a modifier key.

For example: In the Ce command window type "kk;kk" and press "Return". Press and hold the "Control" key. The Ce output message window should display something like "CONTROL_L". Then press the "a" key. The Ce output message window should now display "^a". This value, "^a", is what you would use in a key definition to define the action when the sequence Control a is pressed.

The "kd" command requires a keysym to bind a definition to a specific key or key combination. By default, on a Sun keyboard, the key with the word "Props" on it executes a "kk" command and Shift Props executes "kk;kk".

NOTES:

1. The window manager that you use (OSF/Motif, Open Windows, ...) can reserve certain keys which are then unavailable for use by applications such as ce. If you find that one of your key definitions is not functioning as expected, consult your window manager documentation to see if you are using such a reserved key or key combination. You can also use the "kk" command to determine this. Execute a "kk" (or "kk;kk") and then press the key or key combination in question. If you do not get the messages in the Ce output window, then Ce did not receive this keystroke. Thus the window manager is intercepting it.

2. If the environment variable "CE_FULL_KK" is set, "kk" will display the hardware keycode and the default es string following the keysym. In the "Command:" window execute: "env CE_FULL_KK=1".

3. The key mapping on HP/UX keyboards uses the alt key to map to many of the multi-national keys. For example, the "<Alt> h" key combination usually maps to the Japanese Yen symbol. On an IBM RS6000, with the Alt key pressed down, you would use "*h" to define "h", on an HP you would use "*yen".

The alias Command

The alias command has a syntax almost identical to the key definition "kd" command. The word "alias" replaces "kd" and the name of the alias replaces the name of the key. The "alias" command allows the user to create additional Ce commands which may be used in key definitions or typed at the command line. The three forms of the "alias" command are as follows:

NOTE: "name" is a 1 to 8 character alias name composed of all alphabetic characters. It must not be the same as any built in Ce command.

"<def>" is a string of Ce commands separated by semicolons. It is parsed in exactly the same way as a "kd" command. It may contain prompts just like key definitions. In addition, it may contain positional symbolic parameters ($1, $2, etc.) which will be substituted in when the alias is invoked. That is "$1" refers to the first word following the alias command, "$2" refers to the second word, and so forth.

In addition, the constructs "$*" and "$@" are supported. The "$*" construct resolves during alias expansion to all the supplied arguments with a space between each argument. The "$@" construct resolves to all the supplied arguments with a set of double quotes (") around each argument and a space between each argument.

Alias'ed names may be used in key definitions. However, the alias must already be defined and the alias is expanded during the processing of the key definition. Thus, aliases which use symbolic substitution need to have their parameters specified within the key definition. Examples are provided below:

alias help cv $CEHELPDIR/$1.hlp ke
This alias creates a command named help which opens a cv window on the help file named as the first and only argument to the command.

alias quit wc -q ke
This alias creates a command named quit which closes the a Ce session without saving any changes.

alias print 1,$! -c -m lp k
This alias creates a command named print which will print the entire file by piping it into the system "lp" command.

The mi (menu item) command

The "mi" command is used to set, display, or erase a menu item in the named pull down menu. Changes made via the "mi" command are propagated to all Ce windows on the current display. Note that the "lmi" (Local Menu Item) command behaves just like the "mi" command except that the changes are local to the window they are executed in. The three forms of the "mi" command are as follows:

mi <pdname>/<line>
Display in Ce's output window the definition currently assigned to the specified menu item.

mi <pdname>/<line> 'title'<ce;cmd;list> ke
Add or replace a menu item with a new definition. "<ce;cmd;list>" is parsed at definition time for validity, and if Ce detects a syntax error in the definition, it is rejected. Using the value "$" for the line number causes Ce to find the next available line in the menu item and use that line. This includes items previously erased. If a menu item in the named pull down exists with the same title, the menu item replaces this item no matter what was specified in the line.

mi <pdname>/<line> ke
Erases a menu item. The line is not displayed but exists internally. Using "-1" as the value for line causes all the menu items in that pulldown to be erased.

Parameters

<pdname>
This is the name of the pulldown to be modified or added to. It is 1 to 8 alphameric characters. You can make up new pulldown names and add Menu Items to them. They can then be chained to existing pulldowns or activated from a key definition "kd", command file "cmdf" or from the "Command:" prompt. The "pd" (Pull Down) command causes a pulldown to be activated. To add menu items to the default pulldowns, you need to know their names. From left to right, the pull down names are: File, Edit, Modes, Macro, and Help. Their names are the same as their title in root pulldown whose name is "Menubar". Note that in the processing of the root pulldown Menubar, item "Help" is treated as a special case.

<line>
This is the zero based line number of the menu item to examine, update, or add. When you add lines to an existing pulldown, make sure you do not skip any intermediate line numbers. The lines, starting at zero, are checked until one which is not found is encountered. This is taken to be the end of the list. Thus a hole in the numbering sequence terminates the list.

<title>
This is the string to be placed into menu item line. It is what is displayed on that line in the pull down. The string can be enclosed in single, double, or reverse quotes. If a menu item in the named pull down exists with the same title, the menu item replaces this item no matter what was specified in the line.

<ce;cmd;list>
This is the list of Ce commands separated by colons to be executed under this menu item. It is parsed just like a key definition. For an arbitrary list of Ce commands, the commands are executed when a the mouse button is released in the pulldown menu item corresponding to this list. Holding the left mouse button down, and dragging to a menu item or clicking a menu item produce the same result.

The exception to the button release rule is when the Ce command list contains a single "pd" command. In this case, the pulldown command is executed when the mouse button is pressed or when the mouse button is held down and the mouse is dragged into the pulldown menu item. This exception gives the pulldowns the expected behavior. A side effect of this is that you are not allowed to mix a "pd" command in the command list with anything else. The Ce command list can either contain a single "pd" command or a list of other Ce commands. Using cmdf, aliases, eval, or other techniques it is possible to hide the "pd" command from the "mi" check which disallows this mix. The effect of this is that the pulldown will appear on the button release and the corresponding menu item will not be marked with an arrow to show it is a cascading pulldown. Do this sort of thing at your own risk

ke
This is the terminator for the command list. If you create pulldowns which add key definitions, aliases, or other menu items, use the same rules for escaping "ke's" as when you nest key definitions.

Examples

To Replace an existing pulldown menu item:

The default menu item for doing text flow is defined by:
mi Edit/5 'Text Flow'tf ke

This reads, "Define line 5 of the Edit pulldown as displaying the string "Text Flow" and when selected, execute the "tf" Ce command." We would prefer that to use the text flow options which do blank precompression "-p" and right justification "-b". We would also like to use default left and right boundaries of 9 and 80 if the user does not do a rectangular mark over the region to be text flowed. Executing the following line will implement this change. Adding the line to your ".Cekeys" file will make the change permanent.

mi Edit/5 'Text Flow'tf -p -b -l 9 -r 80 ke

To add a cascading pulldown:

By default, the Pulldown for Macro is empty. We wish to add a cascading pulldown as the first menu item (item 0) which will perform some local functions.

mi Macro/0 'My Stuff1'pd Mine ke
mi Mine/0 'Find All'tmw;1,$! -c -m grep -c \\&'Find: ' ke
mi Mine/1 'Print File'tmw;1,$! -c -m lp ke
mi Mine/2 'Print Region'! -c -m lp ke
mi Mine/3 'Count Words'! -c -m wc -w ke
mi Mine/4 'Sort Region'! sort ke