Pileus Git - ~andy/gtk/blob - gdk/gdkkeys.c

   1 /* GDK - The GIMP Drawing Kit
   2  * Copyright (C) 2000 Red Hat, Inc.
   3  *
   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.
   8  *
   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.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library. If not, see <http://www.gnu.org/licenses/>.
  16  */
  17
  18 /*
  19  * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
  20  * file for a list of people on the GTK+ Team.  See the ChangeLog
  21  * files for a list of changes.  These files are distributed with
  22  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  23  */
  24
  25 #include "config.h"
  26
  27 #include "gdkkeysyms.h"
  28 #include "gdkkeysprivate.h"
  29 #include "gdkdisplay.h"
  30 #include "gdkdisplaymanagerprivate.h"
  31
  32
  33 /**
  34  * SECTION:keys
  35  * @Short_description: Functions for manipulating keyboard codes
  36  * @Title: Key Values
  37  *
  38  * Key values are the codes which are sent whenever a key is pressed or released.
  39  * They appear in the #GdkEventKey.keyval field of the
  40  * #GdkEventKey structure, which is passed to signal handlers for the
  41  * #GtkWidget::key-press-event and #GtkWidget::key-release-event signals.
  42  * The complete list of key values can be found in the
  43  * <filename>&lt;gdk/gdkkeysyms.h&gt;</filename> header file.
  44  *
  45  * Key values are regularly updated from the upstream X.org X11 implementation,
  46  * so new values are added regularly. They will be prefixed with GDK_KEY_ rather
  47  * than XF86XK_ or XK_ (for older symbols).
  48  *
  49  * Key values can be converted into a string representation using
  50  * gdk_keyval_name(). The reverse function, converting a string to a key value,
  51  * is provided by gdk_keyval_from_name().
  52  *
  53  * The case of key values can be determined using gdk_keyval_is_upper() and
  54  * gdk_keyval_is_lower(). Key values can be converted to upper or lower case
  55  * using gdk_keyval_to_upper() and gdk_keyval_to_lower().
  56  *
  57  * When it makes sense, key values can be converted to and from
  58  * Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
  59  *
  60  * <para id="key-group-explanation">
  61  * One #GdkKeymap object exists for each user display. gdk_keymap_get_default()
  62  * returns the #GdkKeymap for the default display; to obtain keymaps for other
  63  * displays, use gdk_keymap_get_for_display(). A keymap
  64  * is a mapping from #GdkKeymapKey to key values. You can think of a #GdkKeymapKey
  65  * as a representation of a symbol printed on a physical keyboard key. That is, it
  66  * contains three pieces of information. First, it contains the hardware keycode;
  67  * this is an identifying number for a physical key. Second, it contains the
  68  * <firstterm>level</firstterm> of the key. The level indicates which symbol on the
  69  * key will be used, in a vertical direction. So on a standard US keyboard, the key
  70  * with the number "1" on it also has the exclamation point ("!") character on
  71  * it. The level indicates whether to use the "1" or the "!" symbol.  The letter
  72  * keys are considered to have a lowercase letter at level 0, and an uppercase
  73  * letter at level 1, though only the uppercase letter is printed.  Third, the
  74  * #GdkKeymapKey contains a group; groups are not used on standard US keyboards,
  75  * but are used in many other countries. On a keyboard with groups, there can be 3
  76  * or 4 symbols printed on a single key. The group indicates movement in a
  77  * horizontal direction. Usually groups are used for two different languages.  In
  78  * group 0, a key might have two English characters, and in group 1 it might have
  79  * two Hebrew characters. The Hebrew characters will be printed on the key next to
  80  * the English characters.
  81  * </para>
  82  *
  83  * In order to use a keymap to interpret a key event, it's necessary to first
  84  * convert the keyboard state into an effective group and level. This is done via a
  85  * set of rules that varies widely according to type of keyboard and user
  86  * configuration. The function gdk_keymap_translate_keyboard_state() accepts a
  87  * keyboard state -- consisting of hardware keycode pressed, active modifiers, and
  88  * active group -- applies the appropriate rules, and returns the group/level to be
  89  * used to index the keymap, along with the modifiers which did not affect the
  90  * group and level. i.e. it returns "unconsumed modifiers." The keyboard group may
  91  * differ from the effective group used for keymap lookups because some keys don't
  92  * have multiple groups - e.g. the Enter key is always in group 0 regardless of
  93  * keyboard state.
  94  *
  95  * Note that gdk_keymap_translate_keyboard_state() also returns the keyval, i.e. it
  96  * goes ahead and performs the keymap lookup in addition to telling you which
  97  * effective group/level values were used for the lookup. #GdkEventKey already
  98  * contains this keyval, however, so you don't normally need to call
  99  * gdk_keymap_translate_keyboard_state() just to get the keyval.
 100  */
 101
 102
 103 enum {
 104   DIRECTION_CHANGED,
 105   KEYS_CHANGED,
 106   STATE_CHANGED,
 107   LAST_SIGNAL
 108 };
 109
 110
 111 static GdkModifierType gdk_keymap_real_get_modifier_mask (GdkKeymap         *keymap,
 112                                                           GdkModifierIntent  intent);
 113
 114
 115 static guint signals[LAST_SIGNAL] = { 0 };
 116
 117 G_DEFINE_TYPE (GdkKeymap, gdk_keymap, G_TYPE_OBJECT)
 118
 119 static void
 120 gdk_keymap_class_init (GdkKeymapClass *klass)
 121 {
 122   GObjectClass *object_class = G_OBJECT_CLASS (klass);
 123
 124   klass->get_modifier_mask = gdk_keymap_real_get_modifier_mask;
 125
 126   /**
 127    * GdkKeymap::direction-changed:
 128    * @keymap: the object on which the signal is emitted
 129    *
 130    * The ::direction-changed signal gets emitted when the direction of
 131    * the keymap changes.
 132    *
 133    * Since: 2.0
 134    */
 135   signals[DIRECTION_CHANGED] =
 136     g_signal_new ("direction-changed",
 137                   G_OBJECT_CLASS_TYPE (object_class),
 138                   G_SIGNAL_RUN_LAST,
 139                   G_STRUCT_OFFSET (GdkKeymapClass, direction_changed),
 140                   NULL, NULL,
 141                   g_cclosure_marshal_VOID__VOID,
 142                   G_TYPE_NONE,
 143                   0);
 144   /**
 145    * GdkKeymap::keys-changed:
 146    * @keymap: the object on which the signal is emitted
 147    *
 148    * The ::keys-changed signal is emitted when the mapping represented by
 149    * @keymap changes.
 150    *
 151    * Since: 2.2
 152    */
 153   signals[KEYS_CHANGED] =
 154     g_signal_new ("keys-changed",
 155                   G_OBJECT_CLASS_TYPE (object_class),
 156                   G_SIGNAL_RUN_LAST,
 157                   G_STRUCT_OFFSET (GdkKeymapClass, keys_changed),
 158                   NULL, NULL,
 159                   g_cclosure_marshal_VOID__VOID,
 160                   G_TYPE_NONE,
 161                   0);
 162
 163   /**
 164    * GdkKeymap::state-changed:
 165    * @keymap: the object on which the signal is emitted
 166    *
 167    * The ::state-changed signal is emitted when the state of the
 168    * keyboard changes, e.g when Caps Lock is turned on or off.
 169    * See gdk_keymap_get_caps_lock_state().
 170    *
 171    * Since: 2.16
 172    */
 173   signals[STATE_CHANGED] =
 174     g_signal_new ("state_changed",
 175                   G_OBJECT_CLASS_TYPE (object_class),
 176                   G_SIGNAL_RUN_LAST,
 177                   G_STRUCT_OFFSET (GdkKeymapClass, state_changed),
 178                   NULL, NULL,
 179                   g_cclosure_marshal_VOID__VOID,
 180                   G_TYPE_NONE,
 181                   0);
 182 }
 183
 184 static void
 185 gdk_keymap_init (GdkKeymap *keymap)
 186 {
 187 }
 188
 189 /* Other key-handling stuff
 190  */
 191
 192 /**
 193  * gdk_keyval_convert_case:
 194  * @symbol: a keyval
 195  * @lower: (out): return location for lowercase version of @symbol
 196  * @upper: (out): return location for uppercase version of @symbol
 197  *
 198  * Obtains the upper- and lower-case versions of the keyval @symbol.
 199  * Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc.
 200  */
 201 void
 202 gdk_keyval_convert_case (guint symbol,
 203                          guint *lower,
 204                          guint *upper)
 205 {
 206   GdkDisplayManager *manager = gdk_display_manager_get ();
 207
 208   GDK_DISPLAY_MANAGER_GET_CLASS (manager)->keyval_convert_case (manager, symbol, lower, upper);
 209 }
 210
 211 /**
 212  * gdk_keyval_to_upper:
 213  * @keyval: a key value.
 214  *
 215  * Converts a key value to upper case, if applicable.
 216  *
 217  * Returns: the upper case form of @keyval, or @keyval itself if it is already
 218  *   in upper case or it is not subject to case conversion.
 219  */
 220 guint
 221 gdk_keyval_to_upper (guint keyval)
 222 {
 223   guint result;
 224
 225   gdk_keyval_convert_case (keyval, NULL, &result);
 226
 227   return result;
 228 }
 229
 230 /**
 231  * gdk_keyval_to_lower:
 232  * @keyval: a key value.
 233  *
 234  * Converts a key value to lower case, if applicable.
 235  *
 236  * Returns: the lower case form of @keyval, or @keyval itself if it is already
 237  *  in lower case or it is not subject to case conversion.
 238  */
 239 guint
 240 gdk_keyval_to_lower (guint keyval)
 241 {
 242   guint result;
 243
 244   gdk_keyval_convert_case (keyval, &result, NULL);
 245
 246   return result;
 247 }
 248
 249 /**
 250  * gdk_keyval_is_upper:
 251  * @keyval: a key value.
 252  *
 253  * Returns %TRUE if the given key value is in upper case.
 254  *
 255  * Returns: %TRUE if @keyval is in upper case, or if @keyval is not subject to
 256  *  case conversion.
 257  */
 258 gboolean
 259 gdk_keyval_is_upper (guint keyval)
 260 {
 261   if (keyval)
 262     {
 263       guint upper_val = 0;
 264
 265       gdk_keyval_convert_case (keyval, NULL, &upper_val);
 266       return upper_val == keyval;
 267     }
 268   return FALSE;
 269 }
 270
 271 /**
 272  * gdk_keyval_is_lower:
 273  * @keyval: a key value.
 274  *
 275  * Returns %TRUE if the given key value is in lower case.
 276  *
 277  * Returns: %TRUE if @keyval is in lower case, or if @keyval is not
 278  *   subject to case conversion.
 279  */
 280 gboolean
 281 gdk_keyval_is_lower (guint keyval)
 282 {
 283   if (keyval)
 284     {
 285       guint lower_val = 0;
 286
 287       gdk_keyval_convert_case (keyval, &lower_val, NULL);
 288       return lower_val == keyval;
 289     }
 290   return FALSE;
 291 }
 292
 293 /**
 294  * gdk_keymap_get_default:
 295  *
 296  * Returns the #GdkKeymap attached to the default display.
 297  *
 298  * Returns: (transfer none): the #GdkKeymap attached to the default display.
 299  */
 300 GdkKeymap*
 301 gdk_keymap_get_default (void)
 302 {
 303   return gdk_keymap_get_for_display (gdk_display_get_default ());
 304 }
 305
 306 /**
 307  * gdk_keymap_get_direction:
 308  * @keymap: a #GdkKeymap
 309  *
 310  * Returns the direction of effective layout of the keymap.
 311  *
 312  * Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL
 313  *   if it can determine the direction. %PANGO_DIRECTION_NEUTRAL
 314  *   otherwise.
 315  **/
 316 PangoDirection
 317 gdk_keymap_get_direction (GdkKeymap *keymap)
 318 {
 319   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), PANGO_DIRECTION_LTR);
 320
 321   return GDK_KEYMAP_GET_CLASS (keymap)->get_direction (keymap);
 322 }
 323
 324 /**
 325  * gdk_keymap_have_bidi_layouts:
 326  * @keymap: a #GdkKeymap
 327  *
 328  * Determines if keyboard layouts for both right-to-left and left-to-right
 329  * languages are in use.
 330  *
 331  * Returns: %TRUE if there are layouts in both directions, %FALSE otherwise
 332  *
 333  * Since: 2.12
 334  **/
 335 gboolean
 336 gdk_keymap_have_bidi_layouts (GdkKeymap *keymap)
 337 {
 338   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);
 339
 340   return GDK_KEYMAP_GET_CLASS (keymap)->have_bidi_layouts (keymap);
 341 }
 342
 343 /**
 344  * gdk_keymap_get_caps_lock_state:
 345  * @keymap: a #GdkKeymap
 346  *
 347  * Returns whether the Caps Lock modifer is locked.
 348  *
 349  * Returns: %TRUE if Caps Lock is on
 350  *
 351  * Since: 2.16
 352  */
 353 gboolean
 354 gdk_keymap_get_caps_lock_state (GdkKeymap *keymap)
 355 {
 356   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);
 357
 358   return GDK_KEYMAP_GET_CLASS (keymap)->get_caps_lock_state (keymap);
 359 }
 360
 361 /**
 362  * gdk_keymap_get_num_lock_state:
 363  * @keymap: a #GdkKeymap
 364  *
 365  * Returns whether the Num Lock modifer is locked.
 366  *
 367  * Returns: %TRUE if Num Lock is on
 368  *
 369  * Since: 3.0
 370  */
 371 gboolean
 372 gdk_keymap_get_num_lock_state (GdkKeymap *keymap)
 373 {
 374   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);
 375
 376   return GDK_KEYMAP_GET_CLASS (keymap)->get_num_lock_state (keymap);
 377 }
 378
 379 /**
 380  * gdk_keymap_get_modifier_state:
 381  * @keymap: a #GdkKeymap
 382  *
 383  * Returns the current modifier state.
 384  *
 385  * Returns: the current modifier state.
 386  *
 387  * Since: 3.4
 388  */
 389 guint
 390 gdk_keymap_get_modifier_state (GdkKeymap *keymap)
 391 {
 392   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);
 393
 394   if (GDK_KEYMAP_GET_CLASS (keymap)->get_modifier_state)
 395     return GDK_KEYMAP_GET_CLASS (keymap)->get_modifier_state (keymap);
 396
 397   return 0;
 398 }
 399
 400 /**
 401  * gdk_keymap_get_entries_for_keyval:
 402  * @keymap: a #GdkKeymap
 403  * @keyval: a keyval, such as %GDK_a, %GDK_Up, %GDK_Return, etc.
 404  * @keys: (out) (array length=n_keys) (transfer full): return location
 405  *     for an array of #GdkKeymapKey
 406  * @n_keys: return location for number of elements in returned array
 407  *
 408  * Obtains a list of keycode/group/level combinations that will
 409  * generate @keyval. Groups and levels are two kinds of keyboard mode;
 410  * in general, the level determines whether the top or bottom symbol
 411  * on a key is used, and the group determines whether the left or
 412  * right symbol is used. On US keyboards, the shift key changes the
 413  * keyboard level, and there are no groups. A group switch key might
 414  * convert a keyboard between Hebrew to English modes, for example.
 415  * #GdkEventKey contains a %group field that indicates the active
 416  * keyboard group. The level is computed from the modifier mask.
 417  * The returned array should be freed
 418  * with g_free().
 419  *
 420  * Return value: %TRUE if keys were found and returned
 421  **/
 422 gboolean
 423 gdk_keymap_get_entries_for_keyval (GdkKeymap     *keymap,
 424                                    guint          keyval,
 425                                    GdkKeymapKey **keys,
 426                                    gint          *n_keys)
 427 {
 428   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);
 429   g_return_val_if_fail (keys != NULL, FALSE);
 430   g_return_val_if_fail (n_keys != NULL, FALSE);
 431   g_return_val_if_fail (keyval != 0, FALSE);
 432
 433   return GDK_KEYMAP_GET_CLASS (keymap)->get_entries_for_keyval (keymap, keyval,
 434                                                                 keys, n_keys);
 435 }
 436
 437 /**
 438  * gdk_keymap_get_entries_for_keycode:
 439  * @keymap: a #GdkKeymap
 440  * @hardware_keycode: a keycode
 441  * @keys: (out) (array length=n_entries) (transfer full): return
 442  *     location for array of #GdkKeymapKey, or %NULL
 443  * @keyvals: (out) (array length=n_entries) (transfer full): return
 444  *     location for array of keyvals, or %NULL
 445  * @n_entries: length of @keys and @keyvals
 446  *
 447  * Returns the keyvals bound to @hardware_keycode.
 448  * The Nth #GdkKeymapKey in @keys is bound to the Nth
 449  * keyval in @keyvals. Free the returned arrays with g_free().
 450  * When a keycode is pressed by the user, the keyval from
 451  * this list of entries is selected by considering the effective
 452  * keyboard group and level. See gdk_keymap_translate_keyboard_state().
 453  *
 454  * Returns: %TRUE if there were any entries
 455  **/
 456 gboolean
 457 gdk_keymap_get_entries_for_keycode (GdkKeymap     *keymap,
 458                                     guint          hardware_keycode,
 459                                     GdkKeymapKey **keys,
 460                                     guint        **keyvals,
 461                                     gint          *n_entries)
 462 {
 463   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);
 464   g_return_val_if_fail (n_entries != NULL, FALSE);
 465
 466   return GDK_KEYMAP_GET_CLASS (keymap)->get_entries_for_keycode (keymap, hardware_keycode,
 467                                                                  keys, keyvals, n_entries);
 468 }
 469
 470 /**
 471  * gdk_keymap_lookup_key:
 472  * @keymap: a #GdkKeymap
 473  * @key: a #GdkKeymapKey with keycode, group, and level initialized
 474  *
 475  * Looks up the keyval mapped to a keycode/group/level triplet.
 476  * If no keyval is bound to @key, returns 0. For normal user input,
 477  * you want to use gdk_keymap_translate_keyboard_state() instead of
 478  * this function, since the effective group/level may not be
 479  * the same as the current keyboard state.
 480  *
 481  * Return value: a keyval, or 0 if none was mapped to the given @key
 482  **/
 483 guint
 484 gdk_keymap_lookup_key (GdkKeymap          *keymap,
 485                        const GdkKeymapKey *key)
 486 {
 487   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), 0);
 488   g_return_val_if_fail (key != NULL, 0);
 489
 490   return GDK_KEYMAP_GET_CLASS (keymap)->lookup_key (keymap, key);
 491 }
 492
 493 /**
 494  * gdk_keymap_translate_keyboard_state:
 495  * @keymap: a #GdkKeymap
 496  * @hardware_keycode: a keycode
 497  * @state: a modifier state
 498  * @group: active keyboard group
 499  * @keyval: (out) (allow-none): return location for keyval, or %NULL
 500  * @effective_group: (out) (allow-none): return location for effective
 501  *     group, or %NULL
 502  * @level: (out) (allow-none): return location for level, or %NULL
 503  * @consumed_modifiers: (out) (allow-none): return location for modifiers
 504  *     that were used to determine the group or level, or %NULL
 505  *
 506  * Translates the contents of a #GdkEventKey into a keyval, effective
 507  * group, and level. Modifiers that affected the translation and
 508  * are thus unavailable for application use are returned in
 509  * @consumed_modifiers.
 510  * See <xref linkend="key-group-explanation"/> for an explanation of
 511  * groups and levels. The @effective_group is the group that was
 512  * actually used for the translation; some keys such as Enter are not
 513  * affected by the active keyboard group. The @level is derived from
 514  * @state. For convenience, #GdkEventKey already contains the translated
 515  * keyval, so this function isn't as useful as you might think.
 516  *
 517  * <note><para>
 518  * @consumed_modifiers gives modifiers that should be masked out
 519  * from @state when comparing this key press to a hot key. For
 520  * instance, on a US keyboard, the <literal>plus</literal>
 521  * symbol is shifted, so when comparing a key press to a
 522  * <literal>&lt;Control&gt;plus</literal> accelerator &lt;Shift&gt; should
 523  * be masked out.
 524  * </para>
 525  * <informalexample><programlisting>
 526  * &sol;* We want to ignore irrelevant modifiers like ScrollLock *&sol;
 527  * &num;define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
 528  * gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode,
 529  *                                      event->state, event->group,
 530  *                                      &amp;keyval, NULL, NULL, &amp;consumed);
 531  * if (keyval == GDK_PLUS &&
 532  *     (event->state &amp; ~consumed &amp; ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
 533  *   &sol;* Control was pressed *&sol;
 534  * </programlisting></informalexample>
 535  * <para>
 536  * An older interpretation @consumed_modifiers was that it contained
 537  * all modifiers that might affect the translation of the key;
 538  * this allowed accelerators to be stored with irrelevant consumed
 539  * modifiers, by doing:</para>
 540  * <informalexample><programlisting>
 541  * &sol;* XXX Don't do this XXX *&sol;
 542  * if (keyval == accel_keyval &&
 543  *     (event->state &amp; ~consumed &amp; ALL_ACCELS_MASK) == (accel_mods &amp; ~consumed))
 544  *   &sol;* Accelerator was pressed *&sol;
 545  * </programlisting></informalexample>
 546  * <para>
 547  * However, this did not work if multi-modifier combinations were
 548  * used in the keymap, since, for instance, <literal>&lt;Control&gt;</literal>
 549  * would be masked out even if only <literal>&lt;Control&gt;&lt;Alt&gt;</literal>
 550  * was used in the keymap. To support this usage as well as well as
 551  * possible, all <emphasis>single modifier</emphasis> combinations
 552  * that could affect the key for any combination of modifiers will
 553  * be returned in @consumed_modifiers; multi-modifier combinations
 554  * are returned only when actually found in @state. When you store
 555  * accelerators, you should always store them with consumed modifiers
 556  * removed. Store <literal>&lt;Control&gt;plus</literal>,
 557  * not <literal>&lt;Control&gt;&lt;Shift&gt;plus</literal>,
 558  * </para></note>
 559  *
 560  * Return value: %TRUE if there was a keyval bound to the keycode/state/group
 561  **/
 562 gboolean
 563 gdk_keymap_translate_keyboard_state (GdkKeymap       *keymap,
 564                                      guint            hardware_keycode,
 565                                      GdkModifierType  state,
 566                                      gint             group,
 567                                      guint           *keyval,
 568                                      gint            *effective_group,
 569                                      gint            *level,
 570                                      GdkModifierType *consumed_modifiers)
 571 {
 572   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);
 573
 574   return GDK_KEYMAP_GET_CLASS (keymap)->translate_keyboard_state (keymap,
 575                                                                   hardware_keycode,
 576                                                                   state,
 577                                                                   group,
 578                                                                   keyval,
 579                                                                   effective_group,
 580                                                                   level,
 581                                                                   consumed_modifiers);
 582 }
 583
 584 /**
 585  * gdk_keymap_add_virtual_modifiers:
 586  * @keymap: a #GdkKeymap
 587  * @state: (out): pointer to the modifier mask to change
 588  *
 589  * Adds virtual modifiers (i.e. Super, Hyper and Meta) which correspond
 590  * to the real modifiers (i.e Mod2, Mod3, ...) in @modifiers.
 591  * are set in @state to their non-virtual counterparts (i.e. Mod2,
 592  * Mod3,...) and set the corresponding bits in @state.
 593  *
 594  * GDK already does this before delivering key events, but for
 595  * compatibility reasons, it only sets the first virtual modifier
 596  * it finds, whereas this function sets all matching virtual modifiers.
 597  *
 598  * This function is useful when matching key events against
 599  * accelerators.
 600  *
 601  * Since: 2.20
 602  */
 603 void
 604 gdk_keymap_add_virtual_modifiers (GdkKeymap       *keymap,
 605                                   GdkModifierType *state)
 606 {
 607   g_return_if_fail (GDK_IS_KEYMAP (keymap));
 608
 609   GDK_KEYMAP_GET_CLASS (keymap)->add_virtual_modifiers (keymap, state);
 610 }
 611
 612 /**
 613  * gdk_keymap_map_virtual_modifiers:
 614  * @keymap: a #GdkKeymap
 615  * @state: (out): pointer to the modifier state to map
 616  *
 617  * Maps the virtual modifiers (i.e. Super, Hyper and Meta) which
 618  * are set in @state to their non-virtual counterparts (i.e. Mod2,
 619  * Mod3,...) and set the corresponding bits in @state.
 620  *
 621  * This function is useful when matching key events against
 622  * accelerators.
 623  *
 624  * Returns: %TRUE if no virtual modifiers were mapped to the
 625  *     same non-virtual modifier. Note that %FALSE is also returned
 626  *     if a virtual modifier is mapped to a non-virtual modifier that
 627  *     was already set in @state.
 628  *
 629  * Since: 2.20
 630  */
 631 gboolean
 632 gdk_keymap_map_virtual_modifiers (GdkKeymap       *keymap,
 633                                   GdkModifierType *state)
 634 {
 635   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);
 636
 637   return GDK_KEYMAP_GET_CLASS(keymap)->map_virtual_modifiers (keymap, state);
 638 }
 639
 640 static GdkModifierType
 641 gdk_keymap_real_get_modifier_mask (GdkKeymap         *keymap,
 642                                    GdkModifierIntent  intent)
 643 {
 644   switch (intent)
 645     {
 646     case GDK_MODIFIER_INTENT_PRIMARY_ACCELERATOR:
 647       return GDK_CONTROL_MASK;
 648
 649     case GDK_MODIFIER_INTENT_CONTEXT_MENU:
 650       return 0;
 651
 652     case GDK_MODIFIER_INTENT_EXTEND_SELECTION:
 653       return GDK_SHIFT_MASK;
 654
 655     case GDK_MODIFIER_INTENT_MODIFY_SELECTION:
 656       return GDK_CONTROL_MASK;
 657
 658     case GDK_MODIFIER_INTENT_NO_TEXT_INPUT:
 659       return GDK_MOD1_MASK | GDK_CONTROL_MASK;
 660
 661     case GDK_MODIFIER_INTENT_SHIFT_GROUP:
 662       return 0;
 663
 664     default:
 665       g_return_val_if_reached (0);
 666     }
 667 }
 668
 669 /**
 670  * gdk_keymap_get_modifier_mask:
 671  * @keymap: a #GdkKeymap
 672  * @intent: the use case for the modifier mask
 673  *
 674  * Returns the modifier mask the @keymap's windowing system backend
 675  * uses for a particular purpose.
 676  *
 677  * Note that this function always returns real hardware modifiers, not
 678  * virtual ones (e.g. it will return #GDK_MOD1_MASK rather than
 679  * #GDK_META_MASK if the backend maps MOD1 to META), so there are use
 680  * cases where the return value of this function has to be transformed
 681  * by gdk_keymap_add_virtual_modifiers() in order to contain the
 682  * expected result.
 683  *
 684  * Returns: the modifier mask used for @intent.
 685  *
 686  * Since: 3.4
 687  **/
 688 GdkModifierType
 689 gdk_keymap_get_modifier_mask (GdkKeymap         *keymap,
 690                               GdkModifierIntent  intent)
 691 {
 692   g_return_val_if_fail (GDK_IS_KEYMAP (keymap), 0);
 693
 694   return GDK_KEYMAP_GET_CLASS (keymap)->get_modifier_mask (keymap, intent);
 695 }
 696
 697
 698 /**
 699  * gdk_keyval_name:
 700  * @keyval: a key value
 701  *
 702  * Converts a key value into a symbolic name.
 703  *
 704  * The names are the same as those in the
 705  * <filename>&lt;gdk/gdkkeysyms.h&gt;</filename> header file
 706  * but without the leading "GDK_KEY_".
 707  *
 708  * Return value: (transfer none): a string containing the name of the key,
 709  *     or %NULL if @keyval is not a valid key. The string should not be
 710  *     modified.
 711  */
 712 gchar *
 713 gdk_keyval_name (guint keyval)
 714 {
 715   GdkDisplayManager *manager = gdk_display_manager_get ();
 716
 717   return GDK_DISPLAY_MANAGER_GET_CLASS (manager)->get_keyval_name (manager,
 718                                                                    keyval);
 719 }
 720
 721 /**
 722  * gdk_keyval_from_name:
 723  * @keyval_name: a key name
 724  *
 725  * Converts a key name to a key value.
 726  *
 727  * The names are the same as those in the
 728  * <filename>&lt;gdk/gdkkeysyms.h&gt;</filename> header file
 729  * but without the leading "GDK_KEY_".
 730  *
 731  * Returns: the corresponding key value, or %GDK_KEY_VoidSymbol
 732  *     if the key name is not a valid key
 733  */
 734 guint
 735 gdk_keyval_from_name (const gchar *keyval_name)
 736 {
 737   GdkDisplayManager *manager = gdk_display_manager_get ();
 738
 739   return GDK_DISPLAY_MANAGER_GET_CLASS (manager)->lookup_keyval (manager,
 740                                                                  keyval_name);
 741 }
 742
 743 void
 744 _gdk_display_manager_real_keyval_convert_case (GdkDisplayManager *manager,
 745                                                guint              symbol,
 746                                                guint             *lower,
 747                                                guint             *upper)
 748 {
 749   guint xlower = symbol;
 750   guint xupper = symbol;
 751
 752   /* Check for directly encoded 24-bit UCS characters: */
 753   if ((symbol & 0xff000000) == 0x01000000)
 754     {
 755       if (lower)
 756         *lower = gdk_unicode_to_keyval (g_unichar_tolower (symbol & 0x00ffffff));
 757       if (upper)
 758         *upper = gdk_unicode_to_keyval (g_unichar_toupper (symbol & 0x00ffffff));
 759       return;
 760     }
 761
 762   switch (symbol >> 8)
 763     {
 764     case 0: /* Latin 1 */
 765       if ((symbol >= GDK_KEY_A) && (symbol <= GDK_KEY_Z))
 766         xlower += (GDK_KEY_a - GDK_KEY_A);
 767       else if ((symbol >= GDK_KEY_a) && (symbol <= GDK_KEY_z))
 768         xupper -= (GDK_KEY_a - GDK_KEY_A);
 769       else if ((symbol >= GDK_KEY_Agrave) && (symbol <= GDK_KEY_Odiaeresis))
 770         xlower += (GDK_KEY_agrave - GDK_KEY_Agrave);
 771       else if ((symbol >= GDK_KEY_agrave) && (symbol <= GDK_KEY_odiaeresis))
 772         xupper -= (GDK_KEY_agrave - GDK_KEY_Agrave);
 773       else if ((symbol >= GDK_KEY_Ooblique) && (symbol <= GDK_KEY_Thorn))
 774         xlower += (GDK_KEY_oslash - GDK_KEY_Ooblique);
 775       else if ((symbol >= GDK_KEY_oslash) && (symbol <= GDK_KEY_thorn))
 776         xupper -= (GDK_KEY_oslash - GDK_KEY_Ooblique);
 777       break;
 778
 779     case 1: /* Latin 2 */
 780       /* Assume the KeySym is a legal value (ignore discontinuities) */
 781       if (symbol == GDK_KEY_Aogonek)
 782         xlower = GDK_KEY_aogonek;
 783       else if (symbol >= GDK_KEY_Lstroke && symbol <= GDK_KEY_Sacute)
 784         xlower += (GDK_KEY_lstroke - GDK_KEY_Lstroke);
 785       else if (symbol >= GDK_KEY_Scaron && symbol <= GDK_KEY_Zacute)
 786         xlower += (GDK_KEY_scaron - GDK_KEY_Scaron);
 787       else if (symbol >= GDK_KEY_Zcaron && symbol <= GDK_KEY_Zabovedot)
 788         xlower += (GDK_KEY_zcaron - GDK_KEY_Zcaron);
 789       else if (symbol == GDK_KEY_aogonek)
 790         xupper = GDK_KEY_Aogonek;
 791       else if (symbol >= GDK_KEY_lstroke && symbol <= GDK_KEY_sacute)
 792         xupper -= (GDK_KEY_lstroke - GDK_KEY_Lstroke);
 793       else if (symbol >= GDK_KEY_scaron && symbol <= GDK_KEY_zacute)
 794         xupper -= (GDK_KEY_scaron - GDK_KEY_Scaron);
 795       else if (symbol >= GDK_KEY_zcaron && symbol <= GDK_KEY_zabovedot)
 796         xupper -= (GDK_KEY_zcaron - GDK_KEY_Zcaron);
 797       else if (symbol >= GDK_KEY_Racute && symbol <= GDK_KEY_Tcedilla)
 798         xlower += (GDK_KEY_racute - GDK_KEY_Racute);
 799       else if (symbol >= GDK_KEY_racute && symbol <= GDK_KEY_tcedilla)
 800         xupper -= (GDK_KEY_racute - GDK_KEY_Racute);
 801       break;
 802
 803     case 2: /* Latin 3 */
 804       /* Assume the KeySym is a legal value (ignore discontinuities) */
 805       if (symbol >= GDK_KEY_Hstroke && symbol <= GDK_KEY_Hcircumflex)
 806         xlower += (GDK_KEY_hstroke - GDK_KEY_Hstroke);
 807       else if (symbol >= GDK_KEY_Gbreve && symbol <= GDK_KEY_Jcircumflex)
 808         xlower += (GDK_KEY_gbreve - GDK_KEY_Gbreve);
 809       else if (symbol >= GDK_KEY_hstroke && symbol <= GDK_KEY_hcircumflex)
 810         xupper -= (GDK_KEY_hstroke - GDK_KEY_Hstroke);
 811       else if (symbol >= GDK_KEY_gbreve && symbol <= GDK_KEY_jcircumflex)
 812         xupper -= (GDK_KEY_gbreve - GDK_KEY_Gbreve);
 813       else if (symbol >= GDK_KEY_Cabovedot && symbol <= GDK_KEY_Scircumflex)
 814         xlower += (GDK_KEY_cabovedot - GDK_KEY_Cabovedot);
 815       else if (symbol >= GDK_KEY_cabovedot && symbol <= GDK_KEY_scircumflex)
 816         xupper -= (GDK_KEY_cabovedot - GDK_KEY_Cabovedot);
 817       break;
 818
 819     case 3: /* Latin 4 */
 820       /* Assume the KeySym is a legal value (ignore discontinuities) */
 821       if (symbol >= GDK_KEY_Rcedilla && symbol <= GDK_KEY_Tslash)
 822         xlower += (GDK_KEY_rcedilla - GDK_KEY_Rcedilla);
 823       else if (symbol >= GDK_KEY_rcedilla && symbol <= GDK_KEY_tslash)
 824         xupper -= (GDK_KEY_rcedilla - GDK_KEY_Rcedilla);
 825       else if (symbol == GDK_KEY_ENG)
 826         xlower = GDK_KEY_eng;
 827       else if (symbol == GDK_KEY_eng)
 828         xupper = GDK_KEY_ENG;
 829       else if (symbol >= GDK_KEY_Amacron && symbol <= GDK_KEY_Umacron)
 830         xlower += (GDK_KEY_amacron - GDK_KEY_Amacron);
 831       else if (symbol >= GDK_KEY_amacron && symbol <= GDK_KEY_umacron)
 832         xupper -= (GDK_KEY_amacron - GDK_KEY_Amacron);
 833       break;
 834
 835     case 6: /* Cyrillic */
 836       /* Assume the KeySym is a legal value (ignore discontinuities) */
 837       if (symbol >= GDK_KEY_Serbian_DJE && symbol <= GDK_KEY_Serbian_DZE)
 838         xlower -= (GDK_KEY_Serbian_DJE - GDK_KEY_Serbian_dje);
 839       else if (symbol >= GDK_KEY_Serbian_dje && symbol <= GDK_KEY_Serbian_dze)
 840         xupper += (GDK_KEY_Serbian_DJE - GDK_KEY_Serbian_dje);
 841       else if (symbol >= GDK_KEY_Cyrillic_YU && symbol <= GDK_KEY_Cyrillic_HARDSIGN)
 842         xlower -= (GDK_KEY_Cyrillic_YU - GDK_KEY_Cyrillic_yu);
 843       else if (symbol >= GDK_KEY_Cyrillic_yu && symbol <= GDK_KEY_Cyrillic_hardsign)
 844         xupper += (GDK_KEY_Cyrillic_YU - GDK_KEY_Cyrillic_yu);
 845       break;
 846
 847     case 7: /* Greek */
 848       /* Assume the KeySym is a legal value (ignore discontinuities) */
 849       if (symbol >= GDK_KEY_Greek_ALPHAaccent && symbol <= GDK_KEY_Greek_OMEGAaccent)
 850         xlower += (GDK_KEY_Greek_alphaaccent - GDK_KEY_Greek_ALPHAaccent);
 851       else if (symbol >= GDK_KEY_Greek_alphaaccent && symbol <= GDK_KEY_Greek_omegaaccent &&
 852                symbol != GDK_KEY_Greek_iotaaccentdieresis &&
 853                symbol != GDK_KEY_Greek_upsilonaccentdieresis)
 854         xupper -= (GDK_KEY_Greek_alphaaccent - GDK_KEY_Greek_ALPHAaccent);
 855       else if (symbol >= GDK_KEY_Greek_ALPHA && symbol <= GDK_KEY_Greek_OMEGA)
 856         xlower += (GDK_KEY_Greek_alpha - GDK_KEY_Greek_ALPHA);
 857       else if (symbol >= GDK_KEY_Greek_alpha && symbol <= GDK_KEY_Greek_omega &&
 858                symbol != GDK_KEY_Greek_finalsmallsigma)
 859         xupper -= (GDK_KEY_Greek_alpha - GDK_KEY_Greek_ALPHA);
 860       break;
 861     }
 862
 863   if (lower)
 864     *lower = xlower;
 865   if (upper)
 866     *upper = xupper;
 867 }