dom/webidl/SimpleGestureEvent.webidl

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