gdkKeymapTranslateKeyboardState: gdkKeymapTranslateKeyboardState

In RGtk2: R Bindings for Gtk 2.8.0 and Above

Description

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

Usage

gdkKeymapTranslateKeyboardState(object, hardware.keycode, state, 
    group)

Arguments

object	a GdkKeymap, or NULL to use the default. [ allow-none ]
hardware.keycode	a keycode
state	a modifier state
group	active keyboard group

Details

PLEASE NOTE: consumed.modifiers gives 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.

# We want to ignore irrelevant modifiers like ScrollLock
all_accels_mask <- GdkModifierType["control-mask"] | 
GdkModifierType["shift-mask"] | GdkModifierType["mod1-mask"]
state <- gdkKeymapTranslateKeyboardState(keymap, event[["hardware_keycode"]],
                                         event[["state"]], event[["group"]])
unconsumed <- all_accels_mask & event[["state"]] & !as.flag(state$consumed) 
if (state$keyval == .gdkPlus && unconsumed == GdkModifierType["control-mask"])
  print("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
unconsumed <- all_accel_mask & event[["state"]] & !as.flag(state$consumed)
if (state$keyval == accel_keyval &&
    unconsumed == accel_mods & !as.flag(state$consumed))
  print("Accellerator 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,

Value

A list containing the following elements:

retval	[logical] TRUE if there was a keyval bound to the keycode/state/group
keyval	return location for keyval, or NULL. [ out ][ allow-none ]
effective.group	return location for effective group, or NULL. [ out ][ allow-none ]
level	return location for level, or NULL. [ out ][ allow-none ]
consumed.modifiers	return location for modifiers that were used to determine the group or level, or NULL. [ out ][ allow-none ]

Note

consumed.modifiers gives 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.

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: 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,

Author(s)

Derived by RGtkGen from GTK+ documentation

RGtk2 documentation built on Oct. 14, 2021, 5:08 p.m.