gioui.org: gioui.org/io/pointer Index | Files

package pointer

import "gioui.org/io/pointer"

Package pointer implements pointer events and operations. A pointer is either a mouse controlled cursor or a touch object such as a finger.

The InputOp operation is used to declare a handler ready for pointer events. Use an event.Queue to receive events.

Areas

The area operations are used for specifying the area where subsequent InputOp are active.

For example, to set up a rectangular hit area:

var ops op.Ops
var h *Handler = ...

r := image.Rectangle{...}
pointer.RectAreaOp{Rect: r}.Add(ops)
pointer.InputOp{Key: h}.Add(ops)

Note that areas compound: the effective area of multiple area operations is the intersection of the areas.

Matching events

StackOp operations and input handlers form an implicit tree. Each stack operation is a node, and each input handler is associated with the most recent node.

For example:

ops := new(op.Ops)
var stack op.StackOp
var h1, h2 *Handler

stack.Push(ops)
pointer.InputOp{Key: h1}.Add(Ops)
stack.Pop()

stack.Push(ops)
pointer.InputOp{Key: h2}.Add(ops)
stack.Pop()

implies a tree of two inner nodes, each with one pointer handler.

When determining which handlers match an Event, only handlers whose areas contain the event position are considered. The matching proceeds as follows.

First, the foremost matching handler is included. If the handler has pass-through enabled, this step is repeated.

Then, all matching handlers from the current node and all parent nodes are included.

In the example above, all events will go to h2 only even though both handlers have the same area (the entire screen).

Pass-through

The PassOp operations controls the pass-through setting. A handler's pass-through setting is recorded along with the InputOp.

Pass-through handlers are useful for overlay widgets such as a hidden side drawer. When the user touches the side, both the (transparent) drawer handle and the interface below should receive pointer events.

Disambiguation

When more than one handler matches a pointer event, the event queue follows a set of rules for distributing the event.

As long as the pointer has not received a Press event, all matching handlers receive all events.

When a pointer is pressed, the set of matching handlers is recorded. The set is not updated according to the pointer position and hit areas. Rather, handlers stay in the matching set until they no longer appear in a InputOp or when another handler in the set grabs the pointer.

A handler can exclude all other handler from its matching sets by setting the Grab flag in its InputOp. The Grab flag is sticky and stays in effect until the handler no longer appears in any matching sets.

The losing handlers are notified by a Cancel event.

For multiple grabbing handlers, the foremost handler wins.

Priorities

Handlers know their position in a matching set of a pointer through event priorities. The Shared priority is for matching sets with multiple handlers; the Grabbed priority indicate exclusive access.

Priorities are useful for deferred gesture matching.

Consider a scrollable list of clickable elements. When the user touches an element, it is unknown whether the gesture is a click on the element or a drag (scroll) of the list. While the click handler might light up the element in anticipation of a click, the scrolling handler does not scroll on finger movements with lower than Grabbed priority.

Should the user release the finger, the click handler registers a click.

However, if the finger moves beyond a threshold, the scrolling handler determines that the gesture is a drag and sets its Grab flag. The click handler receives a Cancel (removing the highlight) and further movements for the scroll handler has priority Grabbed, scrolling the list.

Index

Package Files

doc.go pointer.go

type Buttons Uses

type Buttons uint8

Buttons is a set of mouse buttons

const (
    ButtonLeft Buttons = 1 << iota
    ButtonRight
    ButtonMiddle
)

func (Buttons) Contain Uses

func (b Buttons) Contain(buttons Buttons) bool

Contain reports whether the set b contains all of the buttons.

func (Buttons) String Uses

func (b Buttons) String() string

type EllipseAreaOp Uses

type EllipseAreaOp struct {
    // Rect is the bounds for the ellipse. The current transform
    // is applied to the rectangle.
    Rect image.Rectangle
}

EllipseAreaOp updates the hit area to the intersection of the current hit area with an elliptical area.

func (EllipseAreaOp) Add Uses

func (op EllipseAreaOp) Add(ops *op.Ops)

type Event Uses

type Event struct {
    Type   Type
    Source Source
    // PointerID is the id for the pointer and can be used
    // to track a particular pointer from Press to
    // Release or Cancel.
    PointerID ID
    // Priority is the priority of the receiving handler
    // for this event.
    Priority Priority
    // Time is when the event was received. The
    // timestamp is relative to an undefined base.
    Time time.Duration
    // Buttons are the set of pressed mouse buttons for this event.
    Buttons Buttons
    // Hit is set when the event was within the registered
    // area for the handler. Hit can be false when a pointer
    // was pressed within the hit area, and then dragged
    // outside it.
    Hit bool
    // Position is the position of the event, relative to
    // the current transformation, as set by op.TransformOp.
    Position f32.Point
    // Scroll is the scroll amount, if any.
    Scroll f32.Point
}

Event is a pointer event.

func (Event) ImplementsEvent Uses

func (Event) ImplementsEvent()

type ID Uses

type ID uint16

type InputOp Uses

type InputOp struct {
    Key event.Key
    // Grab, if set, request that the handler get
    // Grabbed priority.
    Grab bool
}

InputOp declares an input handler ready for pointer events.

func (InputOp) Add Uses

func (h InputOp) Add(o *op.Ops)

type PassOp Uses

type PassOp struct {
    Pass bool
}

PassOp sets the pass-through mode.

func (PassOp) Add Uses

func (op PassOp) Add(o *op.Ops)

type Priority Uses

type Priority uint8

Priority of an Event.

const (
    // Shared priority is for handlers that
    // are part of a matching set larger than 1.
    Shared Priority = iota
    // Grabbed is used for matching sets of size 1.
    Grabbed
)

func (Priority) String Uses

func (p Priority) String() string

type RectAreaOp Uses

type RectAreaOp struct {
    // Rect defines the rectangle. The current transform
    // is applied to it.
    Rect image.Rectangle
}

RectAreaOp updates the hit area to the intersection of the current hit area with a rectangular area.

func (RectAreaOp) Add Uses

func (op RectAreaOp) Add(ops *op.Ops)

type Source Uses

type Source uint8

Source of an Event.

const (
    // Mouse generated event.
    Mouse Source = iota
    // Touch generated event.
    Touch
)

func (Source) String Uses

func (s Source) String() string

type Type Uses

type Type uint8

Type of an Event.

const (
    // A Cancel event is generated when the current gesture is
    // interrupted by other handlers or the system.
    Cancel Type = iota
    // Press of a pointer.
    Press
    // Release of a pointer.
    Release
    // Move of a pointer.
    Move
)

func (Type) String Uses

func (t Type) String() string

Package pointer imports 8 packages (graph) and is imported by 11 packages. Updated 2019-11-15. Refresh now. Tools for package owners.