the-sett / elm-pointer / Pointer

Pointer is a high-level pointer API that unifies pointer events over all pointer types where possible. Pointer types can include mouse, touch, stylus and so on.

This Pointer module always uses elm-geometry primitives to describe pointer events with Pixels for units.

Configurable parameters.


type alias Config =
{ dragThreshold : Basics.Int
, holdTimeMillis : Basics.Int
, mouseWheelZoomStep : Basics.Float 
}

Some configurable parameters of the Pointer.

dragThreshold - how many pixels the pointer must move when engaged to be considered a drag.
holdTimeMillis - how many milliseconds the pointer must hold down to be considered a hold.
mouseWheelZoomStep - the zoom factor to assign to each mouse wheel step.

defaultConfig : Config

A default configuration.

The TEA structure for hooking up the internal state into your application.


type Model a msg coordinates

The internal model of the pointer.


type Msg a coordinates

Internal pointer events.

init : Maybe Config -> (Msg a coordinates -> msg) -> Model a msg coordinates

Creates a new pointer model with no handlers set on it yet.

update : Msg a coordinates -> Model a msg coordinates -> ( Model a msg coordinates, Platform.Cmd.Cmd msg )

The pointer update function, which should be applied to all pointer Msgs.

Pointer ports, needed for listening at the overall HTML Document level.


type alias PointerPorts msg =
{ onPointerDown : (Json.Decode.Value -> msg) -> Platform.Sub.Sub msg
, onPointerUp : (Json.Decode.Value -> msg) -> Platform.Sub.Sub msg
, onPointerMove : (Json.Decode.Value -> msg) -> Platform.Sub.Sub msg
, onPointerCancel : (Json.Decode.Value -> msg) -> Platform.Sub.Sub msg 
}

Defines the ports which this pointer module needs to listen to HTML pointer events on the whole document.

Event handlers for adding to the view, for listening to pointer events below the Document level.


type EventKind
    = UpEvent
    | DownEvent
    | ClickEvent
    | MoveEvent
    | ScrollWheelEvent

Provides a classification of the type of event a pointer is performing.

on : Model a msg coordinates -> (EventKind -> Json.Decode.Decoder a) -> List (Html.Attribute msg)

Attaches a pointer model to a TEA view as a list of HTML event handler attributes.

subscriptions : PointerPorts msg -> Model a msg coordinates -> (EventKind -> Json.Decode.Decoder a) -> Platform.Sub.Sub msg

Defines the subscriptions a pointer needs to listen to HTML pointer events on whole document.

These events are not provided by elm/browser so must be accessed through ports. Consult the README for instructions on how to set up the ports.

Pointer event records.


type alias DragArgs coordinates =
{ startPos : Point2d Pixels coordinates
, pos : Point2d Pixels coordinates
, isFirstEvent : Basics.Bool 
}

When a pointer is dragged it reports these values.


type alias PointArgs coordinates =
{ button : Basics.Int
, pos : Point2d Pixels coordinates 
}

When a pointer is referencing a point on the screen it reports these args.


type alias ScaleArgs coordinates =
{ pos : Point2d Pixels coordinates
, scale : Basics.Float 
}

When a pointer performs a scaling operation it reports these values.

A DSL for defining user gesture handling.


type Handlers a msg coordinates

A set of Handlers provides functions that turn pointer events into TEA events.

apply : Handlers a msg coordinates -> Model a msg coordinates -> Model a msg coordinates

Applies a set of handlers to the pointer model. The resulting pointer model will generate TEA events through the handlers.

empty : Handlers a msg coordinates

A default set of empty handlers that ignore all pointer events.

onClick : Basics.Int -> { h | click : PointArgs coordinates -> a -> msg } -> Handlers a msg coordinates -> Handlers a msg coordinates

Adds a click handler.

onDoubleClick : Basics.Int -> { h | doubleClick : PointArgs coordinates -> a -> msg } -> Handlers a msg coordinates -> Handlers a msg coordinates

Adds a double click handler.

onDrag : Basics.Int -> { h | drag : DragArgs coordinates -> a -> a -> msg, dragEnd : DragArgs coordinates -> a -> a -> msg } -> Handlers a msg coordinates -> Handlers a msg coordinates

Adds a drag handler.

onDragStart : Basics.Int -> { h | dragStart : DragArgs coordinates -> a -> msg } -> Handlers a msg coordinates -> Handlers a msg coordinates

Adds a drag start handler.

onWheel : { h | wheel : ScaleArgs coordinates -> a -> msg } -> Handlers a msg coordinates -> Handlers a msg coordinates

Adds a mouse wheel handler.

onPinch : { h | pinch : ScaleArgs coordinates -> a -> msg } -> Handlers a msg coordinates -> Handlers a msg coordinates

Adds a touch zoom pinch handler.

onMove : { h | move : Point2d Pixels coordinates -> a -> msg } -> Handlers a msg coordinates -> Handlers a msg coordinates

Adds a move handler.

onPointerUp : Basics.Int -> { h | pointerUp : PointArgs coordinates -> a -> msg } -> Handlers a msg coordinates -> Handlers a msg coordinates

Adds a pointer up handler.