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