github.com/Seikaijyu/gio@v0.0.1/io/pointer/doc.go (about)

     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  # Kinds
    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  		Kinds: pointer.Press | pointer.Drag | pointer.Release,
    24  	}.Add(ops)
    25  
    26  Cancel events are always delivered.
    27  
    28  # Hit areas
    29  
    30  Clip operations from package op/clip are used for specifying
    31  hit areas where subsequent InputOps are active.
    32  
    33  For example, to set up a handler with a rectangular hit area:
    34  
    35  	r := image.Rectangle{...}
    36  	area := clip.Rect(r).Push(ops)
    37  	pointer.InputOp{Tag: h}.Add(ops)
    38  	area.Pop()
    39  
    40  Note that hit areas behave similar to painting: the effective area of a stack
    41  of multiple area operations is the intersection of the areas.
    42  
    43  BUG: Clip operations other than clip.Rect and clip.Ellipse are approximated
    44  with their bounding boxes.
    45  
    46  # Matching events
    47  
    48  Areas form an implicit tree, with input handlers as leaves. The children of
    49  an area is every area and handler added between its Push and corresponding Pop.
    50  
    51  For example:
    52  
    53  	ops := new(op.Ops)
    54  	var h1, h2 *Handler
    55  
    56  	area := clip.Rect(...).Push(ops)
    57  	pointer.InputOp{Tag: h1}.Add(Ops)
    58  	area.Pop()
    59  
    60  	area := clip.Rect(...).Push(ops)
    61  	pointer.InputOp{Tag: h2}.Add(ops)
    62  	area.Pop()
    63  
    64  implies a tree of two inner nodes, each with one pointer handler attached.
    65  
    66  The matching proceeds as follows.
    67  
    68  First, the foremost area that contains the event is found. Only areas whose
    69  parent areas all contain the event is considered.
    70  
    71  Then, every handler attached to the area is matched with the event.
    72  
    73  If all attached handlers are marked pass-through or if no handlers are
    74  attached, the matching repeats with the next foremost (sibling) area. Otherwise
    75  the matching repeats with the parent area.
    76  
    77  In the example above, all events will go to h2 because it and h1 are siblings
    78  and none are pass-through.
    79  
    80  # Pass-through
    81  
    82  The PassOp operations controls the pass-through setting. All handlers added
    83  inside one or more PassOp scopes are marked pass-through.
    84  
    85  Pass-through is useful for overlay widgets. Consider a hidden side drawer: when
    86  the user touches the side, both the (transparent) drawer handle and the
    87  interface below should receive pointer events. This effect is achieved by
    88  marking the drawer handle pass-through.
    89  
    90  # Disambiguation
    91  
    92  When more than one handler matches a pointer event, the event queue
    93  follows a set of rules for distributing the event.
    94  
    95  As long as the pointer has not received a Press event, all
    96  matching handlers receive all events.
    97  
    98  When a pointer is pressed, the set of matching handlers is
    99  recorded. The set is not updated according to the pointer position
   100  and hit areas. Rather, handlers stay in the matching set until they
   101  no longer appear in a InputOp or when another handler in the set
   102  grabs the pointer.
   103  
   104  A handler can exclude all other handler from its matching sets
   105  by setting the Grab flag in its InputOp. The Grab flag is sticky
   106  and stays in effect until the handler no longer appears in any
   107  matching sets.
   108  
   109  The losing handlers are notified by a Cancel event.
   110  
   111  For multiple grabbing handlers, the foremost handler wins.
   112  
   113  # Priorities
   114  
   115  Handlers know their position in a matching set of a pointer through
   116  event priorities. The Shared priority is for matching sets with
   117  multiple handlers; the Grabbed priority indicate exclusive access.
   118  
   119  Priorities are useful for deferred gesture matching.
   120  
   121  Consider a scrollable list of clickable elements. When the user touches an
   122  element, it is unknown whether the gesture is a click on the element
   123  or a drag (scroll) of the list. While the click handler might light up
   124  the element in anticipation of a click, the scrolling handler does not
   125  scroll on finger movements with lower than Grabbed priority.
   126  
   127  Should the user release the finger, the click handler registers a click.
   128  
   129  However, if the finger moves beyond a threshold, the scrolling handler
   130  determines that the gesture is a drag and sets its Grab flag. The
   131  click handler receives a Cancel (removing the highlight) and further
   132  movements for the scroll handler has priority Grabbed, scrolling the
   133  list.
   134  */
   135  package pointer