Bug 1270832 - Activate standard c++ library hardening r=glandium
[gecko.git] / dom / webidl / SimpleGestureEvent.webidl
blob048f49df481a063b0e16e22be124e56002db49a7
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  */
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  */
105 [ChromeOnly,
106  Exposed=Window]
107 interface SimpleGestureEvent : MouseEvent
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;
115   /* Rotational direction constants */
116   const unsigned long ROTATION_COUNTERCLOCKWISE = 1;
117   const unsigned long ROTATION_CLOCKWISE = 2;
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;
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;
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;
179   /* Click count value for taps. */
180   readonly attribute unsigned long clickCount;
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);