gi-gdk-3.0.29: Gdk bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | Safe-Inferred
Language | Haskell2010

GI.Gdk.Objects.Keymap

Contents

- Exported types
- Methods
  - addVirtualModifiers
  - getCapsLockState
  - getDefault
  - getDirection
  - getEntriesForKeycode
  - getEntriesForKeyval
  - getForDisplay
  - getModifierMask
  - getModifierState
  - getNumLockState
  - getScrollLockState
  - haveBidiLayouts
  - lookupKey
  - mapVirtualModifiers
  - translateKeyboardState
- Signals
  - directionChanged
  - keysChanged
  - stateChanged

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.

Synopsis

- newtype Keymap = Keymap (ManagedPtr Keymap)
- class (GObject o, IsDescendantOf Keymap o) => IsKeymap o
- toKeymap :: (MonadIO m, IsKeymap o) => o -> m Keymap
- keymapAddVirtualModifiers :: (HasCallStack, MonadIO m, IsKeymap a) => a -> [ModifierType] -> m [ModifierType]
- keymapGetCapsLockState :: (HasCallStack, MonadIO m, IsKeymap a) => a -> m Bool
- keymapGetDefault :: (HasCallStack, MonadIO m) => m Keymap
- keymapGetDirection :: (HasCallStack, MonadIO m, IsKeymap a) => a -> m Direction
- keymapGetEntriesForKeycode :: (HasCallStack, MonadIO m, IsKeymap a) => a -> Word32 -> m (Bool, [KeymapKey], [Word32])
- keymapGetEntriesForKeyval :: (HasCallStack, MonadIO m, IsKeymap a) => a -> Word32 -> m (Bool, [KeymapKey])
- keymapGetForDisplay :: (HasCallStack, MonadIO m, IsDisplay a) => a -> m Keymap
- keymapGetModifierMask :: (HasCallStack, MonadIO m, IsKeymap a) => a -> ModifierIntent -> m [ModifierType]
- keymapGetModifierState :: (HasCallStack, MonadIO m, IsKeymap a) => a -> m Word32
- keymapGetNumLockState :: (HasCallStack, MonadIO m, IsKeymap a) => a -> m Bool
- keymapGetScrollLockState :: (HasCallStack, MonadIO m, IsKeymap a) => a -> m Bool
- keymapHaveBidiLayouts :: (HasCallStack, MonadIO m, IsKeymap a) => a -> m Bool
- keymapLookupKey :: (HasCallStack, MonadIO m, IsKeymap a) => a -> KeymapKey -> m Word32
- keymapMapVirtualModifiers :: (HasCallStack, MonadIO m, IsKeymap a) => a -> [ModifierType] -> m (Bool, [ModifierType])
- keymapTranslateKeyboardState :: (HasCallStack, MonadIO m, IsKeymap a) => a -> Word32 -> [ModifierType] -> Int32 -> m (Bool, Word32, Int32, Int32, [ModifierType])
- type KeymapDirectionChangedCallback = IO ()
- afterKeymapDirectionChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapDirectionChangedCallback) -> m SignalHandlerId
- onKeymapDirectionChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapDirectionChangedCallback) -> m SignalHandlerId
- type KeymapKeysChangedCallback = IO ()
- afterKeymapKeysChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapKeysChangedCallback) -> m SignalHandlerId
- onKeymapKeysChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapKeysChangedCallback) -> m SignalHandlerId
- type KeymapStateChangedCallback = IO ()
- afterKeymapStateChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapStateChangedCallback) -> m SignalHandlerId
- onKeymapStateChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapStateChangedCallback) -> m SignalHandlerId

# Exported types

newtype Keymap Source #

Memory-managed wrapper type.

Constructors

Keymap (ManagedPtr Keymap) |

#### Instances

Instances details

Eq Keymap Source # |
Instance details Defined in GI.Gdk.Objects.Keymap Methods (==) :: Keymap -> Keymap -> Bool Source # (/=) :: Keymap -> Keymap -> Bool Source #
GObject Keymap Source # |
Instance details Defined in GI.Gdk.Objects.Keymap
ManagedPtrNewtype Keymap Source # |
Instance details Defined in GI.Gdk.Objects.Keymap Methods toManagedPtr :: Keymap -> ManagedPtr Keymap Source #
TypedObject Keymap Source # |
Instance details Defined in GI.Gdk.Objects.Keymap Methods glibType :: IO GType Source #
HasParentTypes Keymap Source # |
Instance details Defined in GI.Gdk.Objects.Keymap
IsGValue (Maybe Keymap) Source # | Convert `Keymap` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gdk.Objects.Keymap Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Keymap -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Keymap) Source #
type ParentTypes Keymap Source # |
Instance details Defined in GI.Gdk.Objects.Keymap type ParentTypes Keymap = '[Object]

class (GObject o, IsDescendantOf Keymap o) => IsKeymap o Source #

Type class for types which can be safely cast to `Keymap`, for instance with `toKeymap`.

#### Instances

Instances details

(GObject o, IsDescendantOf Keymap o) => IsKeymap o Source # |
Instance details Defined in GI.Gdk.Objects.Keymap

toKeymap :: (MonadIO m, IsKeymap o) => o -> m Keymap Source #

Cast to `Keymap`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

addVirtualModifiers, bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, haveBidiLayouts, isFloating, lookupKey, mapVirtualModifiers, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, translateKeyboardState, unref, watchClosure.

#### Getters

getCapsLockState, getData, getDirection, getEntriesForKeycode, getEntriesForKeyval, getModifierMask, getModifierState, getNumLockState, getProperty, getQdata, getScrollLockState.

#### Setters

setData, setDataFull, setProperty.

## addVirtualModifiers

keymapAddVirtualModifiers Source #

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

keymapGetCapsLockState Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m Keymap | Returns: the `Keymap` attached to the default display.

Deprecated: (Since version 3.22)Use `keymapGetForDisplay` instead

Returns the `Keymap` attached to the default display.

## getDirection

keymapGetDirection Source #

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

keymapGetEntriesForKeycode Source #

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

keymapGetEntriesForKeyval Source #

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 Source #

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

keymapGetModifierMask Source #

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

keymapGetModifierState Source #

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

keymapGetNumLockState Source #

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

keymapGetScrollLockState Source #

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

keymapHaveBidiLayouts Source #

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

keymapLookupKey Source #

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

keymapMapVirtualModifiers Source #

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

keymapTranslateKeyboardState Source #

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 KeymapDirectionChangedCallback = IO () Source #

The directionChanged signal gets emitted when the direction of the keymap changes.

Since: 2.0

afterKeymapDirectionChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapDirectionChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the directionChanged signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after keymap #directionChanged callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onKeymapDirectionChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapDirectionChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the directionChanged signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on keymap #directionChanged callback

## keysChanged

type KeymapKeysChangedCallback = IO () Source #

The keysChanged signal is emitted when the mapping represented by `keymap` changes.

Since: 2.2

afterKeymapKeysChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapKeysChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the keysChanged signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after keymap #keysChanged callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onKeymapKeysChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapKeysChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the keysChanged signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on keymap #keysChanged callback

## stateChanged

type KeymapStateChangedCallback = IO () Source #

The stateChanged signal is emitted when the state of the keyboard changes, e.g when Caps Lock is turned on or off. See `keymapGetCapsLockState`.

Since: 2.16

afterKeymapStateChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapStateChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the stateChanged signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after keymap #stateChanged callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onKeymapStateChanged :: (IsKeymap a, MonadIO m) => a -> ((?self :: a) => KeymapStateChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the stateChanged signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on keymap #stateChanged callback