Reference Manual

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

# Inti::Gdk::Keymap Class Reference

A GdkKeymap C++ wrapper class. More...

`#include <inti/gdk/keys.h>`

Inheritance diagram for Inti::Gdk::Keymap:

List of all members.

## Public Member Functions

Constructors

- virtual ~Keymap ()
    Destructor.

Accessors

- GdkKeymap * gdk_keymap () const
    Get a pointer to the GdkKeymap structure.
- GdkKeymapClass * gdk_keymap_class () const
    Get a pointer to the GdkKeymapClass structure.
- operator GdkKeymap * () const
    Conversion operator; safely converts a Keymap to a GdkKeymap pointer.
- Pango::Direction get_direction () const
    Returns the direction of the keymap, either Pango::DIRECTION_LTR or Pango::DIRECTION_RTL.

Methods

- Keyval lookup_key (const KeymapKey &key)
    Looks up the keyval mapped to key (keycode/group/level triplet).
- bool translate_keyboard_state (unsigned int hardware_keycode, ModifierTypeField state, int group, Keyval &keyval, int *effective_group, int *level, ModifierTypeField *consumed_modifiers)
    Translates the contents of an EventKey into a keyval, effective group, and level.
- bool get_entries_for_keyval (const Keyval &keyval, std::vector< KeymapKey > &keys)
    Obtains a list of KeymapKey (keycode/group/level combinations) that will generate the specified keyval.
- bool get_entries_for_keycode (unsigned int hardware_keycode, std::vector< KeymapKey > *keys, std::vector< Keyval > *keyvals)
    Returns the keyvals bound to hardware_keycode.

Signal Proxies

- const DirectionChangedSignalProxy sig_direction_changed ()
    Connect to the direction_changed_signal; emitted when the direction of the keymap changes;.
- const KeysChangedSignalProxy sig_keys_changed ()
    Connect to the keys_changed_signal; emitted when the keyboard mapping changes.

## Static Public Member Functions

- Keymap * get (const Display *display=0)
    Gets the GdkKeymap attached to display.

## Protected Member Functions

Constructors

- Keymap (GdkKeymap *keymap, bool reference=true)
    Construct a new Keymap from an existing GdkKeymap.

Signal Handlers

- virtual void on_direction_changed ()
    Called when the direction of the keymap changes;.
- virtual void on_keys_changed ()
    Called when the keyboard mapping changes.

## Detailed Description

A GdkKeymap C++ wrapper class.

Key values are the codes which are sent whenever a key is pressed or released. They appear in the keyval field of the GdkEventKey structure. They are also returned by the keyval() accessor in the Gdk::EventKey object, which is passed to the virutal signal handlers for the "key-press" and "key-release" event signals. Examples of key values are GDK_a, GDK_Enter, GDK_F1, etc. The complete list of key values can be found in the <gdk/gdkkeysyms.h> header file. This file is not included by Inti, it must be included independently, because the file is quite large.

The Keyval object represents a GDK key value. A key value can be converted into a string representation with Gdk::Keyval::name(). The reverse, a Keyval can be constructed from string. The case of key values can be determined using Gdk::Keyval::is_upper() and Gdk::Keyval::is_lower(). Key values can be converted to upper or lower case using Gdk::Keyval::to_upper() and Gdk::Keyval::to_lower(). When it makes sense, key values can be converted to and from Unicode characters with Gdk::Keyval::to_unicode() and Gdk::Keyval::from_unicode().

One Gdk::Keymap object exists for each user display. Gdk::Keymap::get() returns the keymap for the specified display, or the default display if no display is specified. A keymap is a mapping from Gdk::KeymapKey to key values. You can think of a Gdk::KeymapKey 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 Gdk::KeymapKey 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.

In order to use a keymap to interpret a key event, it's necessary to first convert the keyboard state into an effective group and level. This is done via a set of rules that varies widely according to type of keyboard and user configuration. The method translate_keyboard_state() accepts a keyboard state -- consisting of hardware keycode pressed, active modifiers, and active group -- applies the appropriate rules, and returns the group/level to be used to index the keymap, along with the modifiers which did not affect the group and level. i.e. it returns "unconsumed modifiers." The keyboard group may differ from the effective group used for keymap lookups because some keys don't have multiple groups - e.g. the Enter key is always in group 0 regardless of keyboard state.

Note that translate_keyboard_state() also returns the keyval, i.e. it goes ahead and performs the keymap lookup in addition to telling you which effective group/level values were used for the lookup. Gdk::EventKey already contains this keyval, however, so you don't normally need to call translate_keyboard_state() just to get the keyval.

## Constructor & Destructor Documentation

Inti::Gdk::Keymap::Keymap | ( | GdkKeymap * | keymap,
|  | bool | reference = true
| ) | `[explicit, protected]`

Construct a new Keymap from an existing GdkKeymap.

Parameters:

  keymap | A pointer to a GdkKeymap.
  reference | Set false if the initial reference count is floating, set true if it's not.

The keymap can be a newly created GdkKeymap or an existing GdkKeymap. (see G::Object::Object).

## Member Function Documentation

Keymap* Inti::Gdk::Keymap::get | ( | const Display * | display = 0 | ) | `[static]`

Gets the GdkKeymap attached to display.

Parameters:

  display | The display to use, or null for the default display.

Returns:
  The keymap attached to display.

bool Inti::Gdk::Keymap::get_entries_for_keycode | ( | unsigned int | hardware_keycode,
|  | std::vector< KeymapKey > * | keys,
|  | std::vector< Keyval > * | keyvals
| ) |

Returns the keyvals bound to hardware_keycode.

Parameters:

  hardware_keycode | A keycode.
  keys | A reference to a vector of KeymapKey to hold the keys, or null.
  keyvals | A reference to a vector of Keyval to hold the key values, or null.

Returns:
  true if there were any entries returned in keys and/or keyvals.

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 translate_keyboard_state().

bool Inti::Gdk::Keymap::get_entries_for_keyval | ( | const Keyval & | keyval,
|  | std::vector< KeymapKey > & | keys
| ) |

Obtains a list of KeymapKey (keycode/group/level combinations) that will generate the specified keyval.

Parameters:

  keyval | A keyval, such as GDK_a, GDK_Up, GDK_Return, etc.
  keys | A reference to a vector of KeymapKey to hold the list of keys.

Returns:
  true if keys were found and returned.

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. EventKey contains a group field that indicates the active keyboard group. The level is computed from the modifier mask.

Keyval Inti::Gdk::Keymap::lookup_key | ( | const KeymapKey & | key | ) |

Looks up the keyval mapped to key (keycode/group/level triplet).

Parameters:

  key | A KeymapKey with keycode, group, and level initialized.

Returns:
  A Keyval, or 0 if none was mapped to the given key.

If no keyval is bound to key, returns 0. For normal user input, you want to use translate_keyboard_state() instead of this method, since the effective group/level may not be the same as the current keyboard state.

bool Inti::Gdk::Keymap::translate_keyboard_state | ( | unsigned int | hardware_keycode,
|  | ModifierTypeField | state,
|  | int | group,
|  | Keyval & | keyval,
|  | int * | effective_group,
|  | int * | level,
|  | ModifierTypeField * | consumed_modifiers
| ) |

Translates the contents of an EventKey into a keyval, effective group, and level.

Parameters:

  hardware_keycode | A keycode.
  state | A modifier state.
  group | The active keyboard group.
  keyval | The return location for the keyval.
  effective_group | The return location for the effective group.
  level | The return location for the level.
  consumed_modifiers | The return location for modifiers that were used to determine the group or level.

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

Modifiers that affected the translation and are thus unavailable for application use are returned in consumed_modifiers. See Gdk::Keyval::get_keys() 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, EventKey already contains the translated keyval, so this function isn't as useful as you might think.

The documentation for this class was generated from the following file:

- keys.h

Main Page - Footer