Drag

A drag gesture consists of a touch/mousedown event followed by a move, followed by an end event. On touch-based devices, a drag gesture is initiated when the user places a finger on the device screen, within the gesture area, and moves the finger without lifting it from the screen. Note that if the device differentiates between multiple and single touches, then a drag gesture is only initiated by a single touch, otherwise it is initiated by any number of touches. On mouse-based devices, the gesture is initiated when the user presses the mouse button and moves the mouse without releasing the button. An end event is fired when the user removes the finger from the screen, or releases the mouse button.

For the previous sequence of events to be recognized as a drag gesture, the distance between the start and end points must be significant. Exactly what constitutes a significant distance is a device specific issue, i.e. the distance may differ from device to device.

Panning/scrolling pages

Typically, touch-based devices use a drag gesture for panning or scrolling. To prevent that from conflicting with the actions that are performed during the drag gesture, the default panning and scrolling behavior is blocked. However, if the element on which the drag gesture occurs covers a significant portion of the screen, then it can be difficult if not impossible for the user to pan the screen. Therefore, selected areas on the viewport are reserved for panning/scrolling, i.e. in those areas drag gestures are never recognized and so the default panning/scrolling behavior is not blocked.

The reserved areas are added as follows:

If the page needs to be panned vertically, then there is a reserved area at the right-hand side of the viewport that is about 50 CSS pixels wide and covers the entire height of the viewport.
If the page needs to be panned horizontally, then there is a reserved area on the viewport that is about 50 CSS pixels high and covers the whole width of the viewport.

Mouse-based devices usually use a scroll bar or mouse wheel to perform scrolling and therefore do not require a reserved area for panning/scrolling.

Features

Support for the drag gesture is represented by the following feature:

mcs:gestures.Drag

Events

Each phase of a drag gesture is reported to the application through an event handler, with the following event types:

Event	Description
mcs:drag-start	Indicates that the drag gesture has started.
mcs:drag	Indicates that the drag gesture progresses.
mcs:drag-end	Indicates the successful completion of the drag gesture.
mcs:drag-cancel	Indicates that the drag gesture has been canceled.

All drag events use the following event structure. Note that all coordinates are in logical pixels, i.e. CSS pixels.

Parameter	Description	Type
target	The identifier of the element which the gesture recognizer was observing.	Element
timeStamp	The time at which the gesture was at this position, in milliseconds.	long
pageX	The x-coordinate of the position of the gesture in page coordinates.	int
pageY	The y-coordinate of the position of the gesture in page coordinates.	int
clientX	The x-coordinate of the position of the gesture relative to the left edge of the viewport.	int
clientY	The y-coordinate of the position of the gesture relative to the top edge of the viewport.	int

In order for drag events to be fired and captured at a presentation element, a listener for the mcs:drag-start event needs to be added to it. That element becomes both the observer and target element. mcs:drag events are fired as the touch point moves, or as the mouse moves while the mouse button is held down. An mcs:drag-end event is fired whenever the touch is removed from the screen, or the mouse button is released. An mcs:drag-cancel event is fired if the touch is canceled (although exactly when this occurs is a device specific detail), if the number of touches changes (only if the device can detect multiple touches), or if the mouse moves outside the page, e.g. outside the browser window that contains the page.

Note that if an element that observes drag events is nested inside another element that also observes them, then events for a drag gesture that starts within the inner element are fired at the inner element and not the outer element.

Example

The existing elements, namely mcs:handler and event:listener, allow page authors to use gestures.

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:mcs="http://www.volantis.com/xmlns/2006/01/xdime/mcs"
  xmlns:event="http://www.w3.org/2001/xml-events"
  xmlns:cst="http://www.volantis.com/xmlns/2009/07/cf2/template"
  xmlns:sel="http://www.w3.org/2004/06/diselect">
  <head>
    <title>Drag gestures</title>
    <style type="text/css">
      #dragarea {
        height: 200px;
        background-color: red;
      }
    </style>
    <mcs:script> var t; V$C.linking(function(c){ t = c.get('presenter'); }); </mcs:script>
    <mcs:handler id="drag-handler" type="text/javascript"> t.setData(event); </mcs:handler>
    <event:listener observer="dragarea" handler="#drag-handler" event="mcs:drag-start"/>
    <event:listener observer="dragarea" handler="#drag-handler" event="mcs:drag-end"/>
    <event:listener observer="dragarea" handler="#drag-handler" event="mcs:drag"/>
    <event:listener observer="dragarea" handler="#drag-handler" event="mcs:drag-cancel"/>
  </head>
  <body>
    <cst:template id="presenter">
      <sel:select>
        <sel:when expr="mcs:feature('mcs:gestures.Drag')">
          <h4 id="dragarea">Dragging area</h4>
          <div id="msg"/>
          <table>
            <tr>
              <td>Type:</td>
              <td colspan="2"><cst:value path="type"/></td>
            </tr>
            <tr>
              <td>Target ID:</td>
              <td colspan="2"><cst:value path="target.id"/></td>
            </tr>
            <tr>
              <td rowspan="3">start</td>
              <td>timestamp:</td>
              <td><cst:value path="timeStamp"/></td>
            </tr>
            <tr>
              <td>pageX:</td>
              <td><cst:value path="pageX"/></td>
            </tr>
            <tr>
              <td>pageY:</td>
              <td><cst:value path="pageY"/></td>
            </tr>
            <tr>
              <td>clientX:</td>
              <td><cst:value path="clientX"/></td>
            </tr>
            <tr>
              <td>clientY:</td>
              <td><cst:value path="clientY"/></td>
            </tr>
          </table>
        </sel:when>
        <sel:otherwise>
          <div class="warning">Drag is not supported </div>
        </sel:otherwise>
      </sel:select>
    </cst:template>
  </body>
</html>

Drag

Panning/scrolling pages

Features

Events

Example

Related topics