X Window System User's Guide for X11 R3 and R4 of the X Window System

11

Setup Clients

This chapter discusses how to set up certain features of your working environment, using the following clients:

xset	To set certain characteristics of the keyboard, pointer and display.
xsetroot	To set root window characteristics.
xmodmap	To change pointer and modifier key mappings.

xset: Setting Display and Keyboard Preferences

The xset client allows you to set an assortment of user preference options for the display and keyboard. Some of these are followed by on or off to set or unset the option. Note that xset is inconsistent in its use of a dash (–)as an option flag. Some options use a preceding “–” to indicate that a feature be disabled; this can be confusing at first to users accustomed to seeing “–” as an introductory symbol on all options.

Although xset can be run any time, it is suggested that you run it at startup. These settings reset to the default values when you log out. Not all X implementations are guaranteed to honor all of these options.

Keyboard Bell

The b option controls bell volume (as a percentage of its maximum), pitch (in hertz), and duration (in milliseconds). It accepts up to three numerical parameters:

b volume pitch duration

If no parameters are given, the system defaults are used. If only one parameter is given, the bell volume is set to that value. If two values are listed, the second parameter specifies the bell pitch. If three values are listed, the third one specifies the duration.

For example, the command:

% xset b 70 1000 100

sets the volume of the keyboard bell to 70 percent of the maximum, the pitch to 1000 hertz, and the duration to 100 milliseconds.

Note that bell characteristics vary with different hardware. The X server sets the characteristics of the bell as closely as it can to the user’s specifications.

The b option also accepts the parameters on or off. If you specify xset b on, system defaults for volume, pitch and duration are used.

The bell can also be turned off with the option –b, or by setting the volume parameter to 0 (xset b 0).

Bug Compatibility Mode

Some Release 3 clients were written to work with “features” of the Release 3 server, which could more accurately be called bugs. Many of these bugs have been eliminated in Release 4. In order to allow certain Release 3 clients to work under the Release 4 server, the Release 4 server has a bug compatibility mode that can be enabled using xset. In this mode, the Release 4 server is compatible with Release 3 clients that depended on bugs in the Release 3 server to work properly (most notably the Release 3 version of xterm).

To enable bug compatibility mode, use the command xset bc; to disable it, use the command xset -bc.

Keyclick Volume

The c option sets the volume of the keyboard’s keyclick and takes the form:

c volume

volume can be a value from 0 to 100, indicating a percentage of the maximum volume. For example:

% xset c 75

sets a moderately loud keyclick. The X server sets the volume to the nearest value that the hardware can support.

The c option also accepts the parameters on or off. If you specify xset c on, the system default for volume is used.

The keyclick can also be turned off with the option -c, or by setting the volume parameter to 0 (xset c 0).

On some hardware, a volume of 0 to 50 turns the keyclick off, and a volume of 51 to 100 turns the keyclick on.

Enabling or Disabling Auto-repeat

The r option controls the keyboard’s auto-repeat feature. (Auto-repeat causes a keystroke to be repeated over and over when the key is held down.) Use xset r or xset r on to enable key repeat. Use xset -r or xset r off to disable key repeat. On some keyboards (notably Apollo), only some keys repeat, regardless of the state of this option.

Changing or Rehashing the Font Path

As discussed in Chapter 8, Command Line Options, when a client is to be displayed in a particular font, the server by default looks for the font in three subdirectories of /usr/lib/Xll/fonts: misc, 75dpi, and 100dpi.

The fp (font path) option of xset can be used to change the font path, i.e., to direct the X server to search other directories for fonts called by a client. The option must be followed by a directory or a comma-separated list of directories, as in the following example:

% xset fp /work/andy/fonts,/usr/lib/Xll/newfonts

To restore the default font path, type:

% xset fp default

As discussed in Chapter 8, the fp option with the rehash parameter causes the server to reread the fonts.dir and fonts.alias files in the current font path. You need to do this every time you edit an alias file to make the server aware of the changes.

To make the server aware of aliases, type:

% xset fp rehash

You also have to do this if you add or remove fonts. See Appendix A, System Management, for more information.

Keyboard LEDs

The led option controls the turning on or off of one or all of the keyboard’s LEDs. It accepts the parameters on or off to turn all of the LEDs on or off. A preceding dash also turns all of the LEDs off (-led).

You can also turn individual LEDs on or off by supplying a numerical parameter (a value between 1 and 32) that corresponds to a particular LED. The led option followed by a numerical parameter turns that LED on. The led option preceded by a dash and followed by a numerical parameter turns that LED off. For example:

% xset led 3

would turn LED #3 on, while:

% xset -led 3

would turn LED #3 off.

Note that the particular LED values may refer to different LEDs on different hardware.

Pointer Acceleration

The m (mouse) option controls the rate at which the mouse or pointer moves across the screen. This option takes two parameters: acceleration and threshold. They must be positive integers. (The acceleration can also be written as a numerator/denominator combination separated by a’/’, for example, 5/4.)

The mouse or pointer moves acceleration times as fast when it travels more than the threshold number of pixels in a short time. This way, the mouse can be used for precise alignment when it is moved slowly, yet it can be set to travel across the screen by a flick of the wrist when desired. If only one parameter is given, it is interpreted as the acceleration.

For example, the command:

% xset m 5 10

sets the mouse movement so that if you move the mouse more than ten pixels, the mouse cursor moves five times as many pixels on the screen as you moved the mouse on the pad.

If no parameter or the value default is used, the system defaults will be set

If you want to change the threshold and leave the acceleration unchanged, enter the value default for acceleration.

Screen Saver

X supports a screen saver to blank or randomly change the screen when the system is left unattended for an extended period. This avoids the “burn in” that can occur when the same image is displayed on the screen for a long time. The s (screen saver) option to xset determines how long the server must be inactive before the screen saver is started.

The s option takes two parameters: time and cycle. The screen goes blank if the server has not received any input for the time interval specified by the time parameter. The contents of the screen reappear upon receipt of any input. If the display is not capable of blanking the screen, then the screen is shifted a pixel in a random direction at time intervals set by the cycle parameter. The parameters are specified in seconds.

For example, the command:

% xset s 600

sets the length of time before the screen saver is invoked to 600 seconds (ten minutes).

For a display not capable of blanking the screen, the command:

% xset s 600 10

sets the length of time before the screen saver is invoked to ten minutes and shifts the screen every ten seconds thereafter, until input is received.

The s option also takes the parameters:

default	Resets the screen save option to the default.
blank	Turns on blanking and overrides any previous settings.
noblank	Displays a background pattern rather than blanking the screen; overrides any previous settings.
off	Turns off the screen saver option and overrides any previous settings.
expose	Allows window exposures (the server can discard window contents).
noexpose	Disables screen saver unless the server can regenerate the screens without causing exposure events (i.e., without forcing the applications to regenerate their own windows).

Color Definition

On color displays, every time a client requests a private read/write colorcell, a new color definition is entered in the display’s colonnap. The p option sets one of these colonnap entries even though they are supposed to be private. The parameters are a positive integer identifying a cell in the colormap to be changed, and a color name:

p entry_ number color_ name

The root window colors can be changed on some servers using xsetroot. An error results if the map entry is a read-only color.

For example, the command:

% xset p 3 blue

sets the third cell in the colormap to the color blue, but only if some client has allocated this cell read/write.

The client that allocated the cell is likely to change it again sometime after you try to set it, since this is the usual procedure for allocating a read/write cell.

Help with xset Options

The q option lists the current values of all xset preferences.

xsetroot: Setting Root Window Characteristics

You can use the xsetroot client to tailor the appearance of the background (root) window on a display running X.

The xsetroot client is primarily used to specify the root window pattern: as a plaid-like grid, tiled grey pattern, solid color, or a bitmap. You can also specify foreground and background colors (defaults are black and white), reverse video, and set the shape of the pointer when it’s in the root window.

If no options are specified, or the -def option is specified, xsetroot resets the root window to its default state, a grey mesh pattern, and resets the pointer to the hollow X pointer. The -def option can also be specified with other options; those characteristics that are not set by other options are reset to the defaults.

Although xsetroot can be run any time, it is suggested that you run it from a startup shell script, as described at the end of this chapter. All settings reset to the default values when you log out.

For a complete list of options, see the xsetroot reference page in Part Three of this guide. Not all X implementations are guaranteed to support all of these options. Some of the options may not work on certain hardware devices.

The -help option prints all the xsetroot options to standard output. The options you’ll probably use most frequently are explained in the next section. Since only one type of background pattern can be specified at a time, the -solid, -gray, -grey, -bitmap and -mod options are mutually exclusive.

Setting Root Window Patterns

The default root window pattern is called a “grey mesh.” On most displays, it is fairly dark.

The xsetroot client allows you to specify an alternative grey background with the -grey (or -gray) option. This tiled grey pattern is slightly lighter than the default grey mesh pattern.

The xsetroot client also allows you to create a root window made up of repeated “tiles“ of a particular bitmap, using the option:

-bitmap filename

where filename is the bitmap file to be used as the window pattern.

You can choose any of the bitmaps in the directory /usr/include/Xll/bitmaps or make your own bitmap files using the bitmap client (see Chapter 7, Other Clients).

For example, the command:

% xsetroot -bitmap /uer/andy/gumby -fg red -bg blue

fills the root window with a tiling of the bitmap /usr/andy/gumby (a virtual army of Gumbys!), using the colors red and blue.

The -mod option sets a Plaid-like pattern on the root window. You specify the horizon-tal (x) and vertical (y) dimensions in pixels of each square in the grid. The syntax of the option is:

-mod x y

where the parameters x and y are integers ranging from 1 to 16 (pixels). (Zero and negative numbers are taken as 1.)

The larger the x and y values you specify, the larger (and more visible) each square on the root window grid pattern. Try the command:

% xsetroot -mod 16 16

for the largest possible grid squares. Then test different x and y specifications.

The xsetroot option:

-solid color

sets the color of the root window to a solid color. This can be a color from the color name database or a more exact color name specified by its RGB value.

The command:

% xsetroot -solid liqhtblue

sets the color of the root window to light blue.* See Chapter 8, Command Line Options, for more information on how to specify colors.

Foreground, Background Color and Reverse Video

In addition to specifying a solid color for the root window pattern, xsetroot allows you to specify foreground and background colors if you set the pattern with -bitmap or -mod. The standard Toolkit options are used to set foreground and background colors: -fg and -bg. The defaults are black and white.

Colors can be specified as names from the color name database, or as RGB values. See Chapter 8 for more instructions on how to specify color.

If you specify reverse video (-rv), the foreground and background colors are reversed.

Foreground and background colors also take effect when you set the root window pointer, as described in the following section.

Changing the Root Window Pointer

By default, the pointer is an X when it’s in the root window. You can change the shape of the root window pointer to one of the standard X cursor shapes or to any bitmap, using the following options:

-cursor_name standard_cursor_name

-cursor cursorfile maskfile

Available as of Release 4, the first option allows you to set the root window pointer to one of the standard cursor symbols, which are generally listed in the file /usr/include/Xll/cursor-font.h. We’ve provided a list of the standard cursors in Appendix D. To specify a standard cursor on a command line or in a resource file, strip the XC_prefix from the name. Thus, to set the root window pointer to the pirate cursor symbol, you would enter:

% xsetroot -cursor_name pirate

If you are running the Release 3 version of xsetroot, you have to use a more roundabout method to set the root window pointer to one of the standard cursor shapes. You must first convert the cursor character you want to a bitmap, using the atobm client, described in Chapter 6, Graphics Utilities. Then you can specify the bitmap as the root window cursor shape using the xsetroot option described in the following paragraphs.

This second option is intended to allow you to set the root window pointer to a bitmap, perhaps one you create. The parameters cursorfile and maskfile are bitmaps. The cursorfile sets the bitmap for the pointer shape. In effect, the maskfile is placed behind the cursorfile bitmap to set it off from the root window. The maskfile should be the same shape as the cursorfile, but should generally be at least one pixel wider in all directions.*

For the cursor file, you can use any of the standard bitmaps in /usr/include/Xll/bitmaps or you can make your own with the bitmap client (see Chapter 6, Graphics Utilities).

Every standard cursor has an associated mask. Pictures of the cursors appear in Appendix D, Standard Cursors. To get an idea of what masks look like, display the cursor font using the command:

% xfd -fn cursor.

If you are using your own bitmap as the cursorfile, until you get used to the way masks work, create a maskfile that is a copy of the cursorfile with all bits set, i.e., the maskfile should be all black* (or the foreground color). Then edit the maskfile to make it wider than the cursorfile by at least one pixel in all directions.

To specify a root window pointer made from the smiling Gumby bitmap we created for Figure 6-2, first copy the bitmap to make a mask file:

% cp gumby gumby. mask

Then edit the gumby.mask file using the bitmap client, setting all squares inside the Gumby. (You can use the bitmap command box Flood Fill to set all the empty squares at once.) Continue to edit the bitmap, making it one pixel wider in all directions.

Then specify the new pointer with xsetroot:

% xsetroot -cursor gumby gumby.mask

See Chapter 6, Graphics Utilities, for more information on using bitmap.

xmodmap: Modifier Key and Pointer Customization

The xmodmap client is used to assign (or map) key functions to physical keys on the keyboard. Primarily, xmodmap is used to assign so-called “modifier” key functions to physical keys, but it can also change the way other keys (and even pointer buttons) function.

As described in Chapter 2, Getting Started, keys with labels such as Shift, Control, Caps Lock, etc. are called “modifier” keys because they modify the action of other keys. The number and names of modifier keys differ from workstation to workstation. Every keyboard is likely to have a Shift, Caps Lock, and Control key, but after that, the babble begins. One workstation might have an Alt key, another might have a Funct key, and yet another a “Gold” key. On the Sun-3 keyboard, there are no less than three additional modifier keys, labeled Alternate, Right, and Left.

Because of the differences between keyboards, X programs are designed to work with “logical” modifier keynames. The logical keynames represent functions recognized by X programs. These modifier keynames can be mapped by the user to any physical key on the keyboard with the xmodmap client.

The logical keynames that X recognizes are:

• Shift
• Lock
• Ctrl
• Mod1 (also meta or 1 in uwm)
• Mod2 (also 2 in uwm)
• Mod3 (also 3 in uwm)
• Mod4 (also 4 in uwm)
• Mod5 (also 5 in uwm)

These keynames are case insensitive.

Of these X modifier keys, only Shift. Caps Lock, Control, and Meta are in common use. Note that uwm also recognizes the mod keys simply by number alone (1-5) and recognizes mod 1 as meta (i.e., mod 1, meta and 1 are equivalent).

The primary function of xmodmap is to allow you to assign these important modifier key-name functions (Shift, Control, Meta, etc.) to convenient keys on the keyboard. For example, you could choose to map the Shift function to a single key called “Shift,” to two “Shift” keys (one on either side of the keypad), to an “Alt” key, or to any other convenient key or keys on the physical keyboard. A left-handed person might choose to map modifier keys on the right side of the keyboard that more often are found on the left side, such as Control.

In practical terms, each server will have a default keyboard configuration. The Shift, Caps Lock, and Control modifier keynames will be mapped to obvious keys. The assignment of the Meta key might be less obvious.

The xmodmap client allows you to print out the current assignments of modifier keyname functions to physical keys and/or to change the assignments.

xmodmap also has two other functions, which you will probably use less frequently. In addition to mapping modifier keyname functions to physical keys, xmodmap also allows you to assign the function of any key on the keyboard to any other key. For instance, you can make the Backspace key and the Delete key both function as Delete keys. (This may be helpful if the Backspace key is easier to reach.)

Also, in addition to keyboard mappings, xmodmap can be used to display or change the pointer button assignments. Many X clients recognize logical pointer button commands. For example, holding down and dragging the first logical pointer button in an xterm window copies the text into memory. (In many default pointer maps, the first logical button is the leftmost button, designed to be pressed by the right index finger.) Each logical button is associated with a button code. The first logical button generates button code 1, the second logical button generates button code 2, etc. xmodmap allows you to reassign logical buttons to different physical buttons on the pointer.

Thus, basically, xmodmap can perform three types of mappings:

1. Assign modifier keyname functions (such as Shift, Control, Meta) recognized by X to physical keys.
2. Make any key on the keyboard function as any other key (for example, making Backspace function like Delete).
3. Reassign logical pointer button functions to other physical buttons (for example, making the third physical button function as the first logical button).

In the following sections, we discuss key mapping, with an emphasis on the first type of mapping, of modifier keyname functions. Chances are, you’ll have relatively little call to map other key functions (such as Backspace), though we have included an example of one such mapping, just in case.

After considering key mapping, we’ll take a look at the much simpler issues involved in mapping pointer button functions. As you might expect, when you’re changing the functionality of (up to) three pointer buttons, it’s fairly simple to keep track of what you’re doing.

On the other hand, mapping modifier key functions to physical keys can be more than a little confusing. In order to understand the mechanics of mapping keys, we first need to take a look at some terms used to describe keyboard keys.

Keycodes and Keysyms

Each key on a physical keyboard can be identified by a number known as a keycode. (Technically speaking, a keycode is the actual value that the key generates.) Keycodes cannot be mapped to other keys. No matter what functions you assign to various keys with xmodmap, the keycode associated with each physical key remains the same.

In addition to a keycode, each physical key is associated with a name known as a keysym. A keysym (“key symbol” name) is a name that represents the label on a key (theoretically) and corresponds to its function.

Alphanumeric keys generally have obvious keysyms, corresponding to the label on the key: for example, the keysym for the key labeled “H” is h. Unfortunately, a keysym does not always correspond to the key label. For example, on a Sun-3 workstation, though the keysym for the key labeled “Return“ is Return, the keysym for the key labeled “Alternate” is Break, and the keysym for the key labeled “Right” is Meta_ R.

While each keycode is tied to a physical key, each keysym corresponds to a function—and the keysym/function is mapped to a particular physical key (keycode). Every keyboard has a default assignment of keysyms to keycodes. In most cases, each physical key on the keyboard will be associated with a different keysym. As we’ll see, however, the keysym (function) associated with a particular physical key (keycode) can be changed. This is done by assigning the keysym of one key to the keycode of another.

The modifier keynames recognized by X are not to be confused with keysyms. The X modifier keys are limited to the eight keynames discussed previously and are assigned in addition to the regular keysym/keycode pairings. In other words, when a physical key is mapped to function as the X Control key, it already has a default functionality (keysym) and keycode.

By default, most modifier keyname functions are mapped to keys having keysyms representing the same function. For example, the X Control keyname is probably mapped to the key labeled Control, and having the keysym Control.

The Meta modifier keyname is probably also assigned to a key having the keysym Meta. However, determining which physical key has the keysym Meta can be something of a puzzle. Later in this chapter, we’ll consider a program called xev, which can be used to determine the keysym and keycode of any physical key.

With this background infonnation in mind, we can now tackle a procedure to map modifier keynames.

Procedure to Map Modifier Keys

In order to change modifier key mappings with a minimum of confusion, you should perfonn the following steps:

1. Display the current modifier key mappings using xmodmap.
2. Then print out the default assignments of keysyms to keycodes for all keys, using xmodmap with the -pk option. Save this list of the default key assignments as a reference.
3. Experiment with the xev client to detennine the keysyms associated with certain physical keys. This will help you find the key(s) assigned as the Meta modifier key (which probably also has the keysym Meta).
4. Once you’re familiar with the current assignments, you can remap modifier keys using xmodmap.

Displaying the Current Modifier Key Map

Before mapping any modifier keynames, you should take a look at the current assignments. With no options, xmodmap displays the current map of X modifier keynames to actual keys. Type xmodmap and you get a display similar to this:

xmodmap: up to 2 keys per modifier, (keycodes in parentheses):

shift	Shift_L (O×6a), Shift_R (O×75)
lock	Caps_Lock (O×7e)
control	Control_L (O×53)
mod1	Meta_L (O×7f), Meta_R (O×81)
mod2
mod3
mod4
mod5

For each logical keyname (on the left), xmodmap lists one or more keysyms, each followed in parentheses by an actual hardware keycode. The keycodes displayed by xmodmap are represented in hex. As we’ll see, the equivalent decimal and octal keycodes are also accepted as arguments to xmodmap.

In this mapping, two keys are assigned as Meta (mod1) keys: keys having the keysyms Meta_L and Meta_R (for left and right, apparently one on each side of the keyboard). Unfortunately, as you can see, this doesn’t really tell you which keys these are on the physical keyboard. You still need to know which physical keys (keycodes) have the keysyms Meta_L and Meta_R. You can determine this using the xev client, described later in this chapter.

Determining the Default Key Mappings

Before you start mapping keys, you should display and save a map of the default assignments of keysyms to keycodes. Running xmodmap with the -pk option prints a current map of all keyboard keys to standard output This map, called a keymap table, lists the decimal key-code on the left and the associated keysym(s) on the right. Figure 11-1 shows a portion of a typical keymap table, for a Sun-3 keyboard.

Notice that each keysym is listed by a keysym name (comma, Caps_Lock, etc.) and a keysym value (O×002c, O×ffe5, etc). For our purposes, this value is irrelevant. It cannot be supplied as a keysym argument to xmodmap.

As you can see, the keymap table lists regular keyboard keys (C, V, comma, slash, space, etc.), and function/numeric keypad keys (Rl3, F35, etc.) as well as modifier keys (Caps_Lock, Meta_L and Meta_R). If you map several keys, you may get confused as to the original assignments. Before you map any keys, we suggest you redirect the keymap table to a file to save and use as a reference:

% xmodmap -pk > keytable

The keysyms recognized by your server are a subset of a far greater number of keysyms recognized internationally. The file /usr/include/Xll/keysym.h lists the keysyms families that are enabled for your server. The file /usr/include/Xll/keysymdef.h lists the keysyms in each of the families enabled for your server, as well as the keysyms in several other families. See Appendix H, Keysyms, of Volume Two, Xlib Reference Manual, for more information on keysyms and tables of the most common ones.

Figure 11-1. Partial keymap table

Matching Keysyms with Physical Keys Using xev

The keysym and keycode for any key can be determined with the xev client.* This is particularly useful for finding the Meta key(s). The xev client is used to keep track of events, packets of information that are generated by the server when actions occur and are interpreted by other clients. Moving the pointer or pressing a keyboard key cause input events to occur. (For more information about events, see Volume One, Xlib Programming Manual.)

To use xev, enter the command:

% xev

in an xterm window, and then use the pointer to place the xev window, as in Figure 11-2.

Within the xev window is a small box. Move the pointer inside this box. When you type a key inside the box, information about the key, including its keysym and keycode, will be displayed in the xterm window from which you started xev. The relevant information will look like this:

Figure 11-2. xev window

... keycode 127 (keysym O×ffe7, Meta_L) . . .

Notice that the keycode is given as a decimal number. You can use the decimal keycode as an argument to xmodmap. The keysym is listed by name, Meta_L, and value, Oxffe7. Again, this value cannot be supplied as a keysym argument to xmodmap. (See the xev reference page in Part Three for more information.)

To find the Meta key, type a few likely keys in the xev window. Type Control-C in the window from which you invoked xev to terminate the program. (If you ran xev in the background, you ’ll have to kill the xev window. See Chapter 7, Other Clients, for ways to do this.)

Changing the Map with xmodmap

xmodmap executes an expression or list of expressions that are interpreted as instructions to modify the key (or pointer) map. The expressions that can be interpreted by xmodmap are described in the next section.

xmodmap has the following syntax:

xmodmap [options] [filename]

An expression can be executed in either one of two ways:

• From the command line, using the -e expression option. This option specifies an expression to be executed (as an instruction to modify the map). Any number of expressions may be specified from the command line. An expression should be enclosed in quotes.
• Entered in a file that is used as an argument to xmodmap. Several expressions can be entered in one file.

See the xmodmap reference page in Part Three of this guide for a complete list of options. Other than -e expression, the most important options for our purposes are listed below.

-n	Indicates that xmodmap should not change the key mappings as specified in the filename or command line expression, but should display what it would do. A handy test. (Only works with key mappings, not with expressions that change the pointer map.)
-verbose	Indicates that xmodmap should print logging infonnation as it parses its input.

filename specifies a file containing xmodmap expressions to be executed (as instructions to modify the map). This file is usually kept in the user’s home directory with a name like xmodmaprc.

Expressions to Change the Key Map

The expressions interpreted by xmodmap can be used to perfonn the following types of key mappings:*

1. Assign and remove keysyms as modifier keynames recognized by X.
2. Map any keysym (function) to any physical key (keycode).

The following list shows allowable expressions, divided by function. (Using xmodmap with the -grammar option returns a help message with much of this information.) Those expressions that include an equal sign require a space before and after the sign.

1. To assign and remove keysyms as modifier keynames:

clear MODIFIERNAME

Removes all entries in the modifier map for the given modifier, where valid modifier names are: shift, lock, control, modl, mod2, mod3, mod4, and modS (case does not matter in modifier names, although it does matter for all other names). For example, the expression clear Lock will remove all keys that were bound to the lock modifier.

add MODIFIERNAME = KEYSYMNAME

Adds the given keysym to the indicated modifier map. For example, you could make the Alt key an additional shift modifier key. The keysym name is evaluated after all input expressions are read to make it easy to write expressions to swap keys.

remove MODIFIERNAME = KEYSYMNAME

Removes the given keysym from the indicated modifier map (unmaps it). For example, remove Caps_Lock as the lock modifier key. Unlike with the add expression, the keysym names are evaluated as the line is read in. This allows you to remove keys from a modifier without having to worry about whether or not they have been reassigned.

2. To map any keysym(s) to any physical key (keycode):

keycode NUMBER = KEYSYMNAME

Assigns the keysym to the indicated keycode (which may be specified in decimal, hex or octal). Usually only one keysym is assigned to a given code.

keysym KEYSYMNAME = KEYSYMNAME

Assigns the keysym on the right to the keycode of the keysym on the left. Note that if you have the same keysym bound to multiple keys, this might not work.

Key Mapping Examples

Expressions can be used on the xmodmap command line or entered in a file that is then used as an argument to xmodmap. Note that xmodmap should be run from your startup script (discussed later in this chapter) to take effect for all clients in the login session. This section includes three examples, corresponding to the three types of mappings you can perform.

Remember that including the –n option on the xmodmap command line allows you to see what the new mappings would be, without actually performing them. This can be very useful, particularly while you’re learning to use xmodmap and getting used to the syntax of expressions. (Note, however, that –n cannot be used with expressions to change the pointer mapping.)

First, the xmodmap client also allows you to assign logical modifier keynames to physical keys. A not so obvious feature of xmodmap is that to change the mapping of a modifier key, you must first remove that key from the current modifier map. For example, to swap the left Control and (Caps) Lock keys, you would first need to unmap both physical keys (Caps_Lock, Control_L) from their respective modifier keynames (lock, control):

remove lock = Caps Lock
remove control = Control_L

And then reverse the mappings:

add lock = Control_L
add control = Caps_Lock

If you then type xmodmap without options, you see the new map:

xmodmap: up to 2 keys per modifier, (keycodes in parentheses):
shift    Shift_L (O×6a), Shift_R (O×75)
lock     Control_L (O×53)
control  Caps_Lock (O×7e)
modl     Meta_L (0×7f), Meta_R (O×81)
mod2
mod3
mod4
mod5


The key with the keysym Control_L functions as a Lock key and the key with the keysym Caps_Lock functions as a Control key.

Second, xmodmap allows you to assign any keysym to any other key. For example, you might make the Backspace key function as a Delete key:

% xmodmap -e ’keyaym BackSpace = Delete’

Then when you display the keymap table and grep for the Delete keysym, you’ll see that it is assigned twice. On the command line of an xterm window, type:

% xmodmap -pk | qrep Delete


and you’ll get two lines from the current keymap table, similar to these:

50          O×ffff (Delete)
73          O×ffff (Delete)

The 50 and 73 are keycodes representing two physical keys. As you can see, both of these keys now function as Delete keys.

This example suggests some of the confusion you can experience using xmodmap. We know that one of these keys previously functioned as the Backspace key. But how can we tell which one? Here is an instance when our default keymap table comes in handy. If you’ve run xmodmap -pk and redirected it to a file before changing any mappings, you can check the file for the keysyms originally associated with the keycodes 50 and 73. In this case, the file tells us 50 was originally Backspace and 73 was Delete.

Of course, you could also figure out the original assignments by remapping one of the key-codes to Backspace. Then, if the key marked Backspace functions as marked, you know you’ve mapped the keysym to the original keycode. But, as you can see, the default keymap table can greatly simplify matters.

This example also implies that there are advantages to using expressions of the form:

keycode number = keysymname

This expression syntax requires you to be aware of default keycode/keysym assignments. Also, if you explicitly assign a keysym to a particular keycode, it’s much easier to keep track of what you’re doing and retrace your steps if necessary. On the down side, though keysyms are portable, keycodes may vary from server to server. Thus, expressions using this syntax cannot be ported to other systems.

Displaying and Changing the Pointer Map

If you want to change the assignment of logical pointer buttons to physical buttons, you should first display the current pointer map with the -pp option to xmodmap. A typical pointer map appears in Figure 11-3.

This is a fairly simple map: the physical buttons are listed on the left and the corresponding logical functions (button codes) are listed on the right.

Figure 11-3. Pointer map

These are typical assignments for a right-handed person: the first logical button is the leftmost button, designed to be pressed by the right index finger. The xmodmap client allows you to reassign logical buttons so that the pointer can be more easily used with the left hand.

The xmodmap client allows you to change the pointer map.* There are two xmodmap expressions: one to assign logical pointer buttons (button codes) to physical buttons; and another to restore the default assignments. The syntax of the expressions is as follows:

pointer = x y z

Sets the first, second, and third physical buttons to the button codes x, y, and z.

pointer = default

Sets the pointer map back to its default settings (button 1 generates a code of 1, button 2 generates a code of 2, etc.).

Being able to change the pointer button assignments is very useful if you happen to be left-handed and would like the rightmost physical button to function as the first logical button (i.e., generate button code 1). To configure the pointer for a southpaw:

% xmodmap -e ’pointer = 3 2 1’

Then if you display the pointer mappings with xmodmap -pp, you get the following:

There are 3 pointer buttons defined.

    Physical        Button
     Button          code  
        1              3  
        2              2  
        3              1  

You can then push the first logical button (button code 1) with the index finger of your left hand.

You can return to the default pointer button assignments by entering:

% xmodmap -e ’pointer = default’

*For technical reasons, colors set with xsetroot -solid may change on you unexpectedly. When you set a color with the -solid option to xsetroot, the client allocates a colorcell, sets the color, and deallocates the colorcell. The root window changes to that color. If another client is started that sets a new color, it allocates the next available colorcell—which may be the same one xsetroot just deallocated. This results in that color changing to the new color. The root window also changes to the new color. If this happens, you can ron xsetroot again and if there are other colorcells available, the root window changes to the new color. If all colorcells are allocated, any call to change a colorcell results in an error message.
While this behavior may seem to be a vicious bug, it is actually an optimization designed to make sure applications don’t run out of colors unnecessarily. Free colormap cells can be a scarce resource. See Volume One, Xlib Programming Manual, for more information.

*Technically speaking, the mask determines the pixels on the screen that are disturbed by the cursor. It functions as a sort of outliner or highlighter for the cursor shape. The mask appears as a white (or background color) border around the cursor (black or another foreground color), making it visible over any root window pattern. This is especially important when a black cursor appears on a black root window.

*Don’t be confused by the idea of a black cursor with a black mask on a black root window. Remember, the mask determines the pixels that are disturbed by the cursor—in effect creating an outline around the cursor. The outline appears in white (or specified background color), regardless of the color of the maskfile.

With the xselrool defaults, you can observe the effect of a mask. When you move the X pointer onto the darlc grey root window, the X should have a very thin white border, which enables you to see it more clearly.

*xev is a Release 3 standard client. In Release 4, it has been moved to the demos directory. If an executable version does not exist on your system, ask your system administrator.

If you cannot use xev, you must rely on the keymap table and a little deductive reasoning. Since certain twm functions have keyboard shortcuts involving the Meta key, testing these shortcuts should help you locate this key. See Chapter 3, Using the twm Window Manager, for more information.

*Expressions to change the pointer map are discussed in the section Displaying and Changing the Pointer Map, later in this chapter.

*Remember that the -n option, which allows you to see what xmodmap would do, without performing the changes, cannot be used with expressions to change the pointer mapping.