Version: v0.0.0-...-e5d8a4b Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Oct 18, 2021 License: MIT, Unlicense Imports: 10 Imported by: 70



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.


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 = ...

	Tag:   h,
	Types: pointer.Press | pointer.Drag | pointer.Release,

Cancel events are always delivered.


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

For example, to set up a rectangular hit area:

r := image.Rectangle{...}
pointer.InputOp{Tag: h}.Add(ops)

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

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 := pointer.Rect(...).Push(ops)
pointer.InputOp{Tag: h1}.Add(Ops)

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

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

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 area that contains the event is found. If no such area exists, matching stops.

Then, every handler attached to the area or an area in the area stack is matched with the event.

Third, If the area or any area in the area stack has pass-through enabled, the matching repeats with the next foremost area.

In the example above, all events will go to h2 only even though both handlers have the same area (the implicit area that fills the window).


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.


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.


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.



This section is empty.


This section is empty.


This section is empty.


type AreaOp

type AreaOp struct {
	// contains filtered or unexported fields

AreaOp pushes the current hit area to the stack and updates it to the intersection of the current hit area and the transformed area.

func Ellipse

func Ellipse(size image.Rectangle) AreaOp

Ellipse constructs an ellipsoid hit area.

func Rect

func Rect(size image.Rectangle) AreaOp

Rect constructs a rectangular hit area.

func (AreaOp) Push

func (a AreaOp) Push(o *op.Ops) AreaStack

Push the current area to the stack and intersects the current area with the area represented by o.

type AreaStack

type AreaStack struct {
	// contains filtered or unexported fields

AreaStack represents an AreaOp on the stack of areas.

func (AreaStack) Pop

func (o AreaStack) Pop()

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.
	// ButtonTertiary is the tertiary button, usually the middle button.

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 CursorName

type CursorName string

CursorName is the name of a cursor.

const (
	// CursorDefault is the default cursor.
	CursorDefault CursorName = ""
	// CursorText is the cursor for text.
	CursorText CursorName = "text"
	// CursorPointer is the cursor for a link.
	CursorPointer CursorName = "pointer"
	// CursorCrossHair is the cursor for precise location.
	CursorCrossHair CursorName = "crosshair"
	// CursorColResize is the cursor for vertical resize.
	CursorColResize CursorName = "col-resize"
	// CursorRowResize is the cursor for horizontal resize.
	CursorRowResize CursorName = "row-resize"
	// CursorGrab is the cursor for moving object in any direction.
	CursorGrab CursorName = "grab"
	// CursorNone hides the cursor. To show it again, use any other cursor.
	CursorNone CursorName = "none"

func (CursorName) String

func (c CursorName) String() string

type CursorNameOp

type CursorNameOp struct {
	Name CursorName

CursorNameOp sets the cursor for the current area.

func (CursorNameOp) Add

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

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. AreaOps 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.
	// Grabbed is used for matching sets of size 1.

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.

func (Source) String

func (s Source) String() string

type Type

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 = (1 << iota) >> 1
	// Press of a pointer.
	// Release of a pointer.
	// Move of a pointer.
	// Drag of a pointer.
	// Pointer enters an area watching for pointer input
	// Pointer leaves an area watching for pointer input
	// Scroll of a pointer.

func (Type) String

func (t Type) String() string

Source Files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL