#[repr(transparent)]
pub struct Keymap { /* private fields */ }
Expand description

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

Implementations

Returns whether the Caps Lock modifer is locked.

Returns

true if Caps Lock is on

Returns the direction of effective layout of the keymap.

Returns

pango::Direction::Ltr or pango::Direction::Rtl if it can determine the direction. pango::Direction::Neutral otherwise.

Returns the modifier mask the self’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 ModifierType::MOD1_MASK rather than ModifierType::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 add_virtual_modifiers() in order to contain the expected result.

intent

the use case for the modifier mask

Returns

the modifier mask used for intent.

Returns the current modifier state.

Returns

the current modifier state.

Returns whether the Num Lock modifer is locked.

Returns

true if Num Lock is on

Returns whether the Scroll Lock modifer is locked.

Returns

true if Scroll Lock is on

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

Returns

true if there are layouts in both directions, false otherwise

Translates the contents of a 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][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, 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 `` should be masked out.

⚠️ The following code is in C ⚠️

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

⚠️ The following code is in C ⚠️

// 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>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. Storeplus, not <Control>plus,

hardware_keycode

a keycode

state

a modifier state

group

active keyboard group

Returns

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

keyval

return location for keyval, or None

effective_group

return location for effective group, or None

level

return location for level, or None

consumed_modifiers

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

Returns the Keymap attached to display.

display

the Display.

Returns

the Keymap attached to display.

The ::direction-changed signal gets emitted when the direction of the keymap changes.

The ::keys-changed signal is emitted when the mapping represented by keymap changes.

The ::state-changed signal is emitted when the state of the keyboard changes, e.g when Caps Lock is turned on or off. See is_caps_locked().

Returns the keyvals bound to hardware_keycode. The Nth 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 translate_keyboard_state().

hardware_keycode

a keycode

Returns

true if there were any entries

keys

return location for array of KeymapKey, or None

keyvals

return location for array of keyvals, or None

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

keyval

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

Returns

true if keys were found and returned

keys

return location for an array of KeymapKey

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.

state

pointer to the modifier mask to change

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.

state

pointer to the modifier state to map

Returns

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.

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 translate_keyboard_state() instead of this function, since the effective group/level may not be the same as the current keyboard state.

key

a KeymapKey with keycode, group, and level initialized

Returns

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

Trait Implementations

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Formats the value using the given formatter. Read more
Feeds this value into the given Hasher. Read more
Feeds a slice of this type into the given Hasher. Read more
This method returns an Ordering between self and other. Read more
Compares and returns the maximum of two values. Read more
Compares and returns the minimum of two values. Read more
Restrict a value to a certain interval. Read more
This method tests for self and other values to be equal, and is used by ==. Read more
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more
This method returns an ordering between self and other values if one exists. Read more
This method tests less than (for self and other) and is used by the < operator. Read more
This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
This method tests greater than (for self and other) and is used by the > operator. Read more
This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
Returns the type identifier of Self.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
Upcasts an object to a superclass or interface T. Read more
Upcasts an object to a reference of its superclass or interface T. Read more
Tries to downcast to a subclass or interface implementor T. Read more
Tries to downcast to a reference of its subclass or interface implementor T. Read more
Tries to cast to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more
Tries to cast to reference to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more
Casts to T unconditionally. Read more
Casts to &T unconditionally. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Returns true if the object is an instance of (can be cast to) T.
Returns the type of the object.
Returns the ObjectClass of the object. Read more
Returns the class of the object.
Returns the class of the object in the given type T. Read more
Returns the interface T of the object. Read more
Sets the property property_name of the object to value value. Read more
Sets the property property_name of the object to value value. Read more
Sets multiple properties of the object at once. Read more
Sets multiple properties of the object at once. Read more
Gets the property property_name of the object and cast it to the type V. Read more
Gets the property property_name of the object. Read more
Check if the object has a property property_name of the given type_. Read more
Get the type of the property property_name of this object. Read more
Get the ParamSpec of the property property_name of this object.
Return all ParamSpec of the properties of this object.
Freeze all property notifications until the return guard object is dropped. Read more
Set arbitrary data on this object with the given key. Read more
Return previously set arbitrary data of this object with the given key. Read more
Retrieve previously set arbitrary data of this object with the given key. Read more
Set arbitrary data on this object with the given key. Read more
Return previously set arbitrary data of this object with the given key. Read more
Retrieve previously set arbitrary data of this object with the given key. Read more
Block a given signal handler. Read more
Unblock a given signal handler.
Stop emission of the currently emitted signal.
Stop emission of the currently emitted signal by the (possibly detailed) signal name.
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect a closure to the signal signal_name on this object. Read more
Connect a closure to the signal signal_id on this object. Read more
Limits the lifetime of closure to the lifetime of the object. When the object’s reference count drops to zero, the closure will be invalidated. An invalidated closure will ignore any calls to invoke_with_values, or invoke when using Rust closures. Read more
Emit signal by signal id. Read more
Same as Self::emit but takes Value for the arguments.
Emit signal by its name. Read more
Emit signal by its name. Read more
Emit signal by its name with details. Read more
Emit signal by its name with details. Read more
Emit signal by signal id with details. Read more
Emit signal by signal id with details. Read more
Disconnect a previously connected signal handler.
Connect to the notify signal of the object. Read more
Connect to the notify signal of the object. Read more
Connect to the notify signal of the object. Read more
Notify that the given property has changed its value. Read more
Notify that the given property has changed its value. Read more
Downgrade this object to a weak reference.
Add a callback to be notified when the Object is disposed.
Add a callback to be notified when the Object is disposed. Read more
Bind property source_property on this object to the target_property on the target object. Read more
Returns the strong reference count of this object.
Ensures that the type has been registered with the type system.
The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
Converts the given value to a String. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.