Convenience helpers for working with keyboard inputs.
Using Keyboard this way, you get all the help it can provide. Use either this approach, or the plain subscriptions and handle the state yourself.
Keyboard
's internal message type.
subscriptions : Platform.Sub.Sub Msg
The subscriptions needed for the "Msg and Update" way.
updateWithParser : KeyParser -> Msg -> List Key -> List Key
A more advanced version of update
. Provide it with a smaller KeyParser
than anyKey
and
it will perform a little bit faster.
The second value updateWithKeyChange
may return, representing the actual
change that happened during the update.
updateWithKeyChange : KeyParser -> Msg -> List Key -> ( List Key, Maybe KeyChange )
This alternate update function answers the question: "Did the pressed down keys in fact change just now?"
You might be wondering why this is a Maybe KeyChange
– it's because
keydown
events happen many times per second when you hold down a key. Thus,
not all incoming messages actually cause a change in the model. Also, you will
only get updates for the keys that match your KeyParser
.
An unprocessed key value.
Use a KeyParser
to turn it into something useful.
RawKey -> Maybe Key
A key parser can turn RawKey
s into meaningful Key
s for your program.
anyKeyUpper : KeyParser
This parser tries to match with all the keys I can recognize. Spacebar
is used for the space
key and Character
s are all uppercase. This parser is used in update
.
If the key doesn't match any of the categories, Nothing
is returned.
Note: If you experience performance issues, you can use oneOf
with some specific parsers.
anyKeyOriginal : KeyParser
The same as anyKeyUpper
, but with Character
s in the original case.
characterKeyUpper : RawKey -> Maybe Key
Returns the character that was pressed, always uppercase.
NOTE There is no reasonable way of actually telling if a certain key is a character or not. For now at least, consider this a Western language focused "best guess".
Examples on a US layout:
[A] -> Just (Character "A")
[Shift] + [A] -> Just (Character "A")
[Shift] + [1] -> Just (Character "!")
[Shift] -> Nothing
characterKeyOriginal : RawKey -> Maybe Key
Returns the character that was pressed, in the original case.
NOTE There is no reasonable way of actually telling if a certain key is a character or not. For now at least, consider this a Western language focused "best guess".
Examples on a US layout:
[A] -> Just (Character "a")
[Shift] + [A] -> Just (Character "A")
[Shift] + [1] -> Just (Character "!")
[Shift] -> Nothing
modifierKey : RawKey -> Maybe Key
Converts a RawKey
if it is one of the modifier keys.
[Alt] -> Just Alt
[Tab] -> Nothing
whitespaceKey : RawKey -> Maybe Key
Converts a RawKey
if it is one of the whitespace keys.
[Tab] -> Just Tab
[Alt] -> Nothing
navigationKey : RawKey -> Maybe Key
Converts a RawKey
if it is one of the navigation keys.
[ArrowLeft] -> Just ArrowLeft
[A] -> Nothing
editingKey : RawKey -> Maybe Key
Converts a RawKey
if it is one of the editing keys.
[Backspace] -> Just Backspace
[Enter] -> Nothing
functionKey : RawKey -> Maybe Key
Converts a RawKey
if it is one of the function keys.
[F4] -> Just F4
[6] -> Nothing
phoneKey : RawKey -> Maybe Key
Converts a RawKey
if it is one of the phone keys.
mediaKey : RawKey -> Maybe Key
Converts a RawKey
if it is one of the media keys.
oneOf : List KeyParser -> RawKey -> Maybe Key
Turn any RawKey
into a Key
using the processing functions (modifierKey
, whitespaceKey
,
etc.) provided. If the key doesn't match any of the categories, Nothing
is returned.
If you prefer to only get "the facts" and do your own handling, use these subscriptions. Otherwise, you may be more comfortable with the Msg and Update.
downs : (RawKey -> msg) -> Platform.Sub.Sub msg
Subscription for key down events.
Note When the user presses and holds a key, there may or may not be many of these messages before the corresponding key up message.
ups : (RawKey -> msg) -> Platform.Sub.Sub msg
Subscription for key up events.
rawValue : RawKey -> String
Get the original string value of the RawKey
.
eventKeyDecoder : Json.Decode.Decoder RawKey
Use this with Html keyboard events to retrieve a RawKey
representing the key
which triggered the event.
Html.Events.on "keydown" eventKeyDecoder
These are all the keys that have names in Keyboard
.