User Keyboard Setup for GNUstep Libraries

Authors

Adam Fedor (fedor@gnu.org)
Nicola Pero (n.pero@mi.flashnet.it)

Version: $Revision: 1.35 $

Date: $Date: 2015/08/31 02:17:17 $

Keyboard Setup

This document describes how to change the mouse and keyboard mappings so that GNUstep can be used properly. This document applies only to the X-Windows based backend.

Defaults Settings

The OpenStep specification requires 3 main different keyboard modifiers: CONTROL, COMMAND and ALTERNATE.

COMMAND is used to enter key equivalents (keyboard shortcuts for menus or buttons); for example, usually 'Quit' on the main menu of an application is bound to 'q', so you may usually quit a GNUstep application by pressing Command - q.
CONTROL and ALTERNATE are two additional modifiers. A typical use of ALTERNATE is to scroll by pages rather than by lines; you have to press ALTERNATE while acting on a scrollbar with the mouse.

By default, GNUstep uses Control_L (left Ctrl) and Control_R (right Ctrl) as CONTROL, Alt_L (left alt) as COMMAND, and Alt_R (right alt, sometimes called AltGr) as ALTERNATE. As a special exception, if Alt_R is not bound to any key on your keyboard, GNUstep will try to use Mode_switch for ALTERNATE instead. Some X server map AltGr onto ISO_Level3_Shift. To allow for this the second code ALTERNATE may be bound to this key.

If this layout does not work for you, because your keyboard misses some of these keys, or they have different X names or they conflict heavily with your window manager shortcuts (or for any other reason), read on.

Changing the Default Settings

Under GNUstep, you may change the default as you wish: you may choose which keys of your keyboard you want to use for CONTROL, COMMAND and ALTERNATE (You may even use different keys for different GNUstep applications, without conflict). These settings are internal to GNUstep, and will not influence the behaviour of other X apps.

You may choose up to 2 keys per modifier.

Note that, if your keyboard is properly set up for X, you should not need to remap your X keyboard to use GNUstep. By changing the defaults, you should be able to use GNUstep whatever the X keyboard mapping might be.

What you have to do, is simply to instruct GNUstep to use different keys for CONTROL, COMMAND and ALTERNATE.

The keys to use are determined at the application startup, by reading the user defaults database.

To set the keys which will act as CONTROL you have to set GSFirstControlKey and GSSecondControlKey; and similarly for the other keys:

CONTROL GSFirstControlKey GSSecondControlKey
COMMAND GSFirstCommandKey GSSecondCommandKey
ALTERNATE GSFirstAlternateKey GSSecondAlternateKey

Valid values are all the standard strings for X keys. To disable completely a key, use NoSymbol as preference.

Each value which you do not explicity set is substituted with its default value. The default values are:

GSFirstControlKey Control_L
GSSecondControlKey Control_R
GSFirstCommandKey Alt_L
GSSecondCommandKey NoSymbol
GSFirstAlternateKey Alt_R (or Mode_switch if there is no Alt_R)
GSSecondAlternateKey NoSymbol

What could go wrong is for example that you don't have an Alt_L key. With the default settings, you will not be able to enter the COMMAND key (which is quite an important key). What you can do in this case is to use Control_R as COMMAND, giving the following commands (from the command line):

	  defaults write NSGlobalDomain GSFirstCommandKey Control_R
	  defaults write NSGlobalDomain GSSecondControlKey NoSymbol

These commands write in the GNUstep user database; the information will be used every time you start a GNUstep application.

The first line sets GSFirstCommandKey to Control_R, which makes Control_R to be read as COMMAND.

The second line disables the second control key, which would otherwise be bound to Control_R by default. If you omit it, Control_R will be used at the same time as COMMAND and as CONTROL, which is not very useful.

To delete these preferences and restore the defaults, use

	  defaults delete NSGlobalDomain GSFirstCommandKey
	  defaults delete NSGlobalDomain GSSecondControlKey

To get a list of currently set defaults, you may use

	  defaults read

The list might be very long; you may want to extract only setting for the GSFirstCommandKey, for example:

	  defaults read | grep GSFirstCommandKey

A thing which could go wrong if you are trying to use a setting different from the default, and you do not know much about X, is that you can't find out the name of one of your key. In this case, you may try having a look at the output of programs like xmodmap or xkeycaps; even if you do not understand it completely, the output can inspire the right guessing.

A problem you are likely to encounter is that of conflicts with the window manager keyboard shortcuts. Good window managers let you change the keyboard shortcuts, so you may move the wm shortcuts that you do not use to keys which do not conflict (at least not too much) with GNUstep.

A final potential worry on X11 has to do with keyboards where hitting 'shift' or another key can affect the interpretation of a modifier key. For example, on some Apple USB keyboards one key to the left of the space bar maps to "Option" without shift pressed, and "Alt" when it IS pressed. Such keyboard mappings are often useful in non-English contexts to access accents or non-Roman characters. However if such a key is used as a modifier in GNUstep problems can occur when trying to use the modifier in conjunction with a shifted character. In particular, you will need to hit and release the modifier and the shift key in a particular order, or else things will not work as expected, and the modifier may become "stuck". If you experience such a problem, set the GNUstep back default GSModifiersAreKeys to YES.