mirror of
https://git.sr.ht/~eliasnaur/gio
synced 2026-07-01 15:45:38 +00:00
Elias Naur
936c266b03
The op.Save and Load methods exist to support the need for
transformation, clip, pointer area state to behave as stacks. For
example, layout needs to apply an offset to its children but not
subsequent operations.
Before this change, op.Save and Load were used to save and restore the
state:
ops := new(op.Ops)
// Save state.
state := op.Save(ops)
// Apply offset.
op.Offset(...).Add(ops)
// Draw with offset applied.
draw(ops)
// Restore state.
state.Load()
A drawback with the op.Save mechanism is that there is no direct
connection between the state change and the saving and loading of state.
This causes confusion as to when a Save/Load is needed and who is
responsible for performing them, which leads to subtle bugs and over-use
of Save/Loads.
This change gets rid of the general state stack and replaces it with
per-state stacks. There is now a stack for transformation, clip, pointer
areas, and they can only be restored by the code pushing state to them.
The example above now becomes:
ops := new(op.Ops)
// Push offset to the transformation stack.
stack := op.Offset(...).Push(ops)
// Draw with offset applied.
draw(ops)
// Restore state.
stack.Pop()
For convenience, transformation also be Add'ed if the stack operation is
not required.
Simple state such as the current material no longer has a way to be
restored; it is assumed the client of a PaintOp adds their desired
material operation before it.
API change: replace op.Save/Load with explicit Push/Pop scopes for
op.TransformOps, pointer.AreaOps, clip.Ops.
To ease porting, this change retains a version of op.Save/Load that
saves and restores the transformation and clip stacks. It also retains
an Add method for clip.Op.
Signed-off-by: Elias Naur <mail@eliasnaur.com>
133 lines
4.2 KiB
Go
133 lines
4.2 KiB
Go
// SPDX-License-Identifier: Unlicense OR MIT
|
|
|
|
/*
|
|
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.
|
|
|
|
Areas
|
|
|
|
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.Rect(r).Add(ops)
|
|
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.Pop()
|
|
|
|
area := pointer.Rect(...).Push(ops)
|
|
pointer.InputOp{Tag: h2}.Add(ops)
|
|
area.Pop()
|
|
|
|
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).
|
|
|
|
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.
|
|
*/
|
|
package pointer
|