doc.go raw

   1  // SPDX-License-Identifier: Unlicense OR MIT
   2  
   3  /*
   4  Package pointer implements pointer events and operations.
   5  A pointer is either a mouse controlled cursor or a touch
   6  object such as a finger.
   7  
   8  The InputOp operation is used to declare a handler ready for pointer
   9  events. Use an event.Queue to receive events.
  10  
  11  Types
  12  
  13  Only events that match a specified list of types are delivered to a handler.
  14  
  15  For example, to receive Press, Drag, and Release events (but not Move, Enter,
  16  Leave, or Scroll):
  17  
  18  	var ops op.Ops
  19  	var h *Handler = ...
  20  
  21  	pointer.InputOp{
  22  		Tag:   h,
  23  		Types: pointer.Press | pointer.Drag | pointer.Release,
  24  	}.Add(ops)
  25  
  26  Cancel events are always delivered.
  27  
  28  Areas
  29  
  30  The area operations are used for specifying the area where
  31  subsequent InputOp are active.
  32  
  33  For example, to set up a rectangular hit area:
  34  
  35  	r := image.Rectangle{...}
  36  	pointer.Rect(r).Add(ops)
  37  	pointer.InputOp{Tag: h}.Add(ops)
  38  
  39  Note that areas compound: the effective area of multiple area
  40  operations is the intersection of the areas.
  41  
  42  Matching events
  43  
  44  StackOp operations and input handlers form an implicit tree.
  45  Each stack operation is a node, and each input handler is associated
  46  with the most recent node.
  47  
  48  For example:
  49  
  50  	ops := new(op.Ops)
  51  	var stack op.StackOp
  52  	var h1, h2 *Handler
  53  
  54  	state := op.Save(ops)
  55  	pointer.InputOp{Tag: h1}.Add(Ops)
  56  	state.Load()
  57  
  58  	state = op.Save(ops)
  59  	pointer.InputOp{Tag: h2}.Add(ops)
  60  	state.Load()
  61  
  62  implies a tree of two inner nodes, each with one pointer handler.
  63  
  64  When determining which handlers match an Event, only handlers whose
  65  areas contain the event position are considered. The matching
  66  proceeds as follows.
  67  
  68  First, the foremost matching handler is included. If the handler
  69  has pass-through enabled, this step is repeated.
  70  
  71  Then, all matching handlers from the current node and all parent
  72  nodes are included.
  73  
  74  In the example above, all events will go to h2 only even though both
  75  handlers have the same area (the entire screen).
  76  
  77  Pass-through
  78  
  79  The PassOp operations controls the pass-through setting. A handler's
  80  pass-through setting is recorded along with the InputOp.
  81  
  82  Pass-through handlers are useful for overlay widgets such as a hidden
  83  side drawer. When the user touches the side, both the (transparent)
  84  drawer handle and the interface below should receive pointer events.
  85  
  86  Disambiguation
  87  
  88  When more than one handler matches a pointer event, the event queue
  89  follows a set of rules for distributing the event.
  90  
  91  As long as the pointer has not received a Press event, all
  92  matching handlers receive all events.
  93  
  94  When a pointer is pressed, the set of matching handlers is
  95  recorded. The set is not updated according to the pointer position
  96  and hit areas. Rather, handlers stay in the matching set until they
  97  no longer appear in a InputOp or when another handler in the set
  98  grabs the pointer.
  99  
 100  A handler can exclude all other handler from its matching sets
 101  by setting the Grab flag in its InputOp. The Grab flag is sticky
 102  and stays in effect until the handler no longer appears in any
 103  matching sets.
 104  
 105  The losing handlers are notified by a Cancel event.
 106  
 107  For multiple grabbing handlers, the foremost handler wins.
 108  
 109  Priorities
 110  
 111  Handlers know their position in a matching set of a pointer through
 112  event priorities. The Shared priority is for matching sets with
 113  multiple handlers; the Grabbed priority indicate exclusive access.
 114  
 115  Priorities are useful for deferred gesture matching.
 116  
 117  Consider a scrollable list of clickable elements. When the user touches an
 118  element, it is unknown whether the gesture is a click on the element
 119  or a drag (scroll) of the list. While the click handler might light up
 120  the element in anticipation of a click, the scrolling handler does not
 121  scroll on finger movements with lower than Grabbed priority.
 122  
 123  Should the user release the finger, the click handler registers a click.
 124  
 125  However, if the finger moves beyond a threshold, the scrolling handler
 126  determines that the gesture is a drag and sets its Grab flag. The
 127  click handler receives a Cancel (removing the highlight) and further
 128  movements for the scroll handler has priority Grabbed, scrolling the
 129  list.
 130  */
 131  package pointer
 132