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

## gtk.gdk.Keymap

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.

Prev | Up | Next
gtk.gdk.Image | Home | gtk.gdk.PangoRenderer