# User Keyboard Setup for GNUstep Libraries

### Authors

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

Version: $Revision$

Date: $Date$

Copyright: (C) 2005 Free Software Foundation, Inc.

# 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`.