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, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 /*
  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/.
  25  */
  26
  27 #include "config.h"
  28
  29 #include "gdkinternals.h"
  30 #include "gdkkeys.h"
  31
  32 #include "gdkdisplay.h"
  33
  34
  35 /**
  36  * SECTION:keys
  37  * @Short_description: Functions for manipulating keyboard codes
  38  * @Title: Key Values
  39  *
  40  * Key values are the codes which are sent whenever a key is pressed or released.
  41  * They appear in the #GdkEventKey.keyval field of the
  42  * #GdkEventKey structure, which is passed to signal handlers for the
  43  * #GtkWidget::key-press-event and #GtkWidget::key-release-event signals.
  44  * The complete list of key values can be found in the
  45  * <filename>&lt;gdk/gdkkeysyms.h&gt;</filename> header file.
  46  *
  47  * Key values are regularly updated from the upstream X.org X11 implementation,
  48  * so new values are added regularly. They will be prefixed with GDK_KEY_ rather
  49  * than XF86XK_ or XK_ (for older symbols).
  50  *
  51  * Key values can be converted into a string representation using
  52  * gdk_keyval_name(). The reverse function, converting a string to a key value,
  53  * is provided by gdk_keyval_from_name().
  54  *
  55  * The case of key values can be determined using gdk_keyval_is_upper() and
  56  * gdk_keyval_is_lower(). Key values can be converted to upper or lower case
  57  * using gdk_keyval_to_upper() and gdk_keyval_to_lower().
  58  *
  59  * When it makes sense, key values can be converted to and from
  60  * Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval().
  61  *
  62  * <para id="key-group-explanation">
  63  * One #GdkKeymap object exists for each user display. gdk_keymap_get_default()
  64  * returns the #GdkKeymap for the default display; to obtain keymaps for other
  65  * displays, use gdk_keymap_get_for_display(). A keymap
  66  * is a mapping from #GdkKeymapKey to key values. You can think of a #GdkKeymapKey
  67  * as a representation of a symbol printed on a physical keyboard key. That is, it
  68  * contains three pieces of information. First, it contains the hardware keycode;
  69  * this is an identifying number for a physical key. Second, it contains the
  70  * <firstterm>level</firstterm> of the key. The level indicates which symbol on the
  71  * key will be used, in a vertical direction. So on a standard US keyboard, the key
  72  * with the number "1" on it also has the exclamation point ("!") character on
  73  * it. The level indicates whether to use the "1" or the "!" symbol.  The letter
  74  * keys are considered to have a lowercase letter at level 0, and an uppercase
  75  * letter at level 1, though only the uppercase letter is printed.  Third, the
  76  * #GdkKeymapKey contains a group; groups are not used on standard US keyboards,
  77  * but are used in many other countries. On a keyboard with groups, there can be 3
  78  * or 4 symbols printed on a single key. The group indicates movement in a
  79  * horizontal direction. Usually groups are used for two different languages.  In
  80  * group 0, a key might have two English characters, and in group 1 it might have
  81  * two Hebrew characters. The Hebrew characters will be printed on the key next to
  82  * the English characters.
  83  * </para>
  84  *
  85  * In order to use a keymap to interpret a key event, it's necessary to first
  86  * convert the keyboard state into an effective group and level. This is done via a
  87  * set of rules that varies widely according to type of keyboard and user
  88  * configuration. The function gdk_keymap_translate_keyboard_state() accepts a
  89  * keyboard state -- consisting of hardware keycode pressed, active modifiers, and
  90  * active group -- applies the appropriate rules, and returns the group/level to be
  91  * used to index the keymap, along with the modifiers which did not affect the
  92  * group and level. i.e. it returns "unconsumed modifiers." The keyboard group may
  93  * differ from the effective group used for keymap lookups because some keys don't
  94  * have multiple groups - e.g. the Enter key is always in group 0 regardless of
  95  * keyboard state.
  96  *
  97  * Note that gdk_keymap_translate_keyboard_state() also returns the keyval, i.e. it
  98  * goes ahead and performs the keymap lookup in addition to telling you which
  99  * effective group/level values were used for the lookup. #GdkEventKey already
 100  * contains this keyval, however, so you don't normally need to call
 101  * gdk_keymap_translate_keyboard_state() just to get the keyval.
 102  */
 103
 104
 105 enum {
 106   DIRECTION_CHANGED,
 107   KEYS_CHANGED,
 108   STATE_CHANGED,
 109   LAST_SIGNAL
 110 };
 111
 112 static guint signals[LAST_SIGNAL] = { 0 };
 113
 114 G_DEFINE_TYPE (GdkKeymap, gdk_keymap, G_TYPE_OBJECT)
 115
 116 static void
 117 gdk_keymap_class_init (GdkKeymapClass *klass)
 118 {
 119   GObjectClass *object_class = G_OBJECT_CLASS (klass);
 120
 121   /**
 122    * GdkKeymap::direction-changed:
 123    * @keymap: the object on which the signal is emitted
 124    *
 125    * The ::direction-changed signal gets emitted when the direction of
 126    * the keymap changes.
 127    *
 128    * Since: 2.0
 129    */
 130   signals[DIRECTION_CHANGED] =
 131     g_signal_new ("direction-changed",
 132                   G_OBJECT_CLASS_TYPE (object_class),
 133                   G_SIGNAL_RUN_LAST,
 134                   G_STRUCT_OFFSET (GdkKeymapClass, direction_changed),
 135                   NULL, NULL,
 136                   g_cclosure_marshal_VOID__VOID,
 137                   G_TYPE_NONE,
 138                   0);
 139   /**
 140    * GdkKeymap::keys-changed:
 141    * @keymap: the object on which the signal is emitted
 142    *
 143    * The ::keys-changed signal is emitted when the mapping represented by
 144    * @keymap changes.
 145    *
 146    * Since: 2.2
 147    */
 148   signals[KEYS_CHANGED] =
 149     g_signal_new ("keys-changed",
 150                   G_OBJECT_CLASS_TYPE (object_class),
 151                   G_SIGNAL_RUN_LAST,
 152                   G_STRUCT_OFFSET (GdkKeymapClass, keys_changed),
 153                   NULL, NULL,
 154                   g_cclosure_marshal_VOID__VOID,
 155                   G_TYPE_NONE,
 156                   0);
 157
 158   /**
 159    * GdkKeymap::state-changed:
 160    * @keymap: the object on which the signal is emitted
 161    *
 162    * The ::state-changed signal is emitted when the state of the
 163    * keyboard changes, e.g when Caps Lock is turned on or off.
 164    * See gdk_keymap_get_caps_lock_state().
 165    *
 166    * Since: 2.16
 167    */
 168   signals[STATE_CHANGED] =
 169     g_signal_new ("state_changed",
 170                   G_OBJECT_CLASS_TYPE (object_class),
 171                   G_SIGNAL_RUN_LAST,
 172                   G_STRUCT_OFFSET (GdkKeymapClass, state_changed),
 173                   NULL, NULL,
 174                   g_cclosure_marshal_VOID__VOID,
 175                   G_TYPE_NONE,
 176                   0);
 177 }
 178
 179 static void
 180 gdk_keymap_init (GdkKeymap *keymap)
 181 {
 182 }
 183
 184 /* Other key-handling stuff
 185  */
 186
 187 #ifndef HAVE_XCONVERTCASE
 188 #include "gdkkeysyms.h"
 189
 190 /* compatibility function from X11R6.3, since XConvertCase is not
 191  * supplied by X11R5.
 192  */
 193 /**
 194  * gdk_keyval_convert_case:
 195  * @symbol: a keyval
 196  * @lower: (out): return location for lowercase version of @symbol
 197  * @upper: (out): return location for uppercase version of @symbol
 198  *
 199  * Obtains the upper- and lower-case versions of the keyval @symbol.
 200  * Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc.
 201  *
 202  **/
 203 void
 204 gdk_keyval_convert_case (guint symbol,
 205                          guint *lower,
 206                          guint *upper)
 207 {
 208   guint xlower = symbol;
 209   guint xupper = symbol;
 210
 211   /* Check for directly encoded 24-bit UCS characters: */
 212   if ((symbol & 0xff000000) == 0x01000000)
 213     {
 214       if (lower)
 215         *lower = gdk_unicode_to_keyval (g_unichar_tolower (symbol & 0x00ffffff));
 216       if (upper)
 217         *upper = gdk_unicode_to_keyval (g_unichar_toupper (symbol & 0x00ffffff));
 218       return;
 219     }
 220
 221   switch (symbol >> 8)
 222     {
 223     case 0: /* Latin 1 */
 224       if ((symbol >= GDK_KEY_A) && (symbol <= GDK_KEY_Z))
 225         xlower += (GDK_KEY_a - GDK_KEY_A);
 226       else if ((symbol >= GDK_KEY_a) && (symbol <= GDK_KEY_z))
 227         xupper -= (GDK_KEY_a - GDK_KEY_A);
 228       else if ((symbol >= GDK_KEY_Agrave) && (symbol <= GDK_KEY_Odiaeresis))
 229         xlower += (GDK_KEY_agrave - GDK_KEY_Agrave);
 230       else if ((symbol >= GDK_KEY_agrave) && (symbol <= GDK_KEY_odiaeresis))
 231         xupper -= (GDK_KEY_agrave - GDK_KEY_Agrave);
 232       else if ((symbol >= GDK_KEY_Ooblique) && (symbol <= GDK_KEY_Thorn))
 233         xlower += (GDK_KEY_oslash - GDK_KEY_Ooblique);
 234       else if ((symbol >= GDK_KEY_oslash) && (symbol <= GDK_KEY_thorn))
 235         xupper -= (GDK_KEY_oslash - GDK_KEY_Ooblique);
 236       break;
 237
 238     case 1: /* Latin 2 */
 239       /* Assume the KeySym is a legal value (ignore discontinuities) */
 240       if (symbol == GDK_KEY_Aogonek)
 241         xlower = GDK_KEY_aogonek;
 242       else if (symbol >= GDK_KEY_Lstroke && symbol <= GDK_KEY_Sacute)
 243         xlower += (GDK_KEY_lstroke - GDK_KEY_Lstroke);
 244       else if (symbol >= GDK_KEY_Scaron && symbol <= GDK_KEY_Zacute)
 245         xlower += (GDK_KEY_scaron - GDK_KEY_Scaron);
 246       else if (symbol >= GDK_KEY_Zcaron && symbol <= GDK_KEY_Zabovedot)
 247         xlower += (GDK_KEY_zcaron - GDK_KEY_Zcaron);
 248       else if (symbol == GDK_KEY_aogonek)
 249         xupper = GDK_KEY_Aogonek;
 250       else if (symbol >= GDK_KEY_lstroke && symbol <= GDK_KEY_sacute)
 251         xupper -= (GDK_KEY_lstroke - GDK_KEY_Lstroke);
 252       else if (symbol >= GDK_KEY_scaron && symbol <= GDK_KEY_zacute)
 253         xupper -= (GDK_KEY_scaron - GDK_KEY_Scaron);
 254       else if (symbol >= GDK_KEY_zcaron && symbol <= GDK_KEY_zabovedot)
 255         xupper -= (GDK_KEY_zcaron - GDK_KEY_Zcaron);
 256       else if (symbol >= GDK_KEY_Racute && symbol <= GDK_KEY_Tcedilla)
 257         xlower += (GDK_KEY_racute - GDK_KEY_Racute);
 258       else if (symbol >= GDK_KEY_racute && symbol <= GDK_KEY_tcedilla)
 259         xupper -= (GDK_KEY_racute - GDK_KEY_Racute);
 260       break;
 261
 262     case 2: /* Latin 3 */
 263       /* Assume the KeySym is a legal value (ignore discontinuities) */
 264       if (symbol >= GDK_KEY_Hstroke && symbol <= GDK_KEY_Hcircumflex)
 265         xlower += (GDK_KEY_hstroke - GDK_KEY_Hstroke);
 266       else if (symbol >= GDK_KEY_Gbreve && symbol <= GDK_KEY_Jcircumflex)
 267         xlower += (GDK_KEY_gbreve - GDK_KEY_Gbreve);
 268       else if (symbol >= GDK_KEY_hstroke && symbol <= GDK_KEY_hcircumflex)
 269         xupper -= (GDK_KEY_hstroke - GDK_KEY_Hstroke);
 270       else if (symbol >= GDK_KEY_gbreve && symbol <= GDK_KEY_jcircumflex)
 271         xupper -= (GDK_KEY_gbreve - GDK_KEY_Gbreve);
 272       else if (symbol >= GDK_KEY_Cabovedot && symbol <= GDK_KEY_Scircumflex)
 273         xlower += (GDK_KEY_cabovedot - GDK_KEY_Cabovedot);
 274       else if (symbol >= GDK_KEY_cabovedot && symbol <= GDK_KEY_scircumflex)
 275         xupper -= (GDK_KEY_cabovedot - GDK_KEY_Cabovedot);
 276       break;
 277
 278     case 3: /* Latin 4 */
 279       /* Assume the KeySym is a legal value (ignore discontinuities) */
 280       if (symbol >= GDK_KEY_Rcedilla && symbol <= GDK_KEY_Tslash)
 281         xlower += (GDK_KEY_rcedilla - GDK_KEY_Rcedilla);
 282       else if (symbol >= GDK_KEY_rcedilla && symbol <= GDK_KEY_tslash)
 283         xupper -= (GDK_KEY_rcedilla - GDK_KEY_Rcedilla);
 284       else if (symbol == GDK_KEY_ENG)
 285         xlower = GDK_KEY_eng;
 286       else if (symbol == GDK_KEY_eng)
 287         xupper = GDK_KEY_ENG;
 288       else if (symbol >= GDK_KEY_Amacron && symbol <= GDK_KEY_Umacron)
 289         xlower += (GDK_KEY_amacron - GDK_KEY_Amacron);
 290       else if (symbol >= GDK_KEY_amacron && symbol <= GDK_KEY_umacron)
 291         xupper -= (GDK_KEY_amacron - GDK_KEY_Amacron);
 292       break;
 293
 294     case 6: /* Cyrillic */
 295       /* Assume the KeySym is a legal value (ignore discontinuities) */
 296       if (symbol >= GDK_KEY_Serbian_DJE && symbol <= GDK_KEY_Serbian_DZE)
 297         xlower -= (GDK_KEY_Serbian_DJE - GDK_KEY_Serbian_dje);
 298       else if (symbol >= GDK_KEY_Serbian_dje && symbol <= GDK_KEY_Serbian_dze)
 299         xupper += (GDK_KEY_Serbian_DJE - GDK_KEY_Serbian_dje);
 300       else if (symbol >= GDK_KEY_Cyrillic_YU && symbol <= GDK_KEY_Cyrillic_HARDSIGN)
 301         xlower -= (GDK_KEY_Cyrillic_YU - GDK_KEY_Cyrillic_yu);
 302       else if (symbol >= GDK_KEY_Cyrillic_yu && symbol <= GDK_KEY_Cyrillic_hardsign)
 303         xupper += (GDK_KEY_Cyrillic_YU - GDK_KEY_Cyrillic_yu);
 304       break;
 305
 306     case 7: /* Greek */
 307       /* Assume the KeySym is a legal value (ignore discontinuities) */
 308       if (symbol >= GDK_KEY_Greek_ALPHAaccent && symbol <= GDK_KEY_Greek_OMEGAaccent)
 309         xlower += (GDK_KEY_Greek_alphaaccent - GDK_KEY_Greek_ALPHAaccent);
 310       else if (symbol >= GDK_KEY_Greek_alphaaccent && symbol <= GDK_KEY_Greek_omegaaccent &&
 311                symbol != GDK_KEY_Greek_iotaaccentdieresis &&
 312                symbol != GDK_KEY_Greek_upsilonaccentdieresis)
 313         xupper -= (GDK_KEY_Greek_alphaaccent - GDK_KEY_Greek_ALPHAaccent);
 314       else if (symbol >= GDK_KEY_Greek_ALPHA && symbol <= GDK_KEY_Greek_OMEGA)
 315         xlower += (GDK_KEY_Greek_alpha - GDK_KEY_Greek_ALPHA);
 316       else if (symbol >= GDK_KEY_Greek_alpha && symbol <= GDK_KEY_Greek_omega &&
 317                symbol != GDK_KEY_Greek_finalsmallsigma)
 318         xupper -= (GDK_KEY_Greek_alpha - GDK_KEY_Greek_ALPHA);
 319       break;
 320     }
 321
 322   if (lower)
 323     *lower = xlower;
 324   if (upper)
 325     *upper = xupper;
 326 }
 327 #endif
 328
 329 /**
 330  * gdk_keyval_to_upper:
 331  * @keyval: a key value.
 332  *
 333  * Converts a key value to upper case, if applicable.
 334  *
 335  * Returns: the upper case form of @keyval, or @keyval itself if it is already
 336  *   in upper case or it is not subject to case conversion.
 337  */
 338 guint
 339 gdk_keyval_to_upper (guint keyval)
 340 {
 341   guint result;
 342
 343   gdk_keyval_convert_case (keyval, NULL, &result);
 344
 345   return result;
 346 }
 347
 348 /**
 349  * gdk_keyval_to_lower:
 350  * @keyval: a key value.
 351  *
 352  * Converts a key value to lower case, if applicable.
 353  *
 354  * Returns: the lower case form of @keyval, or @keyval itself if it is already
 355  *  in lower case or it is not subject to case conversion.
 356  */
 357 guint
 358 gdk_keyval_to_lower (guint keyval)
 359 {
 360   guint result;
 361
 362   gdk_keyval_convert_case (keyval, &result, NULL);
 363
 364   return result;
 365 }
 366
 367 /**
 368  * gdk_keyval_is_upper:
 369  * @keyval: a key value.
 370  *
 371  * Returns %TRUE if the given key value is in upper case.
 372  *
 373  * Returns: %TRUE if @keyval is in upper case, or if @keyval is not subject to
 374  *  case conversion.
 375  */
 376 gboolean
 377 gdk_keyval_is_upper (guint keyval)
 378 {
 379   if (keyval)
 380     {
 381       guint upper_val = 0;
 382
 383       gdk_keyval_convert_case (keyval, NULL, &upper_val);
 384       return upper_val == keyval;
 385     }
 386   return FALSE;
 387 }
 388
 389 /**
 390  * gdk_keyval_is_lower:
 391  * @keyval: a key value.
 392  *
 393  * Returns %TRUE if the given key value is in lower case.
 394  *
 395  * Returns: %TRUE if @keyval is in lower case, or if @keyval is not
 396  *   subject to case conversion.
 397  */
 398 gboolean
 399 gdk_keyval_is_lower (guint keyval)
 400 {
 401   if (keyval)
 402     {
 403       guint lower_val = 0;
 404
 405       gdk_keyval_convert_case (keyval, &lower_val, NULL);
 406       return lower_val == keyval;
 407     }
 408   return FALSE;
 409 }
 410
 411 /**
 412  * gdk_keymap_get_default:
 413  *
 414  * Returns the #GdkKeymap attached to the default display.
 415  *
 416  * Returns: (transfer none): the #GdkKeymap attached to the default display.
 417  */
 418 GdkKeymap*
 419 gdk_keymap_get_default (void)
 420 {
 421   return gdk_keymap_get_for_display (gdk_display_get_default ());
 422 }