Handling detailed mouse events.
{ keys : Keys
, button : Button
, clientPos : ( Basics.Float
, Basics.Float )
, offsetPos : ( Basics.Float
, Basics.Float )
, pagePos : ( Basics.Float
, Basics.Float )
, screenPos : ( Basics.Float
, Basics.Float )
}
Type that get returned by a browser mouse event. Its purpose is to provide all useful properties of JavaScript MouseEvent in the context of the elm programming language.
Coordinates of a specific kind (clientX/Y
, pageX/Y
, ...)
are available under the attribute of the same name grouped by pairs.
For example, if mouseEvent
is of type Mouse.Event
then
mouseEvent.clientPos
holds the ( clientX, clientY )
properties of the event.
For some applications like drawing in a canvas, relative coordinates are needed.
Beware that those coordinates are called offsetX/Y
in a mouse event.
Therefore they are available here with attribute offsetPos
.
relativePos : Mouse.Event -> ( Float, Float )
relativePos mouseEvent =
mouseEvent.offsetPos
The movementX/Y
properties not being compatible with Safari / iOS,
they are not provided by this package.
The x
and y
properties being equivalent to clientX/Y
,
are not provided either.
The screenPos
attribute provides screenX/Y
properties in case needed,
but you shall use instead the clientPos
attribute when in doubt.
screenX/Y
values are not given in CSS pixel sizes and thus not very useful.
More info is available in the excellent
article A tale of two viewports.
{ alt : Basics.Bool
, ctrl : Basics.Bool
, meta : Basics.Bool
, shift : Basics.Bool
}
The keys that might have been pressed during mouse event. Key modifiers of mouse events are available in the key attribute. Checking if the ctrl key was hold when the event triggered is as easy as:
isCtrlKeyPressed : Mouse.Event -> Bool
isCtrlKeyPressed mouseEvent =
mouseEvent.keys.ctrl
The button pressed for the event.
The button that was used to trigger the mouse event is available
in the button
attribute. However, beware that its value is not reliable
for events such as mouseenter
, mouseleave
, mouseover
, mouseout
or mousemove
.
The buttons
(with an "s") property of a mouse event is not provided here since
it is not compatible with mac / safari.
The three default mouse events are mousedown
, mousemove
and mouseup
.
onDown : (Event -> msg) -> Html.Attribute msg
Listen to mousedown
events.
Let's say that we have a message type like this:
type Msg
= DownMsg ( Float, Float )
| MoveMsg ( Float, Float )
| UpMsg ( Float, Float )
Then we could listen to mousedown
events like below:
div
[ Mouse.onDown (\event -> DownMsg event.clientPos) ]
[ text "click here" ]
In a curried style, this can also be written:
div
[ Mouse.onDown (.clientPos >> DownMsg) ]
[ text "click here" ]
onMove : (Event -> msg) -> Html.Attribute msg
Listen to mousemove
events.
Similarly than with onDown
, we can write something like:
div
[ Mouse.onMove (.clientPos >> MoveMsg) ]
[ text "move here" ]
onUp : (Event -> msg) -> Html.Attribute msg
Listen to mouseup
events.
Similarly than with onDown
, we can write something like:
div
[ Mouse.onUp (.clientPos >> UpMsg) ]
[ text "click here" ]
The other supported events by this library are
click
, dblclick
, mouseenter
, mouseover
, mouseleave
and mouseout
.
You can use them exactly like the previous examples.
onClick : (Event -> msg) -> Html.Attribute msg
Listen to click
events.
onDoubleClick : (Event -> msg) -> Html.Attribute msg
Listen to dblclick
events.
onEnter : (Event -> msg) -> Html.Attribute msg
Listen to mouseenter
events.
This event is fired when a mouse is moved over the element
that has the listener attached.
It is similar to mouseover
but doesn't bubble.
More details available on the MDN documentation.
onOver : (Event -> msg) -> Html.Attribute msg
Listen to mouseover
events.
onLeave : (Event -> msg) -> Html.Attribute msg
Listen to mouseleave
events.
This event is fired when a mouse is moved out of the element
that has the listener attached.
It is similar to mouseout
but doesn't bubble.
More details available on the MDN documentation.
onOut : (Event -> msg) -> Html.Attribute msg
Listen to mouseout
events.
onContextMenu : (Event -> msg) -> Html.Attribute msg
Listen to contextmenu
events.
Fired on right mousedown, before the context menu is displayed.
{ stopPropagation : Basics.Bool
, preventDefault : Basics.Bool
}
Options for the event.
onWithOptions : String -> EventOptions -> (Event -> msg) -> Html.Attribute msg
Choose the mouse event to listen to, and specify the event options. If for some reason the default behavior of this package (prevent default) does not fit your needs, you can change it with for example:
onDown : (Mouse.Event -> msg) -> Html.Attribute msg
onDown =
{ stopPropagation = False, preventDefault = True }
|> Mouse.onWithOptions "mousedown"
eventDecoder : Json.Decode.Decoder Event
An Event
decoder for mouse events.
The decoder is provided so that you can extend Mouse.Event
with
specific properties you need. If for example you need the movementX/Y
properties and you can guaranty that users will not use safari,
you could do:
type alias EventWithMovement =
{ mouseEvent : Mouse.Event
, movement : ( Float, Float )
}
decodeWithMovement : Decoder EventWithMovement
decodeWithMovement =
Decode.map2 EventWithMovement
Mouse.eventDecoder
movementDecoder
movementDecoder : Decoder ( Float, Float )
movementDecoder =
Decode.map2 (\a b -> ( a, b ))
(Decode.field "movementX" Decode.float)
(Decode.field "movementY" Decode.float)
And use it like follows:
type Msg
= Movement ( Float, Float )
div
[ onMove (.movement >> Movement) ]
[ text "move here" ]
onMove : (EventWithMovement -> msg) -> Html.Attribute msg
onMove tag =
let
decoder =
decodeWithMovement
|> Decode.map tag
|> Decode.map options
options message =
{ message = message
, stopPropagation = False
, preventDefault = True
}
in
Html.Events.custom "mousemove" decoder