Class: Gdk::Keymap

Inherits:
Object
  • Object
show all
Defined in:
(unknown)

Overview

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

Instance Method Summary collapse

Instance Method Details

#add_virtual_modifiers(state) ⇒ nil

Maps the non-virtual modifiers (i.e Mod2, Mod3, …) which are set in state to the virtual modifiers (i.e. Super, Hyper and Meta) and set the corresponding bits in state.

GDK already does this before delivering key events, but for compatibility reasons, it only sets the first virtual modifier it finds, whereas this function sets all matching virtual modifiers.

This function is useful when matching key events against accelerators.

Parameters:

Returns:

  • (nil)

#caps_lock_state ⇒ TrueClass

Returns whether the Caps Lock modifer is locked.

Returns:

  • (TrueClass) —

    true if Caps Lock is on

#direction ⇒ Pango::Direction

Returns the direction of effective layout of the keymap.

Returns:

  • (Pango::Direction) —

    %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL if it can determine the direction. %PANGO_DIRECTION_NEUTRAL otherwise.

#get_entries_for_keycode(hardware_keycode, keys, keyvals, n_entries) ⇒ TrueClass

Returns the keyvals bound to hardware_keycode. The Nth Gdk::KeymapKey in keys is bound to the Nth keyval in keyvals. Free the returned arrays with g_free(). 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 gdk_keymap_translate_keyboard_state().

Parameters:

  • hardware_keycode (Integer) —

    a keycode

  • keys (Array<Gdk::KeymapKey>) —

    return location for array of Gdk::KeymapKey, or nil

  • keyvals (Array<Integer>) —

    return location for array of keyvals, or nil

  • n_entries (Integer) —

    length of keys and keyvals

Returns:

  • (TrueClass) —

    true if there were any entries

#get_entries_for_keyval(keyval, keys, n_keys) ⇒ TrueClass

Obtains a list of keycode/group/level combinations 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. Gdk::EventKey contains a %group field that indicates the active keyboard group. The level is computed from the modifier mask. The returned array should be freed with g_free().

Parameters:

  • keyval (Integer) —

    a keyval, such as %GDK_KEY_a, %GDK_KEY_Up, %GDK_KEY_Return, etc.

  • keys (Array<Gdk::KeymapKey>) —

    return location for an array of Gdk::KeymapKey

  • n_keys (Integer) —

    return location for number of elements in returned array

Returns:

  • (TrueClass) —

    true if keys were found and returned

#get_modifier_mask(intent) ⇒ Gdk::ModifierType

Returns the modifier mask the keymap’s windowing system backend uses for a particular purpose.

Note that this function always returns real hardware modifiers, not virtual ones (e.g. it will return #GDK_MOD1_MASK rather than #GDK_META_MASK if the backend maps MOD1 to META), so there are use cases where the return value of this function has to be transformed by gdk_keymap_add_virtual_modifiers() in order to contain the expected result.

Parameters:

Returns:

#have_bidi_layouts ⇒ TrueClass

Determines if keyboard layouts for both right-to-left and left-to-right languages are in use.

Returns:

  • (TrueClass) —

    true if there are layouts in both directions, false otherwise

#lookup_key(key) ⇒ Integer

Looks up the keyval mapped to a keycode/group/level triplet. If no keyval is bound to key, returns 0. For normal user input, you want to use gdk_keymap_translate_keyboard_state() instead of this function, since the effective group/level may not be the same as the current keyboard state.

Parameters:

  • key (Gdk::KeymapKey) —

    a Gdk::KeymapKey with keycode, group, and level initialized

Returns:

  • (Integer) —

    a keyval, or 0 if none was mapped to the given key

#map_virtual_modifiers(state) ⇒ TrueClass

Maps the virtual modifiers (i.e. Super, Hyper and Meta) which are set in state to their non-virtual counterparts (i.e. Mod2, Mod3,…) and set the corresponding bits in state.

This function is useful when matching key events against accelerators.

Parameters:

Returns:

  • (TrueClass) —

    false if two virtual modifiers were mapped to the same non-virtual modifier. Note that false is also returned if a virtual modifier is mapped to a non-virtual modifier that was already set in state.

#modifier_state ⇒ Integer

Returns the current modifier state.

Returns:

  • (Integer) —

    the current modifier state.

#num_lock_state ⇒ TrueClass

Returns whether the Num Lock modifer is locked.

Returns:

  • (TrueClass) —

    true if Num Lock is on

#scroll_lock_state ⇒ TrueClass

Returns whether the Scroll Lock modifer is locked.

Returns:

  • (TrueClass) —

    true if Scroll Lock is on

#translate_keyboard_state(hardware_keycode, state, group, keyval, effective_group, level, consumed_modifiers) ⇒ TrueClass

Translates the contents of a Gdk::EventKey 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] 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, Gdk::EventKey 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.

// 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 (Integer) —

    a keycode

  • state (Gdk::ModifierType) —

    a modifier state

  • group (Integer) —

    active keyboard group

  • keyval (Integer) —

    return location for keyval, or nil

  • effective_group (Integer) —

    return location for effective group, or nil

  • level (Integer) —

    return location for level, or nil

  • consumed_modifiers (Gdk::ModifierType) —

    return location for modifiers that were used to determine the group or level, or nil

Returns:

  • (TrueClass) —

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