Method

GdkKeymaptranslate_keyboard_state

Declaration [src]

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
)

Description [src]

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 consumed_modifiers. See [Groups][key-group-explanation] 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, GdkEventKey already contains the translated keyval, so this function isn’t as useful as you might think.

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.

// We want to ignore irrelevant modifiers like ScrollLock
#define ALL_ACCELS_MASK (GDK_CONTROL_MASK | GDK_SHIFT_MASK | GDK_MOD1_MASK)
gdk_keymap_translate_keyboard_state (keymap, event->hardware_keycode,
                                     event->state, event->group,
                                     &keyval, NULL, NULL, &consumed);
if (keyval == GDK_PLUS &&
    (event->state & ~consumed & ALL_ACCELS_MASK) == GDK_CONTROL_MASK)
  // Control was pressed

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 modifiers, by doing:

// XXX Don’t do this XXX
if (keyval == accel_keyval &&
    (event->state & ~consumed & ALL_ACCELS_MASK) == (accel_mods & ~consumed))
  // Accelerator was pressed

However, this did not work if multi-modifier combinations were 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,

Parameters

hardware_keycode

Type: guint

A keycode.

state

Type: GdkModifierType

A modifier state.

group

Type: gint

Active keyboard group.

keyval

Type: guint*

Return location for keyval, or NULL.

The argument will be set by the function.
The argument can be NULL.
effective_group

Type: gint*

Return location for effective group, or NULL.

The argument will be set by the function.
The argument can be NULL.
level

Type: gint*

Return location for level, or NULL.

The argument will be set by the function.
The argument can be NULL.
consumed_modifiers

Type: GdkModifierType

Return location for modifiers that were used to determine the group or level, or NULL.

The argument will be set by the function.
The argument can be NULL.
The instance takes ownership of the data, and is responsible for freeing it.

Return value

Type: gboolean

TRUE if there was a keyval bound to the keycode/state/group.