pointer

Documentation

Overview

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.

Types

Only events that match a specified list of types are delivered to a handler.

For example, to receive Press, Drag, and Release events (but not Move, Enter, Leave, or Scroll):

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

pointer.InputOp{
	Tag:   h,
	Types: pointer.Press | pointer.Drag | pointer.Release,
}.Add(ops)

Cancel events are always delivered.

Hit areas

Clip operations from package op/clip are used for specifying hit areas where subsequent InputOps are active.

For example, to set up a handler with a rectangular hit area:

r := image.Rectangle{...}
area := clip.Rect(r).Push(ops)
pointer.InputOp{Tag: h}.Add(ops)
area.Pop()

Note that hit areas behave similar to painting: the effective area of a stack of multiple area operations is the intersection of the areas.

BUG: Clip operations other than clip.Rect and clip.Ellipse are approximated with their bounding boxes.

Matching events

Areas form an implicit tree, with input handlers as leaves. The children of an area is every area and handler added between its Push and corresponding Pop.

For example:

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

area := clip.Rect(...).Push(ops)
pointer.InputOp{Tag: h1}.Add(Ops)
area.Pop()

area := clip.Rect(...).Push(ops)
pointer.InputOp{Tag: h2}.Add(ops)
area.Pop()

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

The matching proceeds as follows.

First, the foremost area that contains the event is found. Only areas whose parent areas all contain the event is considered.

Then, every handler attached to the area is matched with the event.

If all attached handlers are marked pass-through or if no handlers are attached, the matching repeats with the next foremost (sibling) area. Otherwise the matching repeats with the parent area.

In the example above, all events will go to h2 because it and h1 are siblings and none are pass-through.

Pass-through

The PassOp operations controls the pass-through setting. All handlers added inside one or more PassOp scopes are marked pass-through.

Pass-through is useful for overlay widgets. Consider a hidden side drawer: when the user touches the side, both the (transparent) drawer handle and the interface below should receive pointer events. This effect is achieved by marking the drawer handle pass-through.

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

• type Buttons
  • func (b Buttons) Contain(buttons Buttons) bool
  • func (b Buttons) String() string
• type Cursor
  • func (op Cursor) Add(o *op.Ops)
  • func (c Cursor) String() string
• type Event
  • func (Event) ImplementsEvent()
• type ID
• type InputOp
  • func (op InputOp) Add(o *op.Ops)
• type PassOp
  • func (p PassOp) Push(o *op.Ops) PassStack
• type PassStack
  • func (p PassStack) Pop()
• type Priority
  • func (p Priority) String() string
• type Source
  • func (s Source) String() string
• type Type
  • func (t Type) String() string

Types

type Buttons

type Buttons uint8

Buttons is a set of mouse buttons

const (
	// ButtonPrimary is the primary button, usually the left button for a
	// right-handed user.
	ButtonPrimary Buttons = 1 << iota
	// ButtonSecondary is the secondary button, usually the right button for a
	// right-handed user.
	ButtonSecondary
	// ButtonTertiary is the tertiary button, usually the middle button.
	ButtonTertiary
)

func (Buttons) Contain

func (b Buttons) Contain(buttons Buttons) bool

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

func (Buttons) String

func (b Buttons) String() string

type Cursor

type Cursor byte

Cursor denotes a pre-defined cursor shape. Its Add method adds an operation that sets the cursor shape for the current clip area.

const (
	// CursorDefault is the default cursor.
	CursorDefault Cursor = iota
	// CursorNone hides the cursor. To show it again, use any other cursor.
	CursorNone
	// CursorText is for selecting and inserting text.
	CursorText
	// CursorVerticalText is for selecting and inserting vertical text.
	CursorVerticalText
	// CursorPointer is for a link.
	// Usually displayed as a pointing hand.
	CursorPointer
	// CursorCrosshair is for a precise location.
	CursorCrosshair
	// CursorAllScroll is for indicating scrolling in all directions.
	// Usually displayed as arrows to all four directions.
	CursorAllScroll
	// CursorColResize is for vertical resize.
	// Usually displayed as a vertical bar with arrows pointing east and west.
	CursorColResize
	// CursorRowResize is for horizontal resize.
	// Usually displayed as a horizontal bar with arrows pointing north and south.
	CursorRowResize
	// CursorGrab is for content that can be grabbed (dragged to be moved).
	// Usually displayed as an open hand.
	CursorGrab
	// CursorGrabbing is for content that is being grabbed (dragged to be moved).
	// Usually displayed as a closed hand.
	CursorGrabbing
	// CursorNotAllowed is shown when the request action cannot be carried out.
	// Usually displayed as a circle with a line through.
	CursorNotAllowed
	// CursorWait is shown when the program is busy and user cannot interact.
	// Usually displayed as a hourglass or the system equivalent.
	CursorWait
	// CursorProgress is shown when the program is busy, but the user can still interact.
	// Usually displayed as a default cursor with a hourglass.
	CursorProgress
	// CursorNorthWestResize is for top-left corner resizing.
	// Usually displayed as an arrow towards north-west.
	CursorNorthWestResize
	// CursorNorthEastResize is for top-right corner resizing.
	// Usually displayed as an arrow towards north-east.
	CursorNorthEastResize
	// CursorSouthWestResize is for bottom-left corner resizing.
	// Usually displayed as an arrow towards south-west.
	CursorSouthWestResize
	// CursorSouthEastResize is for bottom-right corner resizing.
	// Usually displayed as an arrow towards south-east.
	CursorSouthEastResize
	// CursorNorthSouth is for top-bottom resizing.
	// Usually displayed as a bi-directional arrow towards north-south.
	CursorNorthSouthResize
	// CursorEastWestResize is for left-right resizing.
	// Usually displayed as a bi-directional arrow towards east-west.
	CursorEastWestResize
	// CursorWestResize is for left resizing.
	// Usually displayed as an arrow towards west.
	CursorWestResize
	// CursorEastResize is for right resizing.
	// Usually displayed as an arrow towards east.
	CursorEastResize
	// CursorNorthResize is for top resizing.
	// Usually displayed as an arrow towards north.
	CursorNorthResize
	// CursorSouthResize is for bottom resizing.
	// Usually displayed as an arrow towards south.
	CursorSouthResize
	// CursorNorthEastSouthWestResize is for top-right to bottom-left diagonal resizing.
	// Usually displayed as a double ended arrow on the corresponding diagonal.
	CursorNorthEastSouthWestResize
	// CursorNorthWestSouthEastResize is for top-left to bottom-right diagonal resizing.
	// Usually displayed as a double ended arrow on the corresponding diagonal.
	CursorNorthWestSouthEastResize
)

The cursors correspond to CSS pointer naming.

func (Cursor) Add

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

func (Cursor) String

func (c Cursor) String() string

type Event

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
	// 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
	// Modifiers is the set of active modifiers when
	// the mouse button was pressed.
	Modifiers key.Modifiers
}

Event is a pointer event.

func (Event) ImplementsEvent

func (Event) ImplementsEvent()

type ID

type ID uint16

type InputOp

type InputOp struct {
	Tag event.Tag
	// Grab, if set, request that the handler get
	// Grabbed priority.
	Grab bool
	// Types is a bitwise-or of event types to receive.
	Types Type
	// ScrollBounds describe the maximum scrollable distances in both
	// axes. Specifically, any Event e delivered to Tag will satisfy
	//
	// ScrollBounds.Min.X <= e.Scroll.X <= ScrollBounds.Max.X (horizontal axis)
	// ScrollBounds.Min.Y <= e.Scroll.Y <= ScrollBounds.Max.Y (vertical axis)
	ScrollBounds image.Rectangle
}

InputOp declares an input handler ready for pointer events.

func (InputOp) Add

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

Add panics if the scroll range does not contain zero.

type PassOp

type PassOp struct {
}

PassOp sets the pass-through mode. InputOps added while the pass-through mode is set don't block events to siblings.

func (PassOp) Push

func (p PassOp) Push(o *op.Ops) PassStack

Push the current pass mode to the pass stack and set the pass mode.

type PassStack

type PassStack struct {
	// contains filtered or unexported fields
}

PassStack represents a PassOp on the pass stack.

func (PassStack) Pop

func (p PassStack) Pop()

type Priority

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
	// Foremost priority is like Shared, but the
	// handler is the foremost of the matching set.
	Foremost
	// Grabbed is used for matching sets of size 1.
	Grabbed
)

func (Priority) String

func (p Priority) String() string

type Source

type Source uint8

Source of an Event.

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

func (Source) String

func (s Source) String() string

type Type

type Type uint

Type of an Event.

const (
	// A Cancel event is generated when the current gesture is
	// interrupted by other handlers or the system.
	Cancel Type = (1 << iota) >> 1
	// Press of a pointer.
	Press
	// Release of a pointer.
	Release
	// Move of a pointer.
	Move
	// Drag of a pointer.
	Drag
	// Pointer enters an area watching for pointer input
	Enter
	// Pointer leaves an area watching for pointer input
	Leave
	// Scroll of a pointer.
	Scroll
)

func (Type) String

func (t Type) String() string