1 /* GDK - The GIMP Drawing Kit
2 * Copyright (C) 2000 Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
21 * Modified by the GTK+ Team and others 1997-2000. See the AUTHORS
22 * file for a list of people on the GTK+ Team. See the ChangeLog
23 * files for a list of changes. These files are distributed with
24 * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
29 #include "gdkkeysprivate.h"
30 #include "gdkdisplay.h"
31 #include "gdkdisplaymanagerprivate.h"
36 * @Short_description: Functions for manipulating keyboard codes
39 * Key values are the codes which are sent whenever a key is pressed or released.
40 * They appear in the #GdkEventKey.keyval field of the
41 * #GdkEventKey structure, which is passed to signal handlers for the
42 * #GtkWidget::key-press-event and #GtkWidget::key-release-event signals.
43 * The complete list of key values can be found in the
44 * <filename><gdk/gdkkeysyms.h></filename> header file.
46 * Key values are regularly updated from the upstream X.org X11 implementation,
47 * so new values are added regularly. They will be prefixed with GDK_KEY_ rather
48 * than XF86XK_ or XK_ (for older symbols).
50 * Key values can be converted into a string representation using
51 * gdk_keyval_name(). The reverse function, converting a string to a key value,
52 * is provided by gdk_keyval_from_name().
54 * The case of key values can be determined using gdk_keyval_is_upper() and
55 * gdk_keyval_is_lower(). Key values can be converted to upper or lower case
56 * using gdk_keyval_to_upper() and gdk_keyval_to_lower().
58 * When it makes sense, key values can be converted to and from
59 * Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
61 * <para id="key-group-explanation">
62 * One #GdkKeymap object exists for each user display. gdk_keymap_get_default()
63 * returns the #GdkKeymap for the default display; to obtain keymaps for other
64 * displays, use gdk_keymap_get_for_display(). A keymap
65 * is a mapping from #GdkKeymapKey to key values. You can think of a #GdkKeymapKey
66 * as a representation of a symbol printed on a physical keyboard key. That is, it
67 * contains three pieces of information. First, it contains the hardware keycode;
68 * this is an identifying number for a physical key. Second, it contains the
69 * <firstterm>level</firstterm> of the key. The level indicates which symbol on the
70 * key will be used, in a vertical direction. So on a standard US keyboard, the key
71 * with the number "1" on it also has the exclamation point ("!") character on
72 * it. The level indicates whether to use the "1" or the "!" symbol. The letter
73 * keys are considered to have a lowercase letter at level 0, and an uppercase
74 * letter at level 1, though only the uppercase letter is printed. Third, the
75 * #GdkKeymapKey contains a group; groups are not used on standard US keyboards,
76 * but are used in many other countries. On a keyboard with groups, there can be 3
77 * or 4 symbols printed on a single key. The group indicates movement in a
78 * horizontal direction. Usually groups are used for two different languages. In
79 * group 0, a key might have two English characters, and in group 1 it might have
80 * two Hebrew characters. The Hebrew characters will be printed on the key next to
81 * the English characters.
84 * In order to use a keymap to interpret a key event, it's necessary to first
85 * convert the keyboard state into an effective group and level. This is done via a
86 * set of rules that varies widely according to type of keyboard and user
87 * configuration. The function gdk_keymap_translate_keyboard_state() accepts a
88 * keyboard state -- consisting of hardware keycode pressed, active modifiers, and
89 * active group -- applies the appropriate rules, and returns the group/level to be
90 * used to index the keymap, along with the modifiers which did not affect the
91 * group and level. i.e. it returns "unconsumed modifiers." The keyboard group may
92 * differ from the effective group used for keymap lookups because some keys don't
93 * have multiple groups - e.g. the Enter key is always in group 0 regardless of
96 * Note that gdk_keymap_translate_keyboard_state() also returns the keyval, i.e. it
97 * goes ahead and performs the keymap lookup in addition to telling you which
98 * effective group/level values were used for the lookup. #GdkEventKey already
99 * contains this keyval, however, so you don't normally need to call
100 * gdk_keymap_translate_keyboard_state() just to get the keyval.
111 static guint signals[LAST_SIGNAL] = { 0 };
113 G_DEFINE_TYPE (GdkKeymap, gdk_keymap, G_TYPE_OBJECT)
116 gdk_keymap_class_init (GdkKeymapClass *klass)
118 GObjectClass *object_class = G_OBJECT_CLASS (klass);
121 * GdkKeymap::direction-changed:
122 * @keymap: the object on which the signal is emitted
124 * The ::direction-changed signal gets emitted when the direction of
125 * the keymap changes.
129 signals[DIRECTION_CHANGED] =
130 g_signal_new ("direction-changed",
131 G_OBJECT_CLASS_TYPE (object_class),
133 G_STRUCT_OFFSET (GdkKeymapClass, direction_changed),
135 g_cclosure_marshal_VOID__VOID,
139 * GdkKeymap::keys-changed:
140 * @keymap: the object on which the signal is emitted
142 * The ::keys-changed signal is emitted when the mapping represented by
147 signals[KEYS_CHANGED] =
148 g_signal_new ("keys-changed",
149 G_OBJECT_CLASS_TYPE (object_class),
151 G_STRUCT_OFFSET (GdkKeymapClass, keys_changed),
153 g_cclosure_marshal_VOID__VOID,
158 * GdkKeymap::state-changed:
159 * @keymap: the object on which the signal is emitted
161 * The ::state-changed signal is emitted when the state of the
162 * keyboard changes, e.g when Caps Lock is turned on or off.
163 * See gdk_keymap_get_caps_lock_state().
167 signals[STATE_CHANGED] =
168 g_signal_new ("state_changed",
169 G_OBJECT_CLASS_TYPE (object_class),
171 G_STRUCT_OFFSET (GdkKeymapClass, state_changed),
173 g_cclosure_marshal_VOID__VOID,
179 gdk_keymap_init (GdkKeymap *keymap)
183 /* Other key-handling stuff
187 * gdk_keyval_convert_case:
189 * @lower: (out): return location for lowercase version of @symbol
190 * @upper: (out): return location for uppercase version of @symbol
192 * Obtains the upper- and lower-case versions of the keyval @symbol.
193 * Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc.
196 gdk_keyval_convert_case (guint symbol,
200 GdkDisplayManager *manager = gdk_display_manager_get ();
202 GDK_DISPLAY_MANAGER_GET_CLASS (manager)->keyval_convert_case (manager, symbol, lower, upper);
206 * gdk_keyval_to_upper:
207 * @keyval: a key value.
209 * Converts a key value to upper case, if applicable.
211 * Returns: the upper case form of @keyval, or @keyval itself if it is already
212 * in upper case or it is not subject to case conversion.
215 gdk_keyval_to_upper (guint keyval)
219 gdk_keyval_convert_case (keyval, NULL, &result);
225 * gdk_keyval_to_lower:
226 * @keyval: a key value.
228 * Converts a key value to lower case, if applicable.
230 * Returns: the lower case form of @keyval, or @keyval itself if it is already
231 * in lower case or it is not subject to case conversion.
234 gdk_keyval_to_lower (guint keyval)
238 gdk_keyval_convert_case (keyval, &result, NULL);
244 * gdk_keyval_is_upper:
245 * @keyval: a key value.
247 * Returns %TRUE if the given key value is in upper case.
249 * Returns: %TRUE if @keyval is in upper case, or if @keyval is not subject to
253 gdk_keyval_is_upper (guint keyval)
259 gdk_keyval_convert_case (keyval, NULL, &upper_val);
260 return upper_val == keyval;
266 * gdk_keyval_is_lower:
267 * @keyval: a key value.
269 * Returns %TRUE if the given key value is in lower case.
271 * Returns: %TRUE if @keyval is in lower case, or if @keyval is not
272 * subject to case conversion.
275 gdk_keyval_is_lower (guint keyval)
281 gdk_keyval_convert_case (keyval, &lower_val, NULL);
282 return lower_val == keyval;
288 * gdk_keymap_get_default:
290 * Returns the #GdkKeymap attached to the default display.
292 * Returns: (transfer none): the #GdkKeymap attached to the default display.
295 gdk_keymap_get_default (void)
297 return gdk_keymap_get_for_display (gdk_display_get_default ());
301 * gdk_keymap_get_direction:
302 * @keymap: a #GdkKeymap
304 * Returns the direction of effective layout of the keymap.
306 * Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL
307 * if it can determine the direction. %PANGO_DIRECTION_NEUTRAL
311 gdk_keymap_get_direction (GdkKeymap *keymap)
313 return GDK_KEYMAP_GET_CLASS(keymap)->get_direction (keymap);
317 * gdk_keymap_have_bidi_layouts:
318 * @keymap: a #GdkKeymap
320 * Determines if keyboard layouts for both right-to-left and left-to-right
321 * languages are in use.
323 * Returns: %TRUE if there are layouts in both directions, %FALSE otherwise
328 gdk_keymap_have_bidi_layouts (GdkKeymap *keymap)
330 return GDK_KEYMAP_GET_CLASS(keymap)->have_bidi_layouts (keymap);
334 * gdk_keymap_get_caps_lock_state:
335 * @keymap: a #GdkKeymap
337 * Returns whether the Caps Lock modifer is locked.
339 * Returns: %TRUE if Caps Lock is on
344 gdk_keymap_get_caps_lock_state (GdkKeymap *keymap)
346 return GDK_KEYMAP_GET_CLASS(keymap)->get_caps_lock_state (keymap);
350 * gdk_keymap_get_num_lock_state:
351 * @keymap: a #GdkKeymap
353 * Returns whether the Num Lock modifer is locked.
355 * Returns: %TRUE if Num Lock is on
360 gdk_keymap_get_num_lock_state (GdkKeymap *keymap)
362 return GDK_KEYMAP_GET_CLASS(keymap)->get_num_lock_state (keymap);
366 * gdk_keymap_get_entries_for_keyval:
367 * @keymap: a #GdkKeymap
368 * @keyval: a keyval, such as %GDK_a, %GDK_Up, %GDK_Return, etc.
369 * @keys: (out) (array length=n_keys) (transfer full): return location
370 * for an array of #GdkKeymapKey
371 * @n_keys: return location for number of elements in returned array
373 * Obtains a list of keycode/group/level combinations that will
374 * generate @keyval. Groups and levels are two kinds of keyboard mode;
375 * in general, the level determines whether the top or bottom symbol
376 * on a key is used, and the group determines whether the left or
377 * right symbol is used. On US keyboards, the shift key changes the
378 * keyboard level, and there are no groups. A group switch key might
379 * convert a keyboard between Hebrew to English modes, for example.
380 * #GdkEventKey contains a %group field that indicates the active
381 * keyboard group. The level is computed from the modifier mask.
382 * The returned array should be freed
385 * Return value: %TRUE if keys were found and returned
388 gdk_keymap_get_entries_for_keyval (GdkKeymap *keymap,
393 return GDK_KEYMAP_GET_CLASS(keymap)->get_entries_for_keyval (keymap, keyval, keys, n_keys);
397 * gdk_keymap_get_entries_for_keycode:
398 * @keymap: a #GdkKeymap
399 * @hardware_keycode: a keycode
400 * @keys: (out) (array length=n_entries) (transfer full): return
401 * location for array of #GdkKeymapKey, or %NULL
402 * @keyvals: (out) (array length=n_entries) (transfer full): return
403 * location for array of keyvals, or %NULL
404 * @n_entries: length of @keys and @keyvals
406 * Returns the keyvals bound to @hardware_keycode.
407 * The Nth #GdkKeymapKey in @keys is bound to the Nth
408 * keyval in @keyvals. Free the returned arrays with g_free().
409 * When a keycode is pressed by the user, the keyval from
410 * this list of entries is selected by considering the effective
411 * keyboard group and level. See gdk_keymap_translate_keyboard_state().
413 * Returns: %TRUE if there were any entries
416 gdk_keymap_get_entries_for_keycode (GdkKeymap *keymap,
417 guint hardware_keycode,
422 return GDK_KEYMAP_GET_CLASS(keymap)->get_entries_for_keycode (keymap, hardware_keycode, keys, keyvals, n_entries);
426 * gdk_keymap_lookup_key:
427 * @keymap: a #GdkKeymap
428 * @key: a #GdkKeymapKey with keycode, group, and level initialized
430 * Looks up the keyval mapped to a keycode/group/level triplet.
431 * If no keyval is bound to @key, returns 0. For normal user input,
432 * you want to use gdk_keymap_translate_keyboard_state() instead of
433 * this function, since the effective group/level may not be
434 * the same as the current keyboard state.
436 * Return value: a keyval, or 0 if none was mapped to the given @key
439 gdk_keymap_lookup_key (GdkKeymap *keymap,
440 const GdkKeymapKey *key)
442 return GDK_KEYMAP_GET_CLASS(keymap)->lookup_key (keymap, key);
446 * gdk_keymap_translate_keyboard_state:
447 * @keymap: a #GdkKeymap
448 * @hardware_keycode: a keycode
449 * @state: a modifier state
450 * @group: active keyboard group
451 * @keyval: (out) (allow-none): return location for keyval, or %NULL
452 * @effective_group: (out) (allow-none): return location for effective
454 * @level: (out) (allow-none): return location for level, or %NULL
455 * @consumed_modifiers: (out) (allow-none): return location for modifiers
456 * that were used to determine the group or level, or %NULL
458 * Translates the contents of a #GdkEventKey into a keyval, effective
459 * group, and level. Modifiers that affected the translation and
460 * are thus unavailable for application use are returned in
461 * @consumed_modifiers.
462 * See <xref linkend="key-group-explanation"/> for an explanation of
463 * groups and levels. The @effective_group is the group that was
464 * actually used for the translation; some keys such as Enter are not
465 * affected by the active keyboard group. The @level is derived from
466 * @state. For convenience, #GdkEventKey already contains the translated
467 * keyval, so this function isn't as useful as you might think.
470 * @consumed_modifiers gives modifiers that should be masked out
471 * from @state when comparing this key press to a hot key. For
472 * instance, on a US keyboard, the <literal>plus</literal>
473 * symbol is shifted, so when comparing a key press to a
474 * <literal><Control>plus</literal> accelerator <Shift> should
477 * <informalexample><programlisting>
478 * /* We want to ignore irrelevant modifiers like ScrollLock */
479 * #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
480 * gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode,
481 * event->state, event->group,
482 * &keyval, NULL, NULL, &consumed);
483 * if (keyval == GDK_PLUS &&
484 * (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
485 * /* Control was pressed */
486 * </programlisting></informalexample>
488 * An older interpretation @consumed_modifiers was that it contained
489 * all modifiers that might affect the translation of the key;
490 * this allowed accelerators to be stored with irrelevant consumed
491 * modifiers, by doing:</para>
492 * <informalexample><programlisting>
493 * /* XXX Don't do this XXX */
494 * if (keyval == accel_keyval &&
495 * (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
496 * /* Accelerator was pressed */
497 * </programlisting></informalexample>
499 * However, this did not work if multi-modifier combinations were
500 * used in the keymap, since, for instance, <literal><Control></literal>
501 * would be masked out even if only <literal><Control><Alt></literal>
502 * was used in the keymap. To support this usage as well as well as
503 * possible, all <emphasis>single modifier</emphasis> combinations
504 * that could affect the key for any combination of modifiers will
505 * be returned in @consumed_modifiers; multi-modifier combinations
506 * are returned only when actually found in @state. When you store
507 * accelerators, you should always store them with consumed modifiers
508 * removed. Store <literal><Control>plus</literal>,
509 * not <literal><Control><Shift>plus</literal>,
512 * Return value: %TRUE if there was a keyval bound to the keycode/state/group
515 gdk_keymap_translate_keyboard_state (GdkKeymap *keymap,
516 guint hardware_keycode,
517 GdkModifierType state,
520 gint *effective_group,
522 GdkModifierType *consumed_modifiers)
524 return GDK_KEYMAP_GET_CLASS(keymap)->translate_keyboard_state (keymap,
535 * gdk_keymap_add_virtual_modifiers:
536 * @keymap: a #GdkKeymap
537 * @state: (out): pointer to the modifier mask to change
539 * Adds virtual modifiers (i.e. Super, Hyper and Meta) which correspond
540 * to the real modifiers (i.e Mod2, Mod3, ...) in @modifiers.
541 * are set in @state to their non-virtual counterparts (i.e. Mod2,
542 * Mod3,...) and set the corresponding bits in @state.
544 * GDK already does this before delivering key events, but for
545 * compatibility reasons, it only sets the first virtual modifier
546 * it finds, whereas this function sets all matching virtual modifiers.
548 * This function is useful when matching key events against
554 gdk_keymap_add_virtual_modifiers (GdkKeymap *keymap,
555 GdkModifierType *state)
557 GDK_KEYMAP_GET_CLASS(keymap)->add_virtual_modifiers (keymap, state);
561 * gdk_keymap_map_virtual_modifiers:
562 * @keymap: a #GdkKeymap
563 * @state: (out): pointer to the modifier state to map
565 * Maps the virtual modifiers (i.e. Super, Hyper and Meta) which
566 * are set in @state to their non-virtual counterparts (i.e. Mod2,
567 * Mod3,...) and set the corresponding bits in @state.
569 * This function is useful when matching key events against
572 * Returns: %TRUE if no virtual modifiers were mapped to the
573 * same non-virtual modifier. Note that %FALSE is also returned
574 * if a virtual modifier is mapped to a non-virtual modifier that
575 * was already set in @state.
580 gdk_keymap_map_virtual_modifiers (GdkKeymap *keymap,
581 GdkModifierType *state)
583 return GDK_KEYMAP_GET_CLASS(keymap)->map_virtual_modifiers (keymap, state);
588 * @keyval: a key value
590 * Converts a key value into a symbolic name.
592 * The names are the same as those in the
593 * <filename><gdk/gdkkeysyms.h></filename> header file
594 * but without the leading "GDK_KEY_".
596 * Return value: (transfer none): a string containing the name of the key,
597 * or %NULL if @keyval is not a valid key. The string should not be
601 gdk_keyval_name (guint keyval)
603 GdkDisplayManager *manager = gdk_display_manager_get ();
605 return GDK_DISPLAY_MANAGER_GET_CLASS (manager)->get_keyval_name (manager, keyval);
609 * gdk_keyval_from_name:
610 * @keyval_name: a key name
612 * Converts a key name to a key value.
614 * The names are the same as those in the
615 * <filename><gdk/gdkkeysyms.h></filename> header file
616 * but without the leading "GDK_KEY_".
618 * Returns: the corresponding key value, or %GDK_KEY_VoidSymbol
619 * if the key name is not a valid key
622 gdk_keyval_from_name (const gchar *keyval_name)
624 GdkDisplayManager *manager = gdk_display_manager_get ();
626 return GDK_DISPLAY_MANAGER_GET_CLASS (manager)->lookup_keyval (manager, keyval_name);