brick-1.9: A declarative terminal user interface library

Safe Haskell | Safe-Inferred
Language | Haskell2010

Brick.Keybindings.KeyConfig

Contents

- Specifying bindings
- Querying KeyConfigs
- Misc

Description

This module provides `KeyConfig` and associated functions. A `KeyConfig` is the basis for the custom keybinding system in this library.

To get started, see `newKeyConfig`. Once a `KeyConfig` has been constructed, see `keyDispatcher`.

Since a key configuration can have keys bound to multiple events, it is the application author's responsibility to check for collisions since the nature of the collisions will depend on how the application is implemented. To check for collisions, use the result of `keyEventMappings`.

Synopsis

- data KeyConfig k
- newKeyConfig :: Ord k => KeyEvents k -> [(k, [Binding])] -> [(k, BindingState)] -> KeyConfig k
- data BindingState
  - = BindingList [Binding]
  - | Unbound
- data Binding = Binding {
  - kbKey :: Key
  - kbMods :: Set Modifier
  }
- class ToBinding a where
  - bind :: a -> Binding
- binding :: Key -> [Modifier] -> Binding
- fn :: Int -> Binding
- meta :: ToBinding a => a -> Binding
- ctrl :: ToBinding a => a -> Binding
- shift :: ToBinding a => a -> Binding
- firstDefaultBinding :: (Show k, Ord k) => KeyConfig k -> k -> Maybe Binding
- firstActiveBinding :: (Show k, Ord k) => KeyConfig k -> k -> Maybe Binding
- allDefaultBindings :: Ord k => KeyConfig k -> k -> [Binding]
- allActiveBindings :: (Show k, Ord k) => KeyConfig k -> k -> [Binding]
- keyEventMappings :: (Ord k, Eq k) => KeyConfig k -> [(Binding, Set k)]
- keyConfigEvents :: KeyConfig k -> KeyEvents k
- lookupKeyConfigBindings :: Ord k => KeyConfig k -> k -> Maybe BindingState

# Documentation

data KeyConfig k Source #

A configuration of custom key bindings. A `KeyConfig` stores everything needed to resolve a key event into one or more key bindings. Make a `KeyConfig` with `newKeyConfig`, then use it to dispatch to `KeyEventHandler`s with `keyDispatcher`.

Make a new `KeyConfig` with `newKeyConfig`.

A `KeyConfig` stores:

- A collection of named key events, mapping the event type `k` to `Text` labels.
- For each event `k`, optionally store a list of default key bindings for that event.
- An optional customized binding list for each event, setting the event to either `Unbound` or providing explicit overridden bindings with `BindingList`.

#### Instances

Instances details

Show k => Show (KeyConfig k) Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods showsPrec :: Int -> KeyConfig k -> ShowS Source # show :: KeyConfig k -> String Source # showList :: [KeyConfig k] -> ShowS Source #
Eq k => Eq (KeyConfig k) Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods (==) :: KeyConfig k -> KeyConfig k -> Bool Source # (/=) :: KeyConfig k -> KeyConfig k -> Bool Source #

newKeyConfig Source #

Arguments

:: Ord k |
=> KeyEvents k | The base mapping of key events and names to use.
-> [(k, [Binding])] | Default bindings by key event, such as from a configuration file or embedded code. Optional on a per-event basis.
-> [(k, BindingState)] | Custom bindings by key event, such as from a configuration file. Explicitly setting an event to `Unbound` here has the effect of disabling its default bindings. Optional on a per-event basis. Note that this function does not check for collisions since it is up to the application to determine whether a key bound to more than one event constitutes a collision!
-> KeyConfig k |

Build a `KeyConfig` with the specified `KeyEvents` event-to-name mapping, list of default bindings by event, and list of custom bindings by event.

data BindingState Source #

An explicit configuration of key bindings for a key event.

Constructors

BindingList [Binding] | Bind the event to the specified list of bindings.
Unbound | Disable all bindings for the event, including default bindings.

#### Instances

Instances details

Show BindingState Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods showsPrec :: Int -> BindingState -> ShowS Source # show :: BindingState -> String Source # showList :: [BindingState] -> ShowS Source #
Eq BindingState Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods (==) :: BindingState -> BindingState -> Bool Source # (/=) :: BindingState -> BindingState -> Bool Source #
Ord BindingState Source # |

Instance details

Defined in Brick.Keybindings.KeyConfig

Methods

compare :: BindingState -> BindingState -> Ordering Source #

(<) :: BindingState -> BindingState -> Bool Source #

(<=) :: BindingState -> BindingState -> Bool Source #

(>) :: BindingState -> BindingState -> Bool Source #

(>=) :: BindingState -> BindingState -> Bool Source #

max :: BindingState -> BindingState -> BindingState Source #

min :: BindingState -> BindingState -> BindingState Source #

# Specifying bindings

data Binding Source #

A key binding.

The easiest way to express `Binding`s is to use the helper functions in this module that work with instances of `ToBinding`, e.g.

    let ctrlB = ctrl 'b'
        shiftX = shift 'x'
        ctrlMetaK = ctrl $ meta 'k'
        -- Or with Vty keys directly:
        ctrlDown = ctrl KDown

Constructors

Binding |

Fields

- kbKey :: Key

  The key itself.

- kbMods :: Set Modifier

  The set of modifiers.

#### Instances

Instances details

Show Binding Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods showsPrec :: Int -> Binding -> ShowS Source # show :: Binding -> String Source # showList :: [Binding] -> ShowS Source #
ToBinding Binding Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods bind :: Binding -> Binding Source #
Eq Binding Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods (==) :: Binding -> Binding -> Bool Source # (/=) :: Binding -> Binding -> Bool Source #
Ord Binding Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods compare :: Binding -> Binding -> Ordering Source # (<) :: Binding -> Binding -> Bool Source # (<=) :: Binding -> Binding -> Bool Source # (>) :: Binding -> Binding -> Bool Source # (>=) :: Binding -> Binding -> Bool Source # max :: Binding -> Binding -> Binding Source # min :: Binding -> Binding -> Binding Source #

class ToBinding a where Source #

The class of types that can form the basis of `Binding`s.

This is provided to make it easy to write and modify bindings in less verbose ways.

Methods

bind :: a -> Binding Source #

Binding constructor.

#### Instances

Instances details

ToBinding Binding Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods bind :: Binding -> Binding Source #
ToBinding Key Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods bind :: Key -> Binding Source #
ToBinding Char Source # |
Instance details Defined in Brick.Keybindings.KeyConfig Methods bind :: Char -> Binding Source #

binding :: Key -> [Modifier] -> Binding Source #

Construct a `Binding`. Modifier order is ignored.

fn :: Int -> Binding Source #

Function key binding.

meta :: ToBinding a => a -> Binding Source #

Add Meta to a binding.

ctrl :: ToBinding a => a -> Binding Source #

Add Ctrl to a binding.

shift :: ToBinding a => a -> Binding Source #

Add Shift to a binding.

# Querying KeyConfigs

firstDefaultBinding :: (Show k, Ord k) => KeyConfig k -> k -> Maybe Binding Source #

A convenience function to return the first result of `allDefaultBindings`, if any.

firstActiveBinding :: (Show k, Ord k) => KeyConfig k -> k -> Maybe Binding Source #

A convenience function to return the first result of `allActiveBindings`, if any.

allDefaultBindings :: Ord k => KeyConfig k -> k -> [Binding] Source #

Returns the list of default bindings for the specified event, irrespective of whether the event has been explicitly configured with other bindings or set to `Unbound`.

allActiveBindings :: (Show k, Ord k) => KeyConfig k -> k -> [Binding] Source #

Return all active key bindings for the specified event. This returns customized bindings if any have been set in the `KeyConfig`, no bindings if the event has been explicitly set to `Unbound`, or the default bindings if the event is absent from the customized bindings.

keyEventMappings :: (Ord k, Eq k) => KeyConfig k -> [(Binding, Set k)] Source #

Return a list of mappings including each key bound to any event combined with the list of events to which it is bound. This is useful for identifying problematic key binding collisions. Since key binding collisions cannot be determined in general, we leave it up to the application author to determine which key-to-event bindings are problematic.

# Misc

keyConfigEvents :: KeyConfig k -> KeyEvents k Source #

The base mapping of events and their names that is used in this configuration.

lookupKeyConfigBindings :: Ord k => KeyConfig k -> k -> Maybe BindingState Source #

Look up the binding state for the specified event. This returns `Nothing` when the event has no explicitly configured custom `BindingState`.