diff --git a/Documentation/GuiUser/KeyboardSetup.gsdoc b/Documentation/GuiUser/KeyboardSetup.gsdoc new file mode 100644 index 000000000..1c65a3911 --- /dev/null +++ b/Documentation/GuiUser/KeyboardSetup.gsdoc @@ -0,0 +1,211 @@ + + + + + User Keyboard Setup for GNUstep Libraries + + + + + + + + + $Revision$ + $Date$ + + + + 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. +

+

+ 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. +

+ +
+ + + + +