In JavaScript, information about the root of an HTML document is held in
the document
and window
objects. This module lets you create event
listeners on those objects for the following topics: animation,
keyboard, mouse, and window.
If there is something else you need, use ports to do it in JavaScript!
onAnimationFrame : (Time.Posix -> msg) -> Platform.Sub.Sub msg
An animation frame triggers about 60 times per second. Get the POSIX time
on each frame. (See elm/time
for more info on
POSIX times.)
Note: Browsers have their own render loop, repainting things as fast as
possible. If you want smooth animations in your application, it is helpful to
sync up with the browsers natural refresh rate. This hooks into JavaScript's
requestAnimationFrame
function.
onAnimationFrameDelta : (Basics.Float -> msg) -> Platform.Sub.Sub msg
Just like onAnimationFrame
, except message is the time in milliseconds
since the previous frame. So you should get a sequence of values all around
1000 / 60
which is nice for stepping animations by a time delta.
onKeyPress : Json.Decode.Decoder msg -> Platform.Sub.Sub msg
Subscribe to key presses that normally produce characters. So you should not rely on this for arrow keys.
Note: Check out this advice to learn more about decoding key codes. It is more complicated than it should be.
onKeyDown : Json.Decode.Decoder msg -> Platform.Sub.Sub msg
Subscribe to get codes whenever a key goes down. This can be useful for
creating games. Maybe you want to know if people are pressing w
, a
, s
,
or d
at any given time.
Note: Check out this advice to learn more about decoding key codes. It is more complicated than it should be.
onKeyUp : Json.Decode.Decoder msg -> Platform.Sub.Sub msg
Subscribe to get codes whenever a key goes up. Often used in combination
with onVisibilityChange
to be sure keys do not appear
to down and never come back up.
onClick : Json.Decode.Decoder msg -> Platform.Sub.Sub msg
Subscribe to mouse clicks anywhere on screen. Maybe you need to create a custom drop down. You could listen for clicks when it is open, letting you know if someone clicked out of it:
import Browser.Events as Events
import Json.Decode as D
type Msg
= ClickOut
subscriptions : Model -> Sub Msg
subscriptions model =
case model.dropDown of
Closed _ ->
Sub.none
Open _ ->
Events.onClick (D.succeed ClickOut)
onMouseMove : Json.Decode.Decoder msg -> Platform.Sub.Sub msg
Subscribe to mouse moves anywhere on screen.
You could use this to implement resizable panels like in Elm's online code editor. Check out the example imprementation here.
Note: Unsubscribe if you do not need these events! Running code on every single mouse movement can be very costly, and it is recommended to only subscribe when absolutely necessary.
onMouseDown : Json.Decode.Decoder msg -> Platform.Sub.Sub msg
Subscribe to get mouse information whenever the mouse button goes down.
onMouseUp : Json.Decode.Decoder msg -> Platform.Sub.Sub msg
Subscribe to get mouse information whenever the mouse button goes up.
Often used in combination with onVisibilityChange
to be sure keys do not appear to down and never come back up.
onResize : (Basics.Int -> Basics.Int -> msg) -> Platform.Sub.Sub msg
Subscribe to any changes in window size.
For example, you could track the current width by saying:
import Browser.Events as E
type Msg
= GotNewWidth Int
subscriptions : model -> Cmd Msg
subscriptions _ =
E.onResize (\w h -> GotNewWidth w)
Note: This is equivalent to getting events from window.onresize
.
onVisibilityChange : (Visibility -> msg) -> Platform.Sub.Sub msg
Subscribe to any visibility changes, like if the user switches to a different tab or window. When the user looks away, you may want to:
onKeyUp
event.Value describing whether the page is hidden or visible.