gdkkeys.c 29.6 KB
Newer Older
Cody Russell's avatar
Cody Russell committed
1
/* GDK - The GIMP Drawing Kit
Havoc Pennington's avatar
Havoc Pennington committed
2 3 4 5 6 7 8 9 10 11 12 13 14
 * Copyright (C) 2000 Red Hat, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
Javier Jardon's avatar
Javier Jardon committed
15
 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
Havoc Pennington's avatar
Havoc Pennington committed
16 17 18 19 20 21
 */

/*
 * Modified by the GTK+ Team and others 1997-2000.  See the AUTHORS
 * file for a list of people on the GTK+ Team.  See the ChangeLog
 * files for a list of changes.  These files are distributed with
22
 * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
Havoc Pennington's avatar
Havoc Pennington committed
23 24
 */

25
#include "config.h"
Havoc Pennington's avatar
Havoc Pennington committed
26

27
#include "gdkkeysyms.h"
28
#include "gdkkeysprivate.h"
29
#include "gdkdisplay.h"
30
#include "gdkdisplaymanagerprivate.h"
31

32

33 34 35 36 37 38 39 40 41 42
/**
 * SECTION:keys
 * @Short_description: Functions for manipulating keyboard codes
 * @Title: Key Values
 *
 * Key values are the codes which are sent whenever a key is pressed or released.
 * They appear in the #GdkEventKey.keyval field of the
 * #GdkEventKey structure, which is passed to signal handlers for the
 * #GtkWidget::key-press-event and #GtkWidget::key-release-event signals.
 * The complete list of key values can be found in the
43
 * `gdk/gdkkeysyms.h` header file.
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
 *
 * Key values are regularly updated from the upstream X.org X11 implementation,
 * so new values are added regularly. They will be prefixed with GDK_KEY_ rather
 * than XF86XK_ or XK_ (for older symbols).
 *
 * Key values can be converted into a string representation using
 * gdk_keyval_name(). The reverse function, converting a string to a key value,
 * is provided by gdk_keyval_from_name().
 *
 * The case of key values can be determined using gdk_keyval_is_upper() and
 * gdk_keyval_is_lower(). Key values can be converted to upper or lower case
 * using gdk_keyval_to_upper() and gdk_keyval_to_lower().
 *
 * When it makes sense, key values can be converted to and from
 * Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
 *
60 61
 * # Groups # {#key-group-explanation}
 *
62 63 64 65 66 67 68
 * One #GdkKeymap object exists for each user display. gdk_keymap_get_default()
 * returns the #GdkKeymap for the default display; to obtain keymaps for other
 * displays, use gdk_keymap_get_for_display(). A keymap
 * is a mapping from #GdkKeymapKey to key values. You can think of a #GdkKeymapKey
 * as a representation of a symbol printed on a physical keyboard key. That is, it
 * contains three pieces of information. First, it contains the hardware keycode;
 * this is an identifying number for a physical key. Second, it contains the
69
 * “level” 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 72
 * with the number “1“ on it also has the exclamation point (”!”) character on
 * it. The level indicates whether to use the “1” or the “!” symbol.  The letter
73 74 75 76 77 78 79 80 81 82
 * keys are considered to have a lowercase letter at level 0, and an uppercase
 * letter at level 1, though only the uppercase letter is printed.  Third, the
 * #GdkKeymapKey contains a group; groups are not used on standard US keyboards,
 * but are used in many other countries. On a keyboard with groups, there can be 3
 * or 4 symbols printed on a single key. The group indicates movement in a
 * horizontal direction. Usually groups are used for two different languages.  In
 * group 0, a key might have two English characters, and in group 1 it might have
 * two Hebrew characters. The Hebrew characters will be printed on the key next to
 * the English characters.
 *
83
 * In order to use a keymap to interpret a key event, it’s necessary to first
84 85 86 87 88 89
 * convert the keyboard state into an effective group and level. This is done via a
 * set of rules that varies widely according to type of keyboard and user
 * configuration. The function gdk_keymap_translate_keyboard_state() accepts a
 * keyboard state -- consisting of hardware keycode pressed, active modifiers, and
 * active group -- applies the appropriate rules, and returns the group/level to be
 * 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 92 93 94 95 96 97
 * differ from the effective group used for keymap lookups because some keys don't
 * have multiple groups - e.g. the Enter key is always in group 0 regardless of
 * keyboard state.
 *
 * Note that gdk_keymap_translate_keyboard_state() also returns the keyval, i.e. it
 * goes ahead and performs the keymap lookup in addition to telling you which
 * 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 100 101 102
 * gdk_keymap_translate_keyboard_state() just to get the keyval.
 */


103 104
enum {
  DIRECTION_CHANGED,
105
  KEYS_CHANGED,
106
  STATE_CHANGED,
107 108 109
  LAST_SIGNAL
};

110 111 112 113 114

static GdkModifierType gdk_keymap_real_get_modifier_mask (GdkKeymap         *keymap,
                                                          GdkModifierIntent  intent);


115 116
static guint signals[LAST_SIGNAL] = { 0 };

Matthias Clasen's avatar
Matthias Clasen committed
117
G_DEFINE_TYPE (GdkKeymap, gdk_keymap, G_TYPE_OBJECT)
Havoc Pennington's avatar
Havoc Pennington committed
118 119 120 121 122 123

static void
gdk_keymap_class_init (GdkKeymapClass *klass)
{
  GObjectClass *object_class = G_OBJECT_CLASS (klass);

124 125
  klass->get_modifier_mask = gdk_keymap_real_get_modifier_mask;

126 127 128
  /**
   * GdkKeymap::direction-changed:
   * @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 134
   *
   * Since: 2.0
   */
135
  signals[DIRECTION_CHANGED] =
136
    g_signal_new (g_intern_static_string ("direction-changed"),
Tim Janik's avatar
Tim Janik committed
137 138 139 140 141 142 143
		  G_OBJECT_CLASS_TYPE (object_class),
		  G_SIGNAL_RUN_LAST,
		  G_STRUCT_OFFSET (GdkKeymapClass, direction_changed),
		  NULL, NULL,
		  g_cclosure_marshal_VOID__VOID,
		  G_TYPE_NONE,
		  0);
144 145 146 147
  /**
   * GdkKeymap::keys-changed:
   * @keymap: the object on which the signal is emitted
   *
148
   * The ::keys-changed signal is emitted when the mapping represented by
149 150 151 152
   * @keymap changes.
   *
   * Since: 2.2
   */
153
  signals[KEYS_CHANGED] =
154
    g_signal_new (g_intern_static_string ("keys-changed"),
155 156
		  G_OBJECT_CLASS_TYPE (object_class),
		  G_SIGNAL_RUN_LAST,
157
		  G_STRUCT_OFFSET (GdkKeymapClass, keys_changed),
158 159 160 161
		  NULL, NULL,
		  g_cclosure_marshal_VOID__VOID,
		  G_TYPE_NONE,
		  0);
162 163 164 165 166 167

  /**
   * GdkKeymap::state-changed:
   * @keymap: the object on which the signal is emitted
   *
   * The ::state-changed signal is emitted when the state of the
168 169
   * keyboard changes, e.g when Caps Lock is turned on or off.
   * See gdk_keymap_get_caps_lock_state().
170 171 172 173
   *
   * Since: 2.16
   */
  signals[STATE_CHANGED] =
174
    g_signal_new (g_intern_static_string ("state_changed"),
175 176 177 178 179
                  G_OBJECT_CLASS_TYPE (object_class),
                  G_SIGNAL_RUN_LAST,
                  G_STRUCT_OFFSET (GdkKeymapClass, state_changed),
                  NULL, NULL,
                  g_cclosure_marshal_VOID__VOID,
180
                  G_TYPE_NONE,
181
                  0);
Havoc Pennington's avatar
Havoc Pennington committed
182 183
}

Matthias Clasen's avatar
Matthias Clasen committed
184 185 186 187 188
static void
gdk_keymap_init (GdkKeymap *keymap)
{
}

Havoc Pennington's avatar
Havoc Pennington committed
189 190 191
/* Other key-handling stuff
 */

192 193 194 195 196 197 198 199 200
/**
 * gdk_keyval_to_upper:
 * @keyval: a key value.
 *
 * Converts a key value to upper case, if applicable.
 *
 * Returns: the upper case form of @keyval, or @keyval itself if it is already
 *   in upper case or it is not subject to case conversion.
 */
Havoc Pennington's avatar
Havoc Pennington committed
201 202 203 204
guint
gdk_keyval_to_upper (guint keyval)
{
  guint result;
205

Havoc Pennington's avatar
Havoc Pennington committed
206 207 208 209 210
  gdk_keyval_convert_case (keyval, NULL, &result);

  return result;
}

211 212 213 214 215 216 217 218 219
/**
 * gdk_keyval_to_lower:
 * @keyval: a key value.
 *
 * Converts a key value to lower case, if applicable.
 *
 * Returns: the lower case form of @keyval, or @keyval itself if it is already
 *  in lower case or it is not subject to case conversion.
 */
Havoc Pennington's avatar
Havoc Pennington committed
220 221 222 223
guint
gdk_keyval_to_lower (guint keyval)
{
  guint result;
224

Havoc Pennington's avatar
Havoc Pennington committed
225 226 227 228 229
  gdk_keyval_convert_case (keyval, &result, NULL);

  return result;
}

230 231 232 233 234 235 236 237 238
/**
 * gdk_keyval_is_upper:
 * @keyval: a key value.
 *
 * Returns %TRUE if the given key value is in upper case.
 *
 * Returns: %TRUE if @keyval is in upper case, or if @keyval is not subject to
 *  case conversion.
 */
Havoc Pennington's avatar
Havoc Pennington committed
239 240 241 242 243 244
gboolean
gdk_keyval_is_upper (guint keyval)
{
  if (keyval)
    {
      guint upper_val = 0;
245

Havoc Pennington's avatar
Havoc Pennington committed
246 247 248 249 250 251
      gdk_keyval_convert_case (keyval, NULL, &upper_val);
      return upper_val == keyval;
    }
  return FALSE;
}

252 253 254 255 256 257 258 259 260
/**
 * gdk_keyval_is_lower:
 * @keyval: a key value.
 *
 * Returns %TRUE if the given key value is in lower case.
 *
 * Returns: %TRUE if @keyval is in lower case, or if @keyval is not
 *   subject to case conversion.
 */
Havoc Pennington's avatar
Havoc Pennington committed
261 262 263 264 265 266
gboolean
gdk_keyval_is_lower (guint keyval)
{
  if (keyval)
    {
      guint lower_val = 0;
267

Havoc Pennington's avatar
Havoc Pennington committed
268 269 270 271 272
      gdk_keyval_convert_case (keyval, &lower_val, NULL);
      return lower_val == keyval;
    }
  return FALSE;
}
273

274
/**
275 276 277
 * gdk_keymap_get_default:
 *
 * Returns the #GdkKeymap attached to the default display.
278
 *
279
 * Returns: (transfer none): the #GdkKeymap attached to the default display.
280
 */
281 282 283
GdkKeymap*
gdk_keymap_get_default (void)
{
Owen Taylor's avatar
Owen Taylor committed
284
  return gdk_keymap_get_for_display (gdk_display_get_default ());
285
}
286 287 288

/**
 * gdk_keymap_get_direction:
289
 * @keymap: a #GdkKeymap
290 291 292 293 294 295 296 297 298 299
 *
 * Returns the direction of effective layout of the keymap.
 *
 * Returns: %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL
 *   if it can determine the direction. %PANGO_DIRECTION_NEUTRAL
 *   otherwise.
 **/
PangoDirection
gdk_keymap_get_direction (GdkKeymap *keymap)
{
300 301 302
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), PANGO_DIRECTION_LTR);

  return GDK_KEYMAP_GET_CLASS (keymap)->get_direction (keymap);
303 304 305 306
}

/**
 * gdk_keymap_have_bidi_layouts:
307
 * @keymap: a #GdkKeymap
308 309 310 311 312 313 314 315 316 317 318
 *
 * Determines if keyboard layouts for both right-to-left and left-to-right
 * languages are in use.
 *
 * Returns: %TRUE if there are layouts in both directions, %FALSE otherwise
 *
 * Since: 2.12
 **/
gboolean
gdk_keymap_have_bidi_layouts (GdkKeymap *keymap)
{
319 320 321
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);

  return GDK_KEYMAP_GET_CLASS (keymap)->have_bidi_layouts (keymap);
322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
}

/**
 * gdk_keymap_get_caps_lock_state:
 * @keymap: a #GdkKeymap
 *
 * Returns whether the Caps Lock modifer is locked.
 *
 * Returns: %TRUE if Caps Lock is on
 *
 * Since: 2.16
 */
gboolean
gdk_keymap_get_caps_lock_state (GdkKeymap *keymap)
{
337 338 339
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);

  return GDK_KEYMAP_GET_CLASS (keymap)->get_caps_lock_state (keymap);
340 341 342 343 344 345 346 347 348 349 350 351 352 353 354
}

/**
 * gdk_keymap_get_num_lock_state:
 * @keymap: a #GdkKeymap
 *
 * Returns whether the Num Lock modifer is locked.
 *
 * Returns: %TRUE if Num Lock is on
 *
 * Since: 3.0
 */
gboolean
gdk_keymap_get_num_lock_state (GdkKeymap *keymap)
{
355 356 357
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);

  return GDK_KEYMAP_GET_CLASS (keymap)->get_num_lock_state (keymap);
358 359
}

360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377
/**
 * gdk_keymap_get_scroll_lock_state:
 * @keymap: a #GdkKeymap
 *
 * Returns whether the Scroll Lock modifer is locked.
 *
 * Returns: %TRUE if Scroll Lock is on
 *
 * Since: 3.18
 */
gboolean
gdk_keymap_get_scroll_lock_state (GdkKeymap *keymap)
{
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);

  return GDK_KEYMAP_GET_CLASS (keymap)->get_scroll_lock_state (keymap);
}

378 379 380 381 382 383 384 385
/**
 * gdk_keymap_get_modifier_state:
 * @keymap: a #GdkKeymap
 *
 * Returns the current modifier state.
 *
 * Returns: the current modifier state.
 *
386
 * Since: 3.4
387 388 389 390 391 392 393 394 395 396 397 398
 */
guint
gdk_keymap_get_modifier_state (GdkKeymap *keymap)
{
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);

  if (GDK_KEYMAP_GET_CLASS (keymap)->get_modifier_state)
    return GDK_KEYMAP_GET_CLASS (keymap)->get_modifier_state (keymap);

  return 0;
}

399 400
/**
 * gdk_keymap_get_entries_for_keyval:
401
 * @keymap: a #GdkKeymap
402
 * @keyval: a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc.
403 404 405
 * @keys: (out) (array length=n_keys) (transfer full): return location
 *     for an array of #GdkKeymapKey
 * @n_keys: return location for number of elements in returned array
406 407 408 409 410 411 412 413 414 415 416 417 418
 *
 * Obtains a list of keycode/group/level combinations that will
 * generate @keyval. Groups and levels are two kinds of keyboard mode;
 * in general, the level determines whether the top or bottom symbol
 * on a key is used, and the group determines whether the left or
 * right symbol is used. On US keyboards, the shift key changes the
 * keyboard level, and there are no groups. A group switch key might
 * convert a keyboard between Hebrew to English modes, for example.
 * #GdkEventKey contains a %group field that indicates the active
 * keyboard group. The level is computed from the modifier mask.
 * The returned array should be freed
 * with g_free().
 *
419
 * Returns: %TRUE if keys were found and returned
420 421 422 423 424 425 426
 **/
gboolean
gdk_keymap_get_entries_for_keyval (GdkKeymap     *keymap,
                                   guint          keyval,
                                   GdkKeymapKey **keys,
                                   gint          *n_keys)
{
427
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);
428 429 430
  g_return_val_if_fail (keys != NULL, FALSE);
  g_return_val_if_fail (n_keys != NULL, FALSE);
  g_return_val_if_fail (keyval != 0, FALSE);
431 432 433

  return GDK_KEYMAP_GET_CLASS (keymap)->get_entries_for_keyval (keymap, keyval,
                                                                keys, n_keys);
434 435 436 437
}

/**
 * gdk_keymap_get_entries_for_keycode:
438
 * @keymap: a #GdkKeymap
439
 * @hardware_keycode: a keycode
440
 * @keys: (out) (array length=n_entries) (transfer full) (optional): return
441
 *     location for array of #GdkKeymapKey, or %NULL
442
 * @keyvals: (out) (array length=n_entries) (transfer full) (optional): return
443
 *     location for array of keyvals, or %NULL
444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461
 * @n_entries: length of @keys and @keyvals
 *
 * Returns the keyvals bound to @hardware_keycode.
 * The Nth #GdkKeymapKey in @keys is bound to the Nth
 * keyval in @keyvals. Free the returned arrays with g_free().
 * When a keycode is pressed by the user, the keyval from
 * this list of entries is selected by considering the effective
 * keyboard group and level. See gdk_keymap_translate_keyboard_state().
 *
 * Returns: %TRUE if there were any entries
 **/
gboolean
gdk_keymap_get_entries_for_keycode (GdkKeymap     *keymap,
                                    guint          hardware_keycode,
                                    GdkKeymapKey **keys,
                                    guint        **keyvals,
                                    gint          *n_entries)
{
462
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);
463
  g_return_val_if_fail (n_entries != NULL, FALSE);
464 465 466

  return GDK_KEYMAP_GET_CLASS (keymap)->get_entries_for_keycode (keymap, hardware_keycode,
                                                                 keys, keyvals, n_entries);
467 468 469 470
}

/**
 * gdk_keymap_lookup_key:
471
 * @keymap: a #GdkKeymap
472 473 474 475 476 477 478 479
 * @key: a #GdkKeymapKey with keycode, group, and level initialized
 *
 * Looks up the keyval mapped to a keycode/group/level triplet.
 * If no keyval is bound to @key, returns 0. For normal user input,
 * you want to use gdk_keymap_translate_keyboard_state() instead of
 * this function, since the effective group/level may not be
 * the same as the current keyboard state.
 *
480
 * Returns: a keyval, or 0 if none was mapped to the given @key
481 482 483 484 485
 **/
guint
gdk_keymap_lookup_key (GdkKeymap          *keymap,
                       const GdkKeymapKey *key)
{
486
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), 0);
487
  g_return_val_if_fail (key != NULL, 0);
488 489

  return GDK_KEYMAP_GET_CLASS (keymap)->lookup_key (keymap, key);
490 491 492 493
}

/**
 * gdk_keymap_translate_keyboard_state:
494
 * @keymap: a #GdkKeymap
495 496 497 498
 * @hardware_keycode: a keycode
 * @state: a modifier state
 * @group: active keyboard group
 * @keyval: (out) (allow-none): return location for keyval, or %NULL
499 500 501 502 503
 * @effective_group: (out) (allow-none): return location for effective
 *     group, or %NULL
 * @level: (out) (allow-none): return location for level, or %NULL
 * @consumed_modifiers: (out) (allow-none): return location for modifiers
 *     that were used to determine the group or level, or %NULL
504 505 506 507
 *
 * Translates the contents of a #GdkEventKey into a keyval, effective
 * group, and level. Modifiers that affected the translation and
 * are thus unavailable for application use are returned in
508
 * @consumed_modifiers.
509
 * See [Groups][key-group-explanation] for an explanation of
510
 * groups and levels. The @effective_group is the group that was
511 512 513
 * actually used for the translation; some keys such as Enter are not
 * affected by the active keyboard group. The @level is derived from
 * @state. For convenience, #GdkEventKey already contains the translated
514
 * keyval, so this function isn’t as useful as you might think.
515
 *
516 517 518 519
 * @consumed_modifiers gives modifiers that should be masked outfrom @state
 * when comparing this key press to a hot key. For instance, on a US keyboard,
 * the `plus` symbol is shifted, so when comparing a key press to a
 * `<Control>plus` accelerator `<Shift>` should be masked out.
520
 *
521
 * |[<!-- language="C" -->
522
 * // We want to ignore irrelevant modifiers like ScrollLock
523
 * #define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
524 525
 * gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode,
 *                                      event->state, event->group,
526
 *                                      &keyval, NULL, NULL, &consumed);
527
 * if (keyval == GDK_PLUS &&
528
 *     (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
529
 *   // Control was pressed
530
 * ]|
531
 * 
532 533 534
 * An older interpretation @consumed_modifiers was that it contained
 * all modifiers that might affect the translation of the key;
 * this allowed accelerators to be stored with irrelevant consumed
535
 * modifiers, by doing:
536
 * |[<!-- language="C" -->
537
 * // XXX Don’t do this XXX
538
 * if (keyval == accel_keyval &&
539
 *     (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
540
 *   // Accelerator was pressed
541
 * ]|
542
 *
543
 * However, this did not work if multi-modifier combinations were
544 545 546 547 548 549 550 551
 * used in the keymap, since, for instance, `<Control>` would be
 * masked out even if only `<Control><Alt>` was used in the keymap.
 * To support this usage as well as well as possible, all single
 * modifier combinations that could affect the key for any combination
 * of modifiers will be returned in @consumed_modifiers; multi-modifier
 * combinations are returned only when actually found in @state. When
 * you store accelerators, you should always store them with consumed
 * modifiers removed. Store `<Control>plus`, not `<Control><Shift>plus`,
552
 *
553
 * Returns: %TRUE if there was a keyval bound to the keycode/state/group
554 555 556 557 558 559 560 561 562 563 564
 **/
gboolean
gdk_keymap_translate_keyboard_state (GdkKeymap       *keymap,
                                     guint            hardware_keycode,
                                     GdkModifierType  state,
                                     gint             group,
                                     guint           *keyval,
                                     gint            *effective_group,
                                     gint            *level,
                                     GdkModifierType *consumed_modifiers)
{
565 566 567
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);

  return GDK_KEYMAP_GET_CLASS (keymap)->translate_keyboard_state (keymap,
568 569 570 571 572 573 574 575 576 577 578 579
								  hardware_keycode,
								  state,
								  group,
								  keyval,
								  effective_group,
								  level,
								  consumed_modifiers);
}

/**
 * gdk_keymap_add_virtual_modifiers:
 * @keymap: a #GdkKeymap
580
 * @state: (inout): pointer to the modifier mask to change
581
 *
582 583 584
 * Maps the non-virtual modifiers (i.e Mod2, Mod3, ...) which are set
 * in @state to the virtual modifiers (i.e. Super, Hyper and Meta) and
 * set the corresponding bits in @state.
585 586 587 588 589 590 591 592 593 594 595 596 597 598
 *
 * GDK already does this before delivering key events, but for
 * compatibility reasons, it only sets the first virtual modifier
 * it finds, whereas this function sets all matching virtual modifiers.
 *
 * This function is useful when matching key events against
 * accelerators.
 *
 * Since: 2.20
 */
void
gdk_keymap_add_virtual_modifiers (GdkKeymap       *keymap,
			          GdkModifierType *state)
{
599 600 601
  g_return_if_fail (GDK_IS_KEYMAP (keymap));

  GDK_KEYMAP_GET_CLASS (keymap)->add_virtual_modifiers (keymap, state);
602 603 604 605 606
}

/**
 * gdk_keymap_map_virtual_modifiers:
 * @keymap: a #GdkKeymap
607
 * @state: (inout): pointer to the modifier state to map
608 609 610 611 612 613 614 615
 *
 * Maps the virtual modifiers (i.e. Super, Hyper and Meta) which
 * are set in @state to their non-virtual counterparts (i.e. Mod2,
 * Mod3,...) and set the corresponding bits in @state.
 *
 * This function is useful when matching key events against
 * accelerators.
 *
Matthias Clasen's avatar
Matthias Clasen committed
616
 * Returns: %FALSE if two virtual modifiers were mapped to the
617 618 619 620 621 622 623 624 625 626
 *     same non-virtual modifier. Note that %FALSE is also returned
 *     if a virtual modifier is mapped to a non-virtual modifier that
 *     was already set in @state.
 *
 * Since: 2.20
 */
gboolean
gdk_keymap_map_virtual_modifiers (GdkKeymap       *keymap,
                                  GdkModifierType *state)
{
627 628
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), FALSE);

629 630
  return GDK_KEYMAP_GET_CLASS(keymap)->map_virtual_modifiers (keymap, state);
}
631

632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652
static GdkModifierType
gdk_keymap_real_get_modifier_mask (GdkKeymap         *keymap,
                                   GdkModifierIntent  intent)
{
  switch (intent)
    {
    case GDK_MODIFIER_INTENT_PRIMARY_ACCELERATOR:
      return GDK_CONTROL_MASK;

    case GDK_MODIFIER_INTENT_CONTEXT_MENU:
      return 0;

    case GDK_MODIFIER_INTENT_EXTEND_SELECTION:
      return GDK_SHIFT_MASK;

    case GDK_MODIFIER_INTENT_MODIFY_SELECTION:
      return GDK_CONTROL_MASK;

    case GDK_MODIFIER_INTENT_NO_TEXT_INPUT:
      return GDK_MOD1_MASK | GDK_CONTROL_MASK;

653 654 655
    case GDK_MODIFIER_INTENT_SHIFT_GROUP:
      return 0;

656 657 658 659
    case GDK_MODIFIER_INTENT_DEFAULT_MOD_MASK:
      return (GDK_SHIFT_MASK   | GDK_CONTROL_MASK | GDK_MOD1_MASK    |
	      GDK_SUPER_MASK   | GDK_HYPER_MASK   | GDK_META_MASK);

660 661 662 663 664 665 666 667 668 669
    default:
      g_return_val_if_reached (0);
    }
}

/**
 * gdk_keymap_get_modifier_mask:
 * @keymap: a #GdkKeymap
 * @intent: the use case for the modifier mask
 *
670
 * Returns the modifier mask the @keymap’s windowing system backend
671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692
 * uses for a particular purpose.
 *
 * Note that this function always returns real hardware modifiers, not
 * virtual ones (e.g. it will return #GDK_MOD1_MASK rather than
 * #GDK_META_MASK if the backend maps MOD1 to META), so there are use
 * cases where the return value of this function has to be transformed
 * by gdk_keymap_add_virtual_modifiers() in order to contain the
 * expected result.
 *
 * Returns: the modifier mask used for @intent.
 *
 * Since: 3.4
 **/
GdkModifierType
gdk_keymap_get_modifier_mask (GdkKeymap         *keymap,
                              GdkModifierIntent  intent)
{
  g_return_val_if_fail (GDK_IS_KEYMAP (keymap), 0);

  return GDK_KEYMAP_GET_CLASS (keymap)->get_modifier_mask (keymap, intent);
}

693
#include "gdkkeynames.c"
694

695 696
/**
 * gdk_keyval_name:
697
 * @keyval: a key value
698 699
 *
 * Converts a key value into a symbolic name.
700
 *
701
 * The names are the same as those in the
702
 * `gdk/gdkkeysyms.h` header file
703
 * but without the leading “GDK_KEY_”.
704
 *
705 706 707
 * Returns: (nullable) (transfer none): a string containing the name
 *     of the key, or %NULL if @keyval is not a valid key. The string
 *     should not be modified.
708
 */
709
gchar *
710 711
gdk_keyval_name (guint keyval)
{
712
  return _gdk_keyval_name (keyval);
713 714
}

715 716 717 718 719 720 721
/**
 * gdk_keyval_from_name:
 * @keyval_name: a key name
 *
 * Converts a key name to a key value.
 *
 * The names are the same as those in the
722
 * `gdk/gdkkeysyms.h` header file
723
 * but without the leading “GDK_KEY_”.
724 725 726 727
 *
 * Returns: the corresponding key value, or %GDK_KEY_VoidSymbol
 *     if the key name is not a valid key
 */
728 729 730
guint
gdk_keyval_from_name (const gchar *keyval_name)
{
731
  return _gdk_keyval_from_name (keyval_name);
732
}
733

734 735 736 737 738 739 740 741 742
/**
 * gdk_keyval_convert_case:
 * @symbol: a keyval
 * @lower: (out): return location for lowercase version of @symbol
 * @upper: (out): return location for uppercase version of @symbol
 *
 * Obtains the upper- and lower-case versions of the keyval @symbol.
 * Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc.
 */
743
void
744 745 746
gdk_keyval_convert_case (guint symbol,
                         guint *lower,
                         guint *upper)
747
{
748 749 750 751
  guint xlower, xupper;

  xlower = symbol;
  xupper = symbol;
752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868

  /* Check for directly encoded 24-bit UCS characters: */
  if ((symbol & 0xff000000) == 0x01000000)
    {
      if (lower)
        *lower = gdk_unicode_to_keyval (g_unichar_tolower (symbol & 0x00ffffff));
      if (upper)
        *upper = gdk_unicode_to_keyval (g_unichar_toupper (symbol & 0x00ffffff));
      return;
    }

  switch (symbol >> 8)
    {
    case 0: /* Latin 1 */
      if ((symbol >= GDK_KEY_A) && (symbol <= GDK_KEY_Z))
        xlower += (GDK_KEY_a - GDK_KEY_A);
      else if ((symbol >= GDK_KEY_a) && (symbol <= GDK_KEY_z))
        xupper -= (GDK_KEY_a - GDK_KEY_A);
      else if ((symbol >= GDK_KEY_Agrave) && (symbol <= GDK_KEY_Odiaeresis))
        xlower += (GDK_KEY_agrave - GDK_KEY_Agrave);
      else if ((symbol >= GDK_KEY_agrave) && (symbol <= GDK_KEY_odiaeresis))
        xupper -= (GDK_KEY_agrave - GDK_KEY_Agrave);
      else if ((symbol >= GDK_KEY_Ooblique) && (symbol <= GDK_KEY_Thorn))
        xlower += (GDK_KEY_oslash - GDK_KEY_Ooblique);
      else if ((symbol >= GDK_KEY_oslash) && (symbol <= GDK_KEY_thorn))
        xupper -= (GDK_KEY_oslash - GDK_KEY_Ooblique);
      break;

    case 1: /* Latin 2 */
      /* Assume the KeySym is a legal value (ignore discontinuities) */
      if (symbol == GDK_KEY_Aogonek)
        xlower = GDK_KEY_aogonek;
      else if (symbol >= GDK_KEY_Lstroke && symbol <= GDK_KEY_Sacute)
        xlower += (GDK_KEY_lstroke - GDK_KEY_Lstroke);
      else if (symbol >= GDK_KEY_Scaron && symbol <= GDK_KEY_Zacute)
        xlower += (GDK_KEY_scaron - GDK_KEY_Scaron);
      else if (symbol >= GDK_KEY_Zcaron && symbol <= GDK_KEY_Zabovedot)
        xlower += (GDK_KEY_zcaron - GDK_KEY_Zcaron);
      else if (symbol == GDK_KEY_aogonek)
        xupper = GDK_KEY_Aogonek;
      else if (symbol >= GDK_KEY_lstroke && symbol <= GDK_KEY_sacute)
        xupper -= (GDK_KEY_lstroke - GDK_KEY_Lstroke);
      else if (symbol >= GDK_KEY_scaron && symbol <= GDK_KEY_zacute)
        xupper -= (GDK_KEY_scaron - GDK_KEY_Scaron);
      else if (symbol >= GDK_KEY_zcaron && symbol <= GDK_KEY_zabovedot)
        xupper -= (GDK_KEY_zcaron - GDK_KEY_Zcaron);
      else if (symbol >= GDK_KEY_Racute && symbol <= GDK_KEY_Tcedilla)
        xlower += (GDK_KEY_racute - GDK_KEY_Racute);
      else if (symbol >= GDK_KEY_racute && symbol <= GDK_KEY_tcedilla)
        xupper -= (GDK_KEY_racute - GDK_KEY_Racute);
      break;

    case 2: /* Latin 3 */
      /* Assume the KeySym is a legal value (ignore discontinuities) */
      if (symbol >= GDK_KEY_Hstroke && symbol <= GDK_KEY_Hcircumflex)
        xlower += (GDK_KEY_hstroke - GDK_KEY_Hstroke);
      else if (symbol >= GDK_KEY_Gbreve && symbol <= GDK_KEY_Jcircumflex)
        xlower += (GDK_KEY_gbreve - GDK_KEY_Gbreve);
      else if (symbol >= GDK_KEY_hstroke && symbol <= GDK_KEY_hcircumflex)
        xupper -= (GDK_KEY_hstroke - GDK_KEY_Hstroke);
      else if (symbol >= GDK_KEY_gbreve && symbol <= GDK_KEY_jcircumflex)
        xupper -= (GDK_KEY_gbreve - GDK_KEY_Gbreve);
      else if (symbol >= GDK_KEY_Cabovedot && symbol <= GDK_KEY_Scircumflex)
        xlower += (GDK_KEY_cabovedot - GDK_KEY_Cabovedot);
      else if (symbol >= GDK_KEY_cabovedot && symbol <= GDK_KEY_scircumflex)
        xupper -= (GDK_KEY_cabovedot - GDK_KEY_Cabovedot);
      break;

    case 3: /* Latin 4 */
      /* Assume the KeySym is a legal value (ignore discontinuities) */
      if (symbol >= GDK_KEY_Rcedilla && symbol <= GDK_KEY_Tslash)
        xlower += (GDK_KEY_rcedilla - GDK_KEY_Rcedilla);
      else if (symbol >= GDK_KEY_rcedilla && symbol <= GDK_KEY_tslash)
        xupper -= (GDK_KEY_rcedilla - GDK_KEY_Rcedilla);
      else if (symbol == GDK_KEY_ENG)
        xlower = GDK_KEY_eng;
      else if (symbol == GDK_KEY_eng)
        xupper = GDK_KEY_ENG;
      else if (symbol >= GDK_KEY_Amacron && symbol <= GDK_KEY_Umacron)
        xlower += (GDK_KEY_amacron - GDK_KEY_Amacron);
      else if (symbol >= GDK_KEY_amacron && symbol <= GDK_KEY_umacron)
        xupper -= (GDK_KEY_amacron - GDK_KEY_Amacron);
      break;

    case 6: /* Cyrillic */
      /* Assume the KeySym is a legal value (ignore discontinuities) */
      if (symbol >= GDK_KEY_Serbian_DJE && symbol <= GDK_KEY_Serbian_DZE)
        xlower -= (GDK_KEY_Serbian_DJE - GDK_KEY_Serbian_dje);
      else if (symbol >= GDK_KEY_Serbian_dje && symbol <= GDK_KEY_Serbian_dze)
        xupper += (GDK_KEY_Serbian_DJE - GDK_KEY_Serbian_dje);
      else if (symbol >= GDK_KEY_Cyrillic_YU && symbol <= GDK_KEY_Cyrillic_HARDSIGN)
        xlower -= (GDK_KEY_Cyrillic_YU - GDK_KEY_Cyrillic_yu);
      else if (symbol >= GDK_KEY_Cyrillic_yu && symbol <= GDK_KEY_Cyrillic_hardsign)
        xupper += (GDK_KEY_Cyrillic_YU - GDK_KEY_Cyrillic_yu);
      break;

    case 7: /* Greek */
      /* Assume the KeySym is a legal value (ignore discontinuities) */
      if (symbol >= GDK_KEY_Greek_ALPHAaccent && symbol <= GDK_KEY_Greek_OMEGAaccent)
        xlower += (GDK_KEY_Greek_alphaaccent - GDK_KEY_Greek_ALPHAaccent);
      else if (symbol >= GDK_KEY_Greek_alphaaccent && symbol <= GDK_KEY_Greek_omegaaccent &&
               symbol != GDK_KEY_Greek_iotaaccentdieresis &&
               symbol != GDK_KEY_Greek_upsilonaccentdieresis)
        xupper -= (GDK_KEY_Greek_alphaaccent - GDK_KEY_Greek_ALPHAaccent);
      else if (symbol >= GDK_KEY_Greek_ALPHA && symbol <= GDK_KEY_Greek_OMEGA)
        xlower += (GDK_KEY_Greek_alpha - GDK_KEY_Greek_ALPHA);
      else if (symbol >= GDK_KEY_Greek_alpha && symbol <= GDK_KEY_Greek_omega &&
               symbol != GDK_KEY_Greek_finalsmallsigma)
        xupper -= (GDK_KEY_Greek_alpha - GDK_KEY_Greek_ALPHA);
      break;
    }

  if (lower)
    *lower = xlower;
  if (upper)
    *upper = xupper;
}