michael@0: /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: 
michael@0: #include "nsIDOMMouseEvent.idl"
michael@0: 
michael@0: /**
michael@0:  * The nsIDOMSimpleGestureEvent interface is the datatype for all
michael@0:  * Mozilla-specific simple gesture events in the Document Object Model.
michael@0:  *
michael@0:  * The following events are generated:
michael@0:  *
michael@0:  * MozSwipeGestureStart - Generated when the user starts a horizontal
michael@0:  * swipe across the input device.  This event not only acts as a signal,
michael@0:  * but also asks two questions:  Should a swipe really be started, and
michael@0:  * in which directions should the user be able to swipe?  The first
michael@0:  * question is answered by event listeners by calling or not calling
michael@0:  * preventDefault() on the event.  Since a swipe swallows all scroll
michael@0:  * events, the default action of the swipe start event is *not* to
michael@0:  * start a swipe. Call preventDefault() if you want a swipe to be
michael@0:  * started.
michael@0:  * The second question (swipe-able directions) is answered in the
michael@0:  * allowedDirections field.
michael@0:  * If this event has preventDefault() called on it (and thus starts
michael@0:  * a swipe), it guarantees a future MozSwipeGestureEnd event that
michael@0:  * will signal the end of a swipe animation.
michael@0:  *
michael@0:  * MozSwipeGestureUpdate - Generated periodically while the user is
michael@0:  * continuing a horizontal swipe gesture.  The "delta" value represents
michael@0:  * the current absolute gesture amount.  This event may even be sent
michael@0:  * after a MozSwipeGesture event fired in order to allow for fluid
michael@0:  * completion of a swipe animation.  The direction value is meaningless
michael@0:  * on swipe update events.
michael@0:  *
michael@0:  * MozSwipeGestureEnd - Generated when the swipe animation is completed.
michael@0:  *
michael@0:  * MozSwipeGesture - Generated when the user releases a swipe across
michael@0:  * across the input device.  This event signals that the actual swipe
michael@0:  * operation is complete, even though the animation might not be finished
michael@0:  * yet.  This event can be sent without accompanying start / update / end
michael@0:  * events, and it can also be handled on its own if the consumer doesn't
michael@0:  * want to handle swipe animation events.
michael@0:  * Only the direction value has any significance, the delta value is
michael@0:  * meaningless.
michael@0:  *
michael@0:  * MozMagnifyGestureStart - Generated when the user begins the magnify
michael@0:  * ("pinch") gesture.  The "delta" value represents the initial
michael@0:  * movement.
michael@0:  *
michael@0:  * MozMagnifyGestureUpdate - Generated periodically while the user is
michael@0:  * continuing the magnify ("pinch") gesture.  The "delta" value
michael@0:  * represents the movement since the last MozMagnifyGestureStart or
michael@0:  * MozMagnifyGestureUpdate event.
michael@0:  *
michael@0:  * MozMagnifyGesture - Generated when the user has completed the
michael@0:  * magnify ("pinch") gesture.  If you only want to receive a single
michael@0:  * event when the magnify gesture is complete, you only need to hook
michael@0:  * this event and can safely ignore the MozMagnifyGestureStart and the
michael@0:  * MozMagnifyGestureUpdate events. The "delta" value is the cumulative
michael@0:  * amount represented by the user's gesture.
michael@0:  *
michael@0:  * MozRotateGestureStart - Generated when the user begins the rotation
michael@0:  * gesture.  The "delta" value represents the initial rotation.
michael@0:  *
michael@0:  * MozRotateGestureUpdate - Generated periodically while the user is
michael@0:  * continuing the rotation gesture.  The "delta" value represents the
michael@0:  * rotation since the last MozRotateGestureStart or
michael@0:  * MozRotateGestureUpdate event.
michael@0:  *
michael@0:  * MozRotateGesture - Generated when the user has completed the
michael@0:  * rotation gesture.  If you only want to receive a single event when
michael@0:  * the rotation gesture is complete, you only need to hook this event
michael@0:  * and can safely ignore the MozRotateGestureStart and the
michael@0:  * MozRotateGestureUpdate events.  The "delta" value is the cumulative
michael@0:  * amount of rotation represented by the user's gesture.
michael@0:  *
michael@0:  * MozTapGesture - Generated when the user executes a two finger
michael@0:  * tap gesture on the input device. Client coordinates contain the
michael@0:  * center point of the tap.
michael@0:  * (XXX On OS X, only Lion (10.7) and up)
michael@0:  *
michael@0:  * MozPressTapGesture - Generated when the user executes a press
michael@0:  * and tap two finger gesture (first finger down, second finger down,
michael@0:  * second finger up, first finger up) on the input device.
michael@0:  * Client coordinates contain the center pivot point of the action.
michael@0:  * (XXX Not implemented on Mac)
michael@0:  *
michael@0:  * MozEdgeUIGesture - Generated when the user swipes the display to
michael@0:  * invoke edge ui.
michael@0:  * (XXX Win8 only)
michael@0:  *
michael@0:  * Default behavior:
michael@0:  *
michael@0:  * Some operating systems support default behaviors for gesture events
michael@0:  * when they are not handled by the application. Consumers should
michael@0:  * use event.preventDefault() to prevent default behavior when
michael@0:  * consuming events.
michael@0:  */
michael@0: 
michael@0: [scriptable, builtinclass, uuid(d78656ab-9d68-4f03-83f9-7c7bee071aa7)]
michael@0: interface nsIDOMSimpleGestureEvent : nsIDOMMouseEvent
michael@0: {
michael@0:   /* Swipe direction constants */
michael@0:   const unsigned long DIRECTION_UP = 1;
michael@0:   const unsigned long DIRECTION_DOWN = 2;
michael@0:   const unsigned long DIRECTION_LEFT = 4;
michael@0:   const unsigned long DIRECTION_RIGHT = 8;
michael@0: 
michael@0:   /* Rotational direction constants */
michael@0:   const unsigned long ROTATION_COUNTERCLOCKWISE = 1;
michael@0:   const unsigned long ROTATION_CLOCKWISE = 2;
michael@0: 
michael@0:   /* Read-write value for swipe events.
michael@0:    *
michael@0:    * Reports the directions that can be swiped to; multiple directions
michael@0:    * should be OR'ed together.
michael@0:    *
michael@0:    * The allowedDirections field is designed to be set on SwipeGestureStart
michael@0:    * events by event listeners.  Its value after event dispatch determines
michael@0:    * the behavior of the swipe animation that is about to begin.
michael@0:    * Specifically, if the user swipes in a direction that can't be swiped
michael@0:    * to, the animation will have a bounce effect.
michael@0:    * Future SwipeGestureUpdate, SwipeGesture and SwipeGestureEnd events
michael@0:    * will carry the allowDirections value that was set on the SwipeStart
michael@0:    * event.  Changing this field on non-SwipeGestureStart events doesn't
michael@0:    * have any effect.
michael@0:    */
michael@0:   attribute unsigned long allowedDirections;
michael@0: 
michael@0:   /* Direction of a gesture. Diagonals are indicated by OR'ing the
michael@0:    * applicable constants together.
michael@0:    *
michael@0:    * Swipes gestures may occur in any direction.
michael@0:    *
michael@0:    * Magnify gestures do not have a direction.
michael@0:    *
michael@0:    * Rotation gestures will be either ROTATION_COUNTERCLOCKWISE or
michael@0:    * ROTATION_CLOCKWISE.
michael@0:    */
michael@0:   readonly attribute unsigned long direction;
michael@0: 
michael@0:   /* Delta value for magnify, rotate and swipe gestures.
michael@0:    *
michael@0:    * For rotation, the value is in degrees and is positive for
michael@0:    * clockwise rotation and negative for counterclockwise
michael@0:    * rotation.
michael@0:    *
michael@0:    * For magnification, the value will be positive for a "zoom in"
michael@0:    * (i.e, increased magnification) and negative for a "zoom out"
michael@0:    * (i.e., decreased magnification).  The particular units
michael@0:    * represented by the "delta" are currently implementation specific.
michael@0:    *
michael@0:    * XXX - The units for measuring magnification are currently
michael@0:    * unspecified because the units used by Mac OS X are currently
michael@0:    * undocumented.  The values are typically in the range of 0.0 to
michael@0:    * 100.0, but it is only safe currently to rely on the delta being
michael@0:    * positive or negative.
michael@0:    *
michael@0:    * For swipe start, update and end events, the value is a fraction
michael@0:    * of one "page".  If the resulting swipe will have DIRECTION_LEFT, the
michael@0:    * delta value will be positive; for DIRECTION_RIGHT, delta is negative.
michael@0:    * If this seems backwards to you, look at it this way:  If the current
michael@0:    * page is pushed to the right during the animation (positive delta),
michael@0:    * the page left to the current page will be visible after the swipe
michael@0:    * (DIRECTION_LEFT).
michael@0:    *
michael@0:    * Units on Windows represent the difference between the initial
michael@0:    * and current/final width between the two touch points on the input
michael@0:    * device and are measured in pixels.
michael@0:    */
michael@0:   readonly attribute double delta;
michael@0: 
michael@0:   /* Click count value for taps. */
michael@0:   readonly attribute unsigned long clickCount;
michael@0: 
michael@0:   void initSimpleGestureEvent(in DOMString typeArg,
michael@0:                               in boolean canBubbleArg,
michael@0:                               in boolean cancelableArg,
michael@0:                               in nsIDOMWindow viewArg,
michael@0:                               in long detailArg,
michael@0:                               in long screenXArg,
michael@0:                               in long screenYArg,
michael@0:                               in long clientXArg,
michael@0:                               in long clientYArg,
michael@0:                               in boolean ctrlKeyArg,
michael@0:                               in boolean altKeyArg,
michael@0:                               in boolean shiftKeyArg,
michael@0:                               in boolean metaKeyArg,
michael@0:                               in unsigned short buttonArg,
michael@0:                               in nsIDOMEventTarget relatedTargetArg,
michael@0:                               in unsigned long allowedDirectionsArg,
michael@0:                               in unsigned long directionArg,
michael@0:                               in double deltaArg,
michael@0:                               in unsigned long clickCount);
michael@0: };