OLD | NEW |
1 Pointer Events | 1 Pointer Events |
2 ============== | 2 ============== |
3 | 3 |
4 Scope | 4 Scope |
5 ----- | 5 ----- |
6 | 6 |
7 The following input devices are supported by sky: | 7 The following input devices are supported by sky: |
8 - fingers on multitouch screens | 8 - fingers on multitouch screens |
9 - mice, including mouse wheels | 9 - mice, including mouse wheels |
10 - styluses on screens | 10 - styluses on screens |
(...skipping 42 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
53 Pointers | 53 Pointers |
54 -------- | 54 -------- |
55 | 55 |
56 Each touch or pointer is tracked individually. | 56 Each touch or pointer is tracked individually. |
57 | 57 |
58 New touches and pointers can appear and disappear over time. | 58 New touches and pointers can appear and disappear over time. |
59 | 59 |
60 Each pointer has a list of current targets. | 60 Each pointer has a list of current targets. |
61 | 61 |
62 When a new one enters the system, a non-bubbling ``PointerAddedEvent`` | 62 When a new one enters the system, a non-bubbling ``PointerAddedEvent`` |
63 event is fired at the application's document, and the pointer's | 63 event is fired at the application's element tree's root node, and the |
64 current targets list is initialised to just that Document object. | 64 pointer's current targets list is initialised to just that Root |
| 65 object. |
65 | 66 |
66 When it is removed, a non-bubbling ``PointerRemovedEvent`` event is | 67 When it is removed, a non-bubbling ``PointerRemovedEvent`` event is |
67 fired at the application's document and at any other objects in the | 68 fired at the application's element tree's root node and at any other |
68 pointer's current targets list. Currently, at the time of a | 69 objects in the pointer's current targets list. Currently, at the time |
69 ``PointerRemoved``, the list will always consist of only the document. | 70 of a ``PointerRemoved``, the list will always consist of only the |
| 71 application's element tree's root node. |
70 | 72 |
71 A pointer can be "up" or "down". Initially all pointers are "up". | 73 A pointer can be "up" or "down". Initially all pointers are "up". |
72 | 74 |
73 A pointer switches from "up" to "down" when it is a touch or stylus | 75 A pointer switches from "up" to "down" when it is a touch or stylus |
74 that is in contact with the display surface, or when it is a mouse | 76 that is in contact with the display surface, or when it is a mouse |
75 that is being clicked, and from "down" back to "up" when this ends. | 77 that is being clicked, and from "down" back to "up" when this ends. |
76 (Note that clicking a button on a stylus doesn't change it from up to | 78 (Note that clicking a button on a stylus doesn't change it from up to |
77 down. A stylus can have a button pressed while "up".) In the case of a | 79 down. A stylus can have a button pressed while "up".) In the case of a |
78 mouse with multiple buttons, the pointer switches back to "up" only | 80 mouse with multiple buttons, the pointer switches back to "up" only |
79 when all the buttons have been released. | 81 when all the buttons have been released. |
80 | 82 |
81 When a pointer switches from "up" to "down", the following algorithm | 83 When a pointer switches from "up" to "down", the following algorithm |
82 is run: | 84 is run: |
83 | 85 |
84 1. Hit test the position of the pointer, let 'node' be the result. | 86 1. Hit test the position of the pointer, let 'node' be the result. |
85 2. Fire a bubbling ``PointerDownEvent`` event at the layoutManager | 87 2. Fire a bubbling ``PointerDownEvent`` event at the layoutManager |
86 for 'node', with an empty array as the default return value. Let | 88 for 'node', with an empty array as the default return value. Let |
87 'result1' be the returned value. | 89 'result1' be the returned value. |
88 3. If result1 is not an array of EventTarget objects, set it to the | 90 3. If result1 is not an array of EventTarget objects, set it to the |
89 empty array and (if this is debug mode) report the issue. | 91 empty array and (if this is debug mode) report the issue. |
90 4. Fire a bubbling ``PointerDownEvent`` event at the Element for | 92 4. Fire a bubbling ``PointerDownEvent`` event at the Element for |
91 'node', with an empty array as the default return value. Let | 93 'node', with an empty array as the default return value. Let |
92 'result2' be the returned value. | 94 'result2' be the returned value. |
93 5. If result2 is not an array of EventTarget objects, set it to the | 95 5. If result2 is not an array of EventTarget objects, set it to the |
94 empty array and (if this is debug mode) report the issue. | 96 empty array and (if this is debug mode) report the issue. |
95 6. Let result be the concatenation of result1's contents, result2's | 97 6. Let result be the concatenation of result1's contents, result2's |
96 contents, and the application document. | 98 contents, and the application's element tree's root node. |
97 7. Let 'result' be this pointer's current targets. | 99 7. Let 'result' be this pointer's current targets. |
98 | 100 |
99 When an object is one of the current targets of a pointer and no other | 101 When an object is one of the current targets of a pointer and no other |
100 pointers have that object as a current target so far, and either there | 102 pointers have that object as a current target so far, and either there |
101 are no buttons (touch, stylus) or only the primary button is active | 103 are no buttons (touch, stylus) or only the primary button is active |
102 (mouse) and this is not an inverted stylus, then that pointer is | 104 (mouse) and this is not an inverted stylus, then that pointer is |
103 considered the "primary" pointer for that object. The pointer remains | 105 considered the "primary" pointer for that object. The pointer remains |
104 the primary pointer for that object until the corresponding | 106 the primary pointer for that object until the corresponding |
105 ``PointerUpEvent`` event (even if the buttons change). | 107 ``PointerUpEvent`` event (even if the buttons change). |
106 | 108 |
107 When a pointer moves, a non-bubbling ``PointerMoveEvent`` event is | 109 When a pointer moves, a non-bubbling ``PointerMoveEvent`` event is |
108 fired at each of the pointer's current targets in turn (maintaining | 110 fired at each of the pointer's current targets in turn (maintaining |
109 the order they had in the ``PointerDownEvent`` event, if there's more | 111 the order they had in the ``PointerDownEvent`` event, if there's more |
110 than one). If the return value of a ``PointerMovedEvent`` event is | 112 than one). If the return value of a ``PointerMovedEvent`` event is |
111 'cancel', and the pointer is currently down, then the pointer is | 113 'cancel', and the pointer is currently down, then the pointer is |
112 canceled (see below). | 114 canceled (see below). |
113 | 115 |
114 When a pointer's button state changes but this doesn't impact whether | 116 When a pointer's button state changes but this doesn't impact whether |
115 it is "up" or "down", e.g. when a mouse with a button down gets a | 117 it is "up" or "down", e.g. when a mouse with a button down gets a |
116 second button down, or when a stylus' buttons change state, but the | 118 second button down, or when a stylus' buttons change state, but the |
117 pointer doesn't simultaneously move, then a ``PointerMovedEvent`` | 119 pointer doesn't simultaneously move, then a ``PointerMovedEvent`` |
118 event is fired anyway, as described above, but with dx=dy=0. | 120 event is fired anyway, as described above, but with dx=dy=0. |
119 | 121 |
120 When a pointer switches from "down" to "up", a non-bubbling | 122 When a pointer switches from "down" to "up", a non-bubbling |
121 ``PointerUpEvent`` event is fired at each of the pointer's current | 123 ``PointerUpEvent`` event is fired at each of the pointer's current |
122 targets in turn (maintaining the order they had in the | 124 targets in turn (maintaining the order they had in the |
123 ``PointerDownEvent`` event, if there's more than one), and then the | 125 ``PointerDownEvent`` event, if there's more than one), and then the |
124 pointer's current target list is emptied except for the application's | 126 pointer's current target list is emptied except for the application's |
125 document. The buttons exposed on the ``PointerUpEvent`` event are | 127 element tree's root node. The buttons exposed on the |
126 those that were down immediately prior to the buttons being released. | 128 ``PointerUpEvent`` event are those that were down immediately prior to |
| 129 the buttons being released. |
127 | 130 |
128 At the time of a ``PointerUpEvent`` event, for each object that is a | 131 At the time of a ``PointerUpEvent`` event, for each object that is a |
129 current target of the pointer, and for which the pointer is considered | 132 current target of the pointer, and for which the pointer is considered |
130 the "primary" pointer for that object, if there is another pointer | 133 the "primary" pointer for that object, if there is another pointer |
131 that is already down, which is of the same kind, which also has that | 134 that is already down, which is of the same kind, which also has that |
132 object as a current target, and that has either no buttons or only its | 135 object as a current target, and that has either no buttons or only its |
133 primary button active, then that pointer becomes the new "primary" | 136 primary button active, then that pointer becomes the new "primary" |
134 pointer for that object before the ``PointerUpEvent`` event is sent. | 137 pointer for that object before the ``PointerUpEvent`` event is sent. |
135 Otherwise, the "primary" pointer stops being "primary" just _after_ | 138 Otherwise, the "primary" pointer stops being "primary" just _after_ |
136 the ``PointerUpEvent`` event. (This matters for whether the 'primary' | 139 the ``PointerUpEvent`` event. (This matters for whether the 'primary' |
137 field is set.) | 140 field is set.) |
138 | 141 |
139 When a pointer is canceled, if it is "down", pretend that the pointer | 142 When a pointer is canceled, if it is "down", pretend that the pointer |
140 moved to "up", sending ``PointerUpEvent`` as described above, and | 143 moved to "up", sending ``PointerUpEvent`` as described above, and |
141 entirely empty its current targets list. AFter the pointer actually | 144 entirely empty its current targets list. AFter the pointer actually |
142 switches from "down" to "up", replace the current targets list with an | 145 switches from "down" to "up", replace the current targets list with an |
143 object that only contains the application's document. | 146 object that only contains the application's element tree's root node. |
144 | 147 |
145 Nothing special happens when a pointer's current target moves in the | 148 Nothing special happens when a pointer's current target moves in the |
146 DOM. | 149 DOM. |
147 | 150 |
148 The x and y position of an -up or -down event always match those of | 151 The x and y position of an -up or -down event always match those of |
149 the previous -moved or -added event, so their dx and dy are always 0. | 152 the previous -moved or -added event, so their dx and dy are always 0. |
150 | 153 |
151 Positions are floating point numbers; they can have subpixel values. | 154 Positions are floating point numbers; they can have subpixel values. |
152 | 155 |
153 For each pointer, only a single ``PointerAddedEvent`` or | 156 For each pointer, only a single ``PointerAddedEvent`` or |
(...skipping 276 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
430 class PointerMovedEvent extends PointerEvent<Null> { | 433 class PointerMovedEvent extends PointerEvent<Null> { |
431 PointerMovedEvent = PointerEvent; | 434 PointerMovedEvent = PointerEvent; |
432 bool get bubbles => false; | 435 bool get bubbles => false; |
433 } | 436 } |
434 ``` | 437 ``` |
435 | 438 |
436 Wheel events | 439 Wheel events |
437 ------------ | 440 ------------ |
438 | 441 |
439 When a wheel input device is turned, a ``WheelEvent`` event that | 442 When a wheel input device is turned, a ``WheelEvent`` event that |
440 doesn't bubble is fired at the application's document, with the | 443 doesn't bubble is fired at the application's element tree's root node, |
441 following fields: | 444 with the following fields: |
442 | 445 |
443 wheel: an integer assigned to this wheel by the system. The | 446 wheel: an integer assigned to this wheel by the system. The |
444 same wheel on the same system must always be given | 447 same wheel on the same system must always be given |
445 the same ID. The primary wheel (e.g. the vertical | 448 the same ID. The primary wheel (e.g. the vertical |
446 wheel on a mouse) must be given ID 1. | 449 wheel on a mouse) must be given ID 1. |
447 | 450 |
448 delta: an floating point number representing the fraction of | 451 delta: an floating point number representing the fraction of |
449 the wheel that was turned, with positive numbers | 452 the wheel that was turned, with positive numbers |
450 representing a downward movement on vertical wheels, | 453 representing a downward movement on vertical wheels, |
451 rightward movement on horizontal wheels, and a | 454 rightward movement on horizontal wheels, and a |
(...skipping 25 matching lines...) Expand all Loading... |
477 | 480 |
478 final int wheel; | 481 final int wheel; |
479 final @nonnull double delta; // revolutions (or fractions thereof) | 482 final @nonnull double delta; // revolutions (or fractions thereof) |
480 final int pointer; | 483 final int pointer; |
481 final double x; // logical pixels | 484 final double x; // logical pixels |
482 final double y; // logical pixels | 485 final double y; // logical pixels |
483 | 486 |
484 bool get bubbles => false; | 487 bool get bubbles => false; |
485 } | 488 } |
486 ``` | 489 ``` |
OLD | NEW |