gtk.gdk.Keymap

gtk.gdk.Keymap
Prev	The gtk.gdk Class Reference	Next

gtk.gdk.Keymap — an object containing mappings of keys to key values.

Synopsis

class gtk.gdk.Keymap(gobject.GObject):
    def lookup_key(keycode, group, level)
    def translate_keyboard_state(keycode, state, group)
    def get_entries_for_keyval(keyval)
    def get_entries_for_keycode(hardware_keycode)
    def get_direction()

Functions

    def gtk.gdk.keymap_get_default()
    def gtk.gdk.keymap_get_for_display(display)
    def gtk.gdk.keyval_name(keyval)
    def gtk.gdk.keyval_from_name(keyval_name)
    def gtk.gdk.keyval_convert_case(symbol)
    def gtk.gdk.keyval_to_upper(keyval)
    def gtk.gdk.keyval_to_lower(keyval)
    def gtk.gdk.keyval_is_upper(keyval)
    def gtk.gdk.keyval_is_lower(keyval)
    def gtk.gdk.keyval_to_unicode(keyval)
    def gtk.gdk.unicode_to_keyval(wc)

Ancestry

+-- gobject.GObject
  +-- gtk.gdk.Keymap

Signal Prototypes

"direction-changed"	`def callback(gdkkeymap, user_param1, ...)`
"keys-changed"	`def callback(gdkkeymap, user_param1, ...)`

Description

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.

Methods

gtk.gdk.Keymap.lookup_key

    def 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.

Note

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.

gtk.gdk.Keymap.translate_keyboard_state

    def 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

Note

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 GDK Modifier Constants.

Consumed Modifiers

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 Control-plus 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. Control-Shift-Tab).

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,

gtk.gdk.Keymap.get_entries_for_keyval

    def 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`.

Note

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.

gtk.gdk.Keymap.get_entries_for_keycode

    def get_entries_for_keycode(hardware_keycode)

`hardware_keycode` :	a keycode
Returns :	a tuple containing 4-tuples: (keyval, keycode, group, level)

Note

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.

gtk.gdk.Keymap.get_direction

    def get_direction()

Returns : a Pango direction: pango.DIRECTION_LTR or pango.DIRECTION_RTL.

The get_direction() method returns the direction of the keymap.

Functions

gtk.gdk.keymap_get_default

    def 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

    def gtk.gdk.keymap_get_for_display(display)

`display` :	a `gtk.gdk.Display`
Returns :	the keymap for `display`.

Note

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

    def 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

    def 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

    def gtk.gdk.keyval_convert_case(symbol)

`symbol` :	a keyval
Returns :	a 2-tuple containing the lowercase and uppercase versions of `symbol`

Note

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

    def 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

    def 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

    def 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

    def 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

    def 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

    def 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.

Signals

The "direction-changed" gtk.gdk.Keymap Signal

    def 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

The "keys-changed" gtk.gdk.Keymap Signal

    def 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)

Note

This signal is available in GTK+ 2.2 and above.

The "keys-changed" signal is emitted when the mapping represented by keymap changes.