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