leojpod / elm-keyboard-shortcut / Shortcut

This module provide a quick and simple (enough) way of listening for keyboard event by describing which shortcut you are interested in.

Shortcut description

The first important part of using this package is describing which shortcut should trigger which message. This can be done by instantiating the Shortcut record directly or via one of the utility function

Keys


type Key
    = Escape
    | BackSpace
    | Space
    | Tab
    | Enter
    | ArrowLeft
    | ArrowRight
    | ArrowUp
    | ArrowDown
    | ShiftLeft
    | ShiftRight
    | MetaLeft
    | MetaRight
    | AltLeft
    | AltRight
    | ControlLeft
    | ControlRight
    | Regular String

The Key is merely an easy way to define which key you are interested in. It has an entry for all the special keys and a constructor (Regular) for all the rest.

Shortcut record

In essence, a shortcut is just an indication of which key(s) we are interested in and a message that should be sent when a keyboard event matches out.


type alias Shortcut msg =
{ msg : msg
, keyCombination : { baseKey : Key
, alt : Maybe Basics.Bool
, shift : Maybe Basics.Bool
, ctrl : Maybe Basics.Bool
, meta : Maybe Basics.Bool } 
}

Shortcut is simply a record of a message and a keyCombination that describe the keyboard shortcut you're interested in.

Please note that the Maybe Bool for the alt, shift, ctrl and meta modifirs allows you to choose if you would like to ignore a modifier (Nothing), force it to be present (True) or force it to be abscent (False)

For instance the following key combination will match both Shift O and Ctrl Shift O but not Shift Meta O

myKeyCombination =
    { baseKey = Regular "O"
    , alt = Nothing
    , shift = Just True
    , ctrl = Nothing
    , meta = Just False
    }

Utility functions

simpleShortcut : Key -> msg -> Shortcut msg

if you're only interested in one key not in any of the modifiers then simpleShortcut is made for you. Both of these are equivalent:

myShortcut =
    { msg = SimpleMessage
    , keyCombination =
        { baseKey = Regular "O"
        , alt = Nothing
        , shift = Nothing
        , ctrl = Nothing
        , meta = Nothing
        }
    }

mySimpleShortcut =
    simpleShortcut <| Regular "O"

esc : msg -> Shortcut msg

alias of simpleShortcut Escape

altShortcut : Key -> msg -> Shortcut msg

equivalent of setting all the modifiers to Nothing and the alt modifier to Just True

shiftShortcut : Key -> msg -> Shortcut msg

equivalent of setting all the modifiers to Nothing and the shift modifier to Just True

ctrlShortcut : Key -> msg -> Shortcut msg

equivalent of setting all the modifiers to Nothing and the ctrl modifier to Just True

metaShortcut : Key -> msg -> Shortcut msg

equivalent of setting all the modifiers to Nothing and the meta modifier to Just True

Shortcut capture

The capture part is taken care of by the custom-element that comes with this package. For a reminder on how to install it, please have a look at the README.

shortcutElement : List (Shortcut msg) -> List (Html.Attribute msg) -> List (Html msg) -> Html msg

This is the elm wrapper for the custom-element provided by the NPM companion package