GI.Gdk.Objects.Keymap

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.

Exported types

newtype Keymap

Constructors

Keymap (ManagedPtr Keymap)

Instances

GObject Keymap

Methods

gobjectType :: Keymap -> IO GType

IsObject Keymap

IsKeymap Keymap

((~) * info (ResolveKeymapMethod t Keymap), MethodInfo * info Keymap p) => IsLabel t (Keymap -> p)

Methods

fromLabel :: Proxy# Symbol t -> Keymap -> p

((~) * info (ResolveKeymapMethod t Keymap), MethodInfo * info Keymap p) => IsLabelProxy t (Keymap -> p)

Methods

fromLabelProxy :: Proxy Symbol t -> Keymap -> p

HasAttributeList * Keymap

type AttributeList Keymap

type AttributeList Keymap

type SignalList Keymap

type SignalList Keymap

class GObject o => IsKeymap o

Instances

(GObject a, UnknownAncestorError Constraint Keymap a) => IsKeymap a

IsKeymap Keymap

toKeymap :: IsKeymap o => o -> IO Keymap

noKeymap :: Maybe Keymap

Methods

addVirtualModifiers

data KeymapAddVirtualModifiersMethodInfo

Instances

((~) * signature ([ModifierType] -> m [ModifierType]), MonadIO m, IsKeymap a) => MethodInfo * KeymapAddVirtualModifiersMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapAddVirtualModifiersMethodInfo a -> signature -> s

keymapAddVirtualModifiers

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> [ModifierType]

state: pointer to the modifier mask to change

-> m [ModifierType]

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.

Since: 2.20

getCapsLockState

data KeymapGetCapsLockStateMethodInfo

Instances

((~) * signature (m Bool), MonadIO m, IsKeymap a) => MethodInfo * KeymapGetCapsLockStateMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapGetCapsLockStateMethodInfo a -> signature -> s

keymapGetCapsLockState

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> m Bool

Returns: True if Caps Lock is on

Returns whether the Caps Lock modifer is locked.

Since: 2.16

getDefault

keymapGetDefault

Arguments

:: (HasCallStack, MonadIO m)

=> m Keymap

Returns: the Keymap attached to the default display.

Returns the Keymap attached to the default display.

getDirection

data KeymapGetDirectionMethodInfo

Instances

((~) * signature (m Direction), MonadIO m, IsKeymap a) => MethodInfo * KeymapGetDirectionMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapGetDirectionMethodInfo a -> signature -> s

keymapGetDirection

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> m Direction

Returns: DirectionLtr or DirectionRtl if it can determine the direction. DirectionNeutral otherwise.

Returns the direction of effective layout of the keymap.

getEntriesForKeycode

data KeymapGetEntriesForKeycodeMethodInfo

Instances

((~) * signature (Word32 -> m (Bool, [KeymapKey], [Word32])), MonadIO m, IsKeymap a) => MethodInfo * KeymapGetEntriesForKeycodeMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapGetEntriesForKeycodeMethodInfo a -> signature -> s

keymapGetEntriesForKeycode

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> Word32

hardwareKeycode: a keycode

-> m (Bool, [KeymapKey], [Word32])

Returns: True if there were any entries

Returns the keyvals bound to hardwareKeycode. The Nth KeymapKey in keys is bound to the Nth keyval in keyvals. Free the returned arrays with 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 keymapTranslateKeyboardState.

getEntriesForKeyval

data KeymapGetEntriesForKeyvalMethodInfo

Instances

((~) * signature (Word32 -> m (Bool, [KeymapKey])), MonadIO m, IsKeymap a) => MethodInfo * KeymapGetEntriesForKeyvalMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapGetEntriesForKeyvalMethodInfo a -> signature -> s

keymapGetEntriesForKeyval

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> Word32

keyval: a keyval, such as KEY_a, KEY_Up, KEY_Return, etc.

-> m (Bool, [KeymapKey])

Returns: True if keys were found and returned

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

getForDisplay

keymapGetForDisplay

Arguments

:: (HasCallStack, MonadIO m, IsDisplay a)

=> a

display: the Display.

-> m Keymap

Returns: the Keymap attached to display.

Returns the Keymap attached to display.

Since: 2.2

getModifierMask

data KeymapGetModifierMaskMethodInfo

Instances

((~) * signature (ModifierIntent -> m [ModifierType]), MonadIO m, IsKeymap a) => MethodInfo * KeymapGetModifierMaskMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapGetModifierMaskMethodInfo a -> signature -> s

keymapGetModifierMask

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> ModifierIntent

intent: the use case for the modifier mask

-> m [ModifierType]

Returns: the modifier mask used for intent.

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 keymapAddVirtualModifiers in order to contain the expected result.

Since: 3.4

getModifierState

data KeymapGetModifierStateMethodInfo

Instances

((~) * signature (m Word32), MonadIO m, IsKeymap a) => MethodInfo * KeymapGetModifierStateMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapGetModifierStateMethodInfo a -> signature -> s

keymapGetModifierState

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> m Word32

Returns: the current modifier state.

Returns the current modifier state.

Since: 3.4

getNumLockState

data KeymapGetNumLockStateMethodInfo

Instances

((~) * signature (m Bool), MonadIO m, IsKeymap a) => MethodInfo * KeymapGetNumLockStateMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapGetNumLockStateMethodInfo a -> signature -> s

keymapGetNumLockState

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> m Bool

Returns: True if Num Lock is on

Returns whether the Num Lock modifer is locked.

Since: 3.0

getScrollLockState

data KeymapGetScrollLockStateMethodInfo

Instances

((~) * signature (m Bool), MonadIO m, IsKeymap a) => MethodInfo * KeymapGetScrollLockStateMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapGetScrollLockStateMethodInfo a -> signature -> s

keymapGetScrollLockState

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> m Bool

Returns: True if Scroll Lock is on

Returns whether the Scroll Lock modifer is locked.

Since: 3.18

haveBidiLayouts

data KeymapHaveBidiLayoutsMethodInfo

Instances

((~) * signature (m Bool), MonadIO m, IsKeymap a) => MethodInfo * KeymapHaveBidiLayoutsMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapHaveBidiLayoutsMethodInfo a -> signature -> s

keymapHaveBidiLayouts

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> m Bool

Returns: True if there are layouts in both directions, False otherwise

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

Since: 2.12

lookupKey

data KeymapLookupKeyMethodInfo

Instances

((~) * signature (KeymapKey -> m Word32), MonadIO m, IsKeymap a) => MethodInfo * KeymapLookupKeyMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapLookupKeyMethodInfo a -> signature -> s

keymapLookupKey

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> KeymapKey

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

-> m Word32

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

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

mapVirtualModifiers

data KeymapMapVirtualModifiersMethodInfo

Instances

((~) * signature ([ModifierType] -> m (Bool, [ModifierType])), MonadIO m, IsKeymap a) => MethodInfo * KeymapMapVirtualModifiersMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapMapVirtualModifiersMethodInfo a -> signature -> s

keymapMapVirtualModifiers

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> [ModifierType]

state: pointer to the modifier state to map

-> m (Bool, [ModifierType])

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.

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.

Since: 2.20

translateKeyboardState

data KeymapTranslateKeyboardStateMethodInfo

Instances

((~) * signature (Word32 -> [ModifierType] -> Int32 -> m (Bool, Word32, Int32, Int32, [ModifierType])), MonadIO m, IsKeymap a) => MethodInfo * KeymapTranslateKeyboardStateMethodInfo a signature

Methods

overloadedMethod :: MethodProxy KeymapTranslateKeyboardStateMethodInfo a -> signature -> s

keymapTranslateKeyboardState

Arguments

:: (HasCallStack, MonadIO m, IsKeymap a)

=> a

keymap: a Keymap

-> Word32

hardwareKeycode: a keycode

-> [ModifierType]

state: a modifier state

-> Int32

group: active keyboard group

-> m (Bool, Word32, Int32, Int32, [ModifierType])

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

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 consumedModifiers. See [Groups][key-group-explanation] for an explanation of groups and levels. The effectiveGroup 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.

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

C code

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

C code

// 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 consumedModifiers; 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,

Signals

directionChanged

type C_KeymapDirectionChangedCallback = Ptr () -> Ptr () -> IO ()

type KeymapDirectionChangedCallback = IO ()

data KeymapDirectionChangedSignalInfo

Instances

SignalInfo KeymapDirectionChangedSignalInfo

Associated Types

type HaskellCallbackType KeymapDirectionChangedSignalInfo :: *

Methods

connectSignal :: GObject o => SignalProxy o KeymapDirectionChangedSignalInfo -> o -> HaskellCallbackType KeymapDirectionChangedSignalInfo -> SignalConnectMode -> IO SignalHandlerId

type HaskellCallbackType KeymapDirectionChangedSignalInfo

type HaskellCallbackType KeymapDirectionChangedSignalInfo = KeymapDirectionChangedCallback

afterKeymapDirectionChanged :: (GObject a, MonadIO m) => a -> KeymapDirectionChangedCallback -> m SignalHandlerId

genClosure_KeymapDirectionChanged :: KeymapDirectionChangedCallback -> IO Closure

mk_KeymapDirectionChangedCallback :: C_KeymapDirectionChangedCallback -> IO (FunPtr C_KeymapDirectionChangedCallback)

noKeymapDirectionChangedCallback :: Maybe KeymapDirectionChangedCallback

onKeymapDirectionChanged :: (GObject a, MonadIO m) => a -> KeymapDirectionChangedCallback -> m SignalHandlerId

wrap_KeymapDirectionChangedCallback :: KeymapDirectionChangedCallback -> Ptr () -> Ptr () -> IO ()

keysChanged

type C_KeymapKeysChangedCallback = Ptr () -> Ptr () -> IO ()

type KeymapKeysChangedCallback = IO ()

data KeymapKeysChangedSignalInfo

Instances

SignalInfo KeymapKeysChangedSignalInfo

Associated Types

type HaskellCallbackType KeymapKeysChangedSignalInfo :: *

Methods

connectSignal :: GObject o => SignalProxy o KeymapKeysChangedSignalInfo -> o -> HaskellCallbackType KeymapKeysChangedSignalInfo -> SignalConnectMode -> IO SignalHandlerId

type HaskellCallbackType KeymapKeysChangedSignalInfo

type HaskellCallbackType KeymapKeysChangedSignalInfo = KeymapKeysChangedCallback

afterKeymapKeysChanged :: (GObject a, MonadIO m) => a -> KeymapKeysChangedCallback -> m SignalHandlerId

genClosure_KeymapKeysChanged :: KeymapKeysChangedCallback -> IO Closure

mk_KeymapKeysChangedCallback :: C_KeymapKeysChangedCallback -> IO (FunPtr C_KeymapKeysChangedCallback)

noKeymapKeysChangedCallback :: Maybe KeymapKeysChangedCallback

onKeymapKeysChanged :: (GObject a, MonadIO m) => a -> KeymapKeysChangedCallback -> m SignalHandlerId

wrap_KeymapKeysChangedCallback :: KeymapKeysChangedCallback -> Ptr () -> Ptr () -> IO ()

stateChanged

type C_KeymapStateChangedCallback = Ptr () -> Ptr () -> IO ()

type KeymapStateChangedCallback = IO ()

data KeymapStateChangedSignalInfo

Instances

SignalInfo KeymapStateChangedSignalInfo

Associated Types

type HaskellCallbackType KeymapStateChangedSignalInfo :: *

Methods

connectSignal :: GObject o => SignalProxy o KeymapStateChangedSignalInfo -> o -> HaskellCallbackType KeymapStateChangedSignalInfo -> SignalConnectMode -> IO SignalHandlerId

type HaskellCallbackType KeymapStateChangedSignalInfo

type HaskellCallbackType KeymapStateChangedSignalInfo = KeymapStateChangedCallback

afterKeymapStateChanged :: (GObject a, MonadIO m) => a -> KeymapStateChangedCallback -> m SignalHandlerId

genClosure_KeymapStateChanged :: KeymapStateChangedCallback -> IO Closure

mk_KeymapStateChangedCallback :: C_KeymapStateChangedCallback -> IO (FunPtr C_KeymapStateChangedCallback)

noKeymapStateChangedCallback :: Maybe KeymapStateChangedCallback

onKeymapStateChanged :: (GObject a, MonadIO m) => a -> KeymapStateChangedCallback -> m SignalHandlerId

wrap_KeymapStateChangedCallback :: KeymapStateChangedCallback -> Ptr () -> Ptr () -> IO ()