Xfce Foundation Classes
Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::Gdk::Keymap Class Reference

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

#include <xfc/gdk/keymap.hh>

Inheritance diagram for Xfc::Gdk::Keymap:

Xfc::G::Object Xfc::G::TypeInstance Xfc::Trackable List of all members.

Signal Prototpyes

Public Member Functions

Constructors
Accessors
Methods
Signal Proxies

Static Public Member Functions

Accessors

Protected Member Functions

Constructors

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

Xfc::Gdk::Keymap::Keymap (  GdkKeymap *  keymap,
bool  owns_reference = true
)  [explicit, protected]
 

Construct a new Keymap from an existing GdkKeymap.

Parameters:
keymap A pointer to a GdkKeymap.
owns_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* Xfc::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 Xfc::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 Xfc::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 Xfc::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 Xfc::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.

Member Data Documentation

const DirectionChangedSignalType Xfc::Gdk::Keymap::direction_changed_signal [static, protected]
 

Direction changed signal (see signal_direction_changed()).

Calls a slot with the signature: 

             void function();

const KeysChangedSignalType Xfc::Gdk::Keymap::keys_changed_signal [static, protected]
 

Keys changed signal (see signal_keys_changed()).

Calls a slot with the signature: 

             void function();

The documentation for this class was generated from the following file: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3