dom/interfaces/events/nsIDOMSimpleGestureEvent.idl@7e26c7da4463 (annotated)
dom/interfaces/events/nsIDOMSimpleGestureEvent.idl
Wed, 31 Dec 2014 06:55:50 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:55:50 +0100
- changeset 2
- 7e26c7da4463
- permissions
- -rw-r--r--
Added tag UPSTREAM_283F7C6 for changeset ca08bd8f51b2
| michael@0 | 1 | /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ |
| michael@0 | 2 | /* This Source Code Form is subject to the terms of the Mozilla Public |
| michael@0 | 3 | * License, v. 2.0. If a copy of the MPL was not distributed with this |
| michael@0 | 4 | * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ |
| michael@0 | 5 | |
| michael@0 | 6 | |
| michael@0 | 7 | #include "nsIDOMMouseEvent.idl" |
| michael@0 | 8 | |
| michael@0 | 9 | /** |
| michael@0 | 10 | * The nsIDOMSimpleGestureEvent interface is the datatype for all |
| michael@0 | 11 | * Mozilla-specific simple gesture events in the Document Object Model. |
| michael@0 | 12 | * |
| michael@0 | 13 | * The following events are generated: |
| michael@0 | 14 | * |
| michael@0 | 15 | * MozSwipeGestureStart - Generated when the user starts a horizontal |
| michael@0 | 16 | * swipe across the input device. This event not only acts as a signal, |
| michael@0 | 17 | * but also asks two questions: Should a swipe really be started, and |
| michael@0 | 18 | * in which directions should the user be able to swipe? The first |
| michael@0 | 19 | * question is answered by event listeners by calling or not calling |
| michael@0 | 20 | * preventDefault() on the event. Since a swipe swallows all scroll |
| michael@0 | 21 | * events, the default action of the swipe start event is *not* to |
| michael@0 | 22 | * start a swipe. Call preventDefault() if you want a swipe to be |
| michael@0 | 23 | * started. |
| michael@0 | 24 | * The second question (swipe-able directions) is answered in the |
| michael@0 | 25 | * allowedDirections field. |
| michael@0 | 26 | * If this event has preventDefault() called on it (and thus starts |
| michael@0 | 27 | * a swipe), it guarantees a future MozSwipeGestureEnd event that |
| michael@0 | 28 | * will signal the end of a swipe animation. |
| michael@0 | 29 | * |
| michael@0 | 30 | * MozSwipeGestureUpdate - Generated periodically while the user is |
| michael@0 | 31 | * continuing a horizontal swipe gesture. The "delta" value represents |
| michael@0 | 32 | * the current absolute gesture amount. This event may even be sent |
| michael@0 | 33 | * after a MozSwipeGesture event fired in order to allow for fluid |
| michael@0 | 34 | * completion of a swipe animation. The direction value is meaningless |
| michael@0 | 35 | * on swipe update events. |
| michael@0 | 36 | * |
| michael@0 | 37 | * MozSwipeGestureEnd - Generated when the swipe animation is completed. |
| michael@0 | 38 | * |
| michael@0 | 39 | * MozSwipeGesture - Generated when the user releases a swipe across |
| michael@0 | 40 | * across the input device. This event signals that the actual swipe |
| michael@0 | 41 | * operation is complete, even though the animation might not be finished |
| michael@0 | 42 | * yet. This event can be sent without accompanying start / update / end |
| michael@0 | 43 | * events, and it can also be handled on its own if the consumer doesn't |
| michael@0 | 44 | * want to handle swipe animation events. |
| michael@0 | 45 | * Only the direction value has any significance, the delta value is |
| michael@0 | 46 | * meaningless. |
| michael@0 | 47 | * |
| michael@0 | 48 | * MozMagnifyGestureStart - Generated when the user begins the magnify |
| michael@0 | 49 | * ("pinch") gesture. The "delta" value represents the initial |
| michael@0 | 50 | * movement. |
| michael@0 | 51 | * |
| michael@0 | 52 | * MozMagnifyGestureUpdate - Generated periodically while the user is |
| michael@0 | 53 | * continuing the magnify ("pinch") gesture. The "delta" value |
| michael@0 | 54 | * represents the movement since the last MozMagnifyGestureStart or |
| michael@0 | 55 | * MozMagnifyGestureUpdate event. |
| michael@0 | 56 | * |
| michael@0 | 57 | * MozMagnifyGesture - Generated when the user has completed the |
| michael@0 | 58 | * magnify ("pinch") gesture. If you only want to receive a single |
| michael@0 | 59 | * event when the magnify gesture is complete, you only need to hook |
| michael@0 | 60 | * this event and can safely ignore the MozMagnifyGestureStart and the |
| michael@0 | 61 | * MozMagnifyGestureUpdate events. The "delta" value is the cumulative |
| michael@0 | 62 | * amount represented by the user's gesture. |
| michael@0 | 63 | * |
| michael@0 | 64 | * MozRotateGestureStart - Generated when the user begins the rotation |
| michael@0 | 65 | * gesture. The "delta" value represents the initial rotation. |
| michael@0 | 66 | * |
| michael@0 | 67 | * MozRotateGestureUpdate - Generated periodically while the user is |
| michael@0 | 68 | * continuing the rotation gesture. The "delta" value represents the |
| michael@0 | 69 | * rotation since the last MozRotateGestureStart or |
| michael@0 | 70 | * MozRotateGestureUpdate event. |
| michael@0 | 71 | * |
| michael@0 | 72 | * MozRotateGesture - Generated when the user has completed the |
| michael@0 | 73 | * rotation gesture. If you only want to receive a single event when |
| michael@0 | 74 | * the rotation gesture is complete, you only need to hook this event |
| michael@0 | 75 | * and can safely ignore the MozRotateGestureStart and the |
| michael@0 | 76 | * MozRotateGestureUpdate events. The "delta" value is the cumulative |
| michael@0 | 77 | * amount of rotation represented by the user's gesture. |
| michael@0 | 78 | * |
| michael@0 | 79 | * MozTapGesture - Generated when the user executes a two finger |
| michael@0 | 80 | * tap gesture on the input device. Client coordinates contain the |
| michael@0 | 81 | * center point of the tap. |
| michael@0 | 82 | * (XXX On OS X, only Lion (10.7) and up) |
| michael@0 | 83 | * |
| michael@0 | 84 | * MozPressTapGesture - Generated when the user executes a press |
| michael@0 | 85 | * and tap two finger gesture (first finger down, second finger down, |
| michael@0 | 86 | * second finger up, first finger up) on the input device. |
| michael@0 | 87 | * Client coordinates contain the center pivot point of the action. |
| michael@0 | 88 | * (XXX Not implemented on Mac) |
| michael@0 | 89 | * |
| michael@0 | 90 | * MozEdgeUIGesture - Generated when the user swipes the display to |
| michael@0 | 91 | * invoke edge ui. |
| michael@0 | 92 | * (XXX Win8 only) |
| michael@0 | 93 | * |
| michael@0 | 94 | * Default behavior: |
| michael@0 | 95 | * |
| michael@0 | 96 | * Some operating systems support default behaviors for gesture events |
| michael@0 | 97 | * when they are not handled by the application. Consumers should |
| michael@0 | 98 | * use event.preventDefault() to prevent default behavior when |
| michael@0 | 99 | * consuming events. |
| michael@0 | 100 | */ |
| michael@0 | 101 | |
| michael@0 | 102 | [scriptable, builtinclass, uuid(d78656ab-9d68-4f03-83f9-7c7bee071aa7)] |
| michael@0 | 103 | interface nsIDOMSimpleGestureEvent : nsIDOMMouseEvent |
| michael@0 | 104 | { |
| michael@0 | 105 | /* Swipe direction constants */ |
| michael@0 | 106 | const unsigned long DIRECTION_UP = 1; |
| michael@0 | 107 | const unsigned long DIRECTION_DOWN = 2; |
| michael@0 | 108 | const unsigned long DIRECTION_LEFT = 4; |
| michael@0 | 109 | const unsigned long DIRECTION_RIGHT = 8; |
| michael@0 | 110 | |
| michael@0 | 111 | /* Rotational direction constants */ |
| michael@0 | 112 | const unsigned long ROTATION_COUNTERCLOCKWISE = 1; |
| michael@0 | 113 | const unsigned long ROTATION_CLOCKWISE = 2; |
| michael@0 | 114 | |
| michael@0 | 115 | /* Read-write value for swipe events. |
| michael@0 | 116 | * |
| michael@0 | 117 | * Reports the directions that can be swiped to; multiple directions |
| michael@0 | 118 | * should be OR'ed together. |
| michael@0 | 119 | * |
| michael@0 | 120 | * The allowedDirections field is designed to be set on SwipeGestureStart |
| michael@0 | 121 | * events by event listeners. Its value after event dispatch determines |
| michael@0 | 122 | * the behavior of the swipe animation that is about to begin. |
| michael@0 | 123 | * Specifically, if the user swipes in a direction that can't be swiped |
| michael@0 | 124 | * to, the animation will have a bounce effect. |
| michael@0 | 125 | * Future SwipeGestureUpdate, SwipeGesture and SwipeGestureEnd events |
| michael@0 | 126 | * will carry the allowDirections value that was set on the SwipeStart |
| michael@0 | 127 | * event. Changing this field on non-SwipeGestureStart events doesn't |
| michael@0 | 128 | * have any effect. |
| michael@0 | 129 | */ |
| michael@0 | 130 | attribute unsigned long allowedDirections; |
| michael@0 | 131 | |
| michael@0 | 132 | /* Direction of a gesture. Diagonals are indicated by OR'ing the |
| michael@0 | 133 | * applicable constants together. |
| michael@0 | 134 | * |
| michael@0 | 135 | * Swipes gestures may occur in any direction. |
| michael@0 | 136 | * |
| michael@0 | 137 | * Magnify gestures do not have a direction. |
| michael@0 | 138 | * |
| michael@0 | 139 | * Rotation gestures will be either ROTATION_COUNTERCLOCKWISE or |
| michael@0 | 140 | * ROTATION_CLOCKWISE. |
| michael@0 | 141 | */ |
| michael@0 | 142 | readonly attribute unsigned long direction; |
| michael@0 | 143 | |
| michael@0 | 144 | /* Delta value for magnify, rotate and swipe gestures. |
| michael@0 | 145 | * |
| michael@0 | 146 | * For rotation, the value is in degrees and is positive for |
| michael@0 | 147 | * clockwise rotation and negative for counterclockwise |
| michael@0 | 148 | * rotation. |
| michael@0 | 149 | * |
| michael@0 | 150 | * For magnification, the value will be positive for a "zoom in" |
| michael@0 | 151 | * (i.e, increased magnification) and negative for a "zoom out" |
| michael@0 | 152 | * (i.e., decreased magnification). The particular units |
| michael@0 | 153 | * represented by the "delta" are currently implementation specific. |
| michael@0 | 154 | * |
| michael@0 | 155 | * XXX - The units for measuring magnification are currently |
| michael@0 | 156 | * unspecified because the units used by Mac OS X are currently |
| michael@0 | 157 | * undocumented. The values are typically in the range of 0.0 to |
| michael@0 | 158 | * 100.0, but it is only safe currently to rely on the delta being |
| michael@0 | 159 | * positive or negative. |
| michael@0 | 160 | * |
| michael@0 | 161 | * For swipe start, update and end events, the value is a fraction |
| michael@0 | 162 | * of one "page". If the resulting swipe will have DIRECTION_LEFT, the |
| michael@0 | 163 | * delta value will be positive; for DIRECTION_RIGHT, delta is negative. |
| michael@0 | 164 | * If this seems backwards to you, look at it this way: If the current |
| michael@0 | 165 | * page is pushed to the right during the animation (positive delta), |
| michael@0 | 166 | * the page left to the current page will be visible after the swipe |
| michael@0 | 167 | * (DIRECTION_LEFT). |
| michael@0 | 168 | * |
| michael@0 | 169 | * Units on Windows represent the difference between the initial |
| michael@0 | 170 | * and current/final width between the two touch points on the input |
| michael@0 | 171 | * device and are measured in pixels. |
| michael@0 | 172 | */ |
| michael@0 | 173 | readonly attribute double delta; |
| michael@0 | 174 | |
| michael@0 | 175 | /* Click count value for taps. */ |
| michael@0 | 176 | readonly attribute unsigned long clickCount; |
| michael@0 | 177 | |
| michael@0 | 178 | void initSimpleGestureEvent(in DOMString typeArg, |
| michael@0 | 179 | in boolean canBubbleArg, |
| michael@0 | 180 | in boolean cancelableArg, |
| michael@0 | 181 | in nsIDOMWindow viewArg, |
| michael@0 | 182 | in long detailArg, |
| michael@0 | 183 | in long screenXArg, |
| michael@0 | 184 | in long screenYArg, |
| michael@0 | 185 | in long clientXArg, |
| michael@0 | 186 | in long clientYArg, |
| michael@0 | 187 | in boolean ctrlKeyArg, |
| michael@0 | 188 | in boolean altKeyArg, |
| michael@0 | 189 | in boolean shiftKeyArg, |
| michael@0 | 190 | in boolean metaKeyArg, |
| michael@0 | 191 | in unsigned short buttonArg, |
| michael@0 | 192 | in nsIDOMEventTarget relatedTargetArg, |
| michael@0 | 193 | in unsigned long allowedDirectionsArg, |
| michael@0 | 194 | in unsigned long directionArg, |
| michael@0 | 195 | in double deltaArg, |
| michael@0 | 196 | in unsigned long clickCount); |
| michael@0 | 197 | }; |
