gtk.gdk.Keymap an object containing mappings of keys to key values. gtk.gdk.Keymap gobject.GObject lookup_key keycode group level translate_keyboard_state keycode state group get_entries_for_keyval keyval get_entries_for_keycode hardware_keycode get_direction have_bidi_layouts Functions gtk.gdk.keymap_get_default gtk.gdk.keymap_get_for_display display gtk.gdk.keyval_name keyval gtk.gdk.keyval_from_name keyval_name gtk.gdk.keyval_convert_case symbol gtk.gdk.keyval_to_upper keyval gtk.gdk.keyval_to_lower keyval gtk.gdk.keyval_is_upper keyval gtk.gdk.keyval_is_lower keyval gtk.gdk.keyval_to_unicode keyval gtk.gdk.unicode_to_keyval wc +-- gobject.GObject +-- gtk.gdk.Keymap "direction-changed" callback gdkkeymap user_param1 ... "keys-changed" callback gdkkeymap user_param1 ... A gtk.gdk.Keymap defines the translation from keyboard state (including a hardware key, a modifier mask, and active keyboard group) to a keyval. This translation has two phases. The first phase is to determine the effective keyboard group and level for the keyboard state; the second phase is to look up the keycode/group/level triplet in the keymap and see what keyval it corresponds to. One gtk.gdk.Keymap object exists for each user display. PyGTK supports only one display, so gtk.gdk.keymap_get_default()() returns the singleton gtk.gdk.Keymap. A keymap is a mapping from a Keymap key to key values. You can think of a Keymap key 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 level of the key. The level indicates which symbol on the key will be used, in a vertical direction. So on a standard US keyboard, the key 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 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 Keymap key 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. lookup_key keycode group level keycode : the hardware keycode. group : the key group level : the key level Returns : a keyval, or 0 if none was mapped to the (keycode, group, level) triplet. This method is available in PyGTK 2.4 and above. The lookup_key() method returns the keyval mapped to the specified (keycode, group, level) triplet. This method returns 0 if no keyval is found. For normal user input, you want to use the translate_keyboard_state() method instead of this method, since the effective group or level may not be the same as the current keyboard state. The parameters to this method are: keycode : the hardware keycode. This is an identifying number for a physical key. 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. level : indicates which symbol on the key will be used, in a vertical direction. So on a standard US keyboard, the key 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 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. translate_keyboard_state keycode state group keycode : a keycode state : a modifier state group : an active keyboard group Returns : a 4-tuple containing the keyval, the effective group, the level and the modifiers that were used to determine the group or level This method is available in PyGTK 2.4 and above. The translate_keyboard_state() method translates the contents of a keyboard gtk.gdk.Event (specified by keycode, state and group) into a keyval, effective group, level and consumed modifiers that affected the translation (and are unavailable for application use) which are returned in a 4-tuple. See the lookup_key() method for an explanation of groups and levels. The effective group is the group that was 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, the keyboard gtk.gdk.Event already contains the translated keyval, so this method isn't as useful as you might think. The value of state or the consumed modifiers is a combination of the . The consumed modifiers are modifiers that should be masked out from 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 Controlplus accelerator Shift should be masked out. For example: # We want to ignore irrelevant modifiers like ScrollLock ALL_ACCELS_MASK = (gtk.gdk.CONTROL_MASK | gtk.gdk.SHIFT_MASK | gtk.gdk.MOD1_MASK) keyval, egroup, level, consumed = keymap.translate_keyboard_state( event.hardware_keycode, event.state, event.group) if (keyval == gtk.keysyms.plus and (event.state & ~consumed & ALL_ACCELS_MASK) == gtk.gdk.CONTROL_MASK): # Control was pressed Note that most keys that are affected by the Shift key will have gtk.gdk.SHIFT_MASK part of the consumed modifiers (e.g. ControlShiftTab ). 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, get_entries_for_keyval keyval keyval : a keyval, such as GDK_a, GDK_Up, GDK_Return, etc. Returns : a tuple containing 3-tuple containing a keycode, a group and a level that will generate keyval. This method is available in PyGTK 2.4 and above. The get_entries_for_keyval() method returns a tuple of (keycode, group, level) 3-tuples 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, the gtk.gdk.KEY_PRESS and gtk.gdk.KEY_RELEASE gtk.gdk.Event objects contain a group attribute that indicates the active keyboard group. The level is computed from the modifier mask. get_entries_for_keycode hardware_keycode hardware_keycode : a keycode Returns : a tuple containing 4-tuples: (keyval, keycode, group, level) This method is available in PyGTK 2.4 and above. The get_entries_for_keycode() method returns a tuple containing 4-tuples with: the keyvals bound to hardware_keycode, the keycode, the group and the level. 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 the translate_keyboard_state() method for more information. get_direction Returns : a Pango direction: pango.DIRECTION_LTR or pango.DIRECTION_RTL. The get_direction() method returns the direction of the keymap. have_bidi_layouts Returns : True if there are layouts in both directions, False otherwise. The have_bidi_layouts() method determines if keyboard layouts for both right-to-left and left-to-right languages are in use. gtk.gdk.keymap_get_default Returns : the default gdk keymap for the display. The gtk.gdk.keymap_get_default() function returns the default gtk.gdk.Keymap for the display. gtk.gdk.keymap_get_for_display display display : a gtk.gdk.Display Returns : the keymap for display. This function is available in PyGTK 2.2 and above. The gtk.gdk.keymap_get_for_display() function returns the gtk.gdk.Keymap for the gtk.gdk.Display specified by display. gtk.gdk.keyval_name keyval keyval : a key value Returns : a string containing the name of the key, or None if keyval is not a valid key. The gtk.gdk.keyval_name() function converts the key value specified by keyval into a symbolic name. gtk.gdk.keyval_from_name keyval_name keyval_name : a key name Returns : the corresponding key value or 0 if the key name is not a valid key. The gtk.gdk.keyval_from_name() function converts the key name specified by keyval_name to a key value. gtk.gdk.keyval_convert_case symbol symbol : a keyval Returns : a 2-tuple containing the lowercase and uppercase versions of symbol This function is available in PyGTK 2.4 and above. The gtk.gdk.keyval_convert_case() function returns the lowercase and uppercase versions of the keyval specified by symbol. gtk.gdk.keyval_to_upper keyval keyval : a key value. 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. The gtk.gdk.keyval_to_upper() function converts the key value specified by keyval to upper case, if applicable. gtk.gdk.keyval_to_lower keyval keyval : the key value 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. The gtk.gdk.keyval_to_lower() function converts the key value specified by keyval to lower case, if applicable. gtk.gdk.keyval_is_upper keyval keyval : the key value Returns : True if keyval is in upper case or if keyval is not subject to case conversion. The gtk.gdk.keyval_is_upper() function returns True if the key value specified by keyval is in upper case or not subject to case conversion. gtk.gdk.keyval_is_lower keyval keyval : the key value Returns : True if keyval is in lower case, or if keyval is not subject to case conversion. The gtk.gdk.keyval_is_lower() function returns True if the key value specified by keyval is in lower case or is not subject to case conversion. gtk.gdk.keyval_to_unicode keyval keyval : the key value Returns : the corresponding unicode character, or 0 if there is no corresponding character. The gtk.gdk.keyval_to_unicode() function converts the key value specified by keyval to the corresponding ISO10646 (Unicode) character. gtk.gdk.unicode_to_keyval wc wc : a ISO10646 encoded (unicode) character Returns : the corresponding key value, if one exists. or, if there is no corresponding symbol, wc | 0x01000000 The gtk.gdk.unicode_to_keyval() function converts the ISO10646 (unicode) character specified by wc to a key value. callback gdkkeymap user_param1 ... gdkkeymap : the gdkkeymap that received the signal user_param1 : the first user parameter (if any) specified with the connect() method ... : additional user parameters (if any) The "direction-changed" signal is emitted when the pango text direction of gdkkeymap is changed callback gdkkeymap user_param1 ... gdkkeymap : the gdkkeymap that received the signal user_param1 : the first user parameter (if any) specified with the connect() method ... : additional user parameters (if any) This signal is available in GTK+ 2.2 and above. The "keys-changed" signal is emitted when the mapping represented by keymap changes.