1 2@c %start of fragment 3 4@node Key Values 5@chapter Key Values 6Functions for manipulating keyboard codes 7 8@section Overview 9Key values are the codes which are sent whenever a key is pressed or released. 10They appear in the field of the @code{<gdk-event-key>} structure, which is 11passed to signal handlers for the "key-press-event" and "key-release-event" 12signals. The complete list of key values can be found in the 13@file{<gdk/gdkkeysyms.h>} header file. @file{<gdk/gdkkeysyms.h>} is not included 14in @file{<gtk/gtk.h>}, it must be included independently, because the file is 15quite large. 16 17Key values can be converted into a string representation using 18@code{gdk-keyval-name}. The reverse function, converting a string to a key 19value, is provided by @code{gdk-keyval-from-name}. 20 21The case of key values can be determined using @code{gdk-keyval-is-upper} and 22@code{gdk-keyval-is-lower}. Key values can be converted to upper or lower case 23using @code{gdk-keyval-to-upper} and @code{gdk-keyval-to-lower}. 24 25When it makes sense, key values can be converted to and from Unicode characters 26with @code{gdk-keyval-to-unicode} and @code{gdk-unicode-to-keyval}. 27 28One @code{<gdk-keymap>} object exists for each user display. 29@code{gdk-keymap-get-default} returns the @code{<gdk-keymap>} for the default 30display; to obtain keymaps for other displays, use 31@code{gdk-keymap-get-for-display}. A keymap is a mapping from 32@code{<gdk-keymap-key>} to key values. You can think of a 33@code{<gdk-keymap-key>} as a representation of a symbol printed on a physical 34keyboard key. That is, it contains three pieces of information. First, it 35contains the hardware keycode; this is an identifying number for a physical key. 36Second, it contains the @dfn{level} of the key. The level indicates which symbol 37on the key will be used, in a vertical direction. So on a standard US keyboard, 38the key with the number "1" on it also has the exclamation point ("!") character 39on it. The level indicates whether to use the "1" or the "!" symbol. The letter 40keys are considered to have a lowercase letter at level 0, and an uppercase 41letter at level 1, though only the uppercase letter is printed. Third, the 42@code{<gdk-keymap-key>} contains a group; groups are not used on standard US 43keyboards, but are used in many other countries. On a keyboard with groups, 44there can be 3 or 4 symbols printed on a single key. The group indicates 45movement in a horizontal direction. Usually groups are used for two different 46languages. In group 0, a key might have two English characters, and in group 1 47it might have two Hebrew characters. The Hebrew characters will be printed on 48the key next to the English characters. 49 50In order to use a keymap to interpret a key event, it's necessary to first 51convert the keyboard state into an effective group and level. This is done via a 52set of rules that varies widely according to type of keyboard and user 53configuration. The function @code{gdk-keymap-translate-keyboard-state} accepts a 54keyboard state -- consisting of hardware keycode pressed, active modifiers, and 55active group -- applies the appropriate rules, and returns the group/level to be 56used to index the keymap, along with the modifiers which did not affect the 57group and level. i.e. it returns "unconsumed modifiers." The keyboard group may 58differ from the effective group used for keymap lookups because some keys don't 59have multiple groups - e.g. the Enter key is always in group 0 regardless of 60keyboard state. 61 62Note that @code{gdk-keymap-translate-keyboard-state} also returns the keyval, 63i.e. it goes ahead and performs the keymap lookup in addition to telling you 64which effective group/level values were used for the lookup. 65@code{<gdk-event-key>} already contains this keyval, however, so you don't 66normally need to call @code{gdk-keymap-translate-keyboard-state} just to get the 67keyval. 68 69@section Usage 70@include defuns-keys.xml.texi 71 72@c %end of fragment 73