Starlight Touch Documentation

0.1

This document covers Touch implementation for Windows 7 in Qt / WebKit.

Overview

The life of a touch event begins at the user making a touch interaction. The frontend handles the touch event and passes it to WebCore::EventHandler::handleTouch.

WebCore::EventHandler::handleTouch first updates its gesture context by calling WebCore::GestureContext::touchEvent. The gesture context updates the state of all GestureRecognizer objects it holds. After that WebCore::EventHandler::handleTouch calls the following in this order:

After WebCore::EventHandler::handleTouch returns, the frontend can do page manipulation such as scrolling or zooming unless the mouse event started a manipulate for which the DOM handler declined the default handler execution by calling preventDefault on the event.

DOM-events

TouchEvent

Definition

module events {

    interface [
        GenerateConstructor
    ] TouchEvent : UIEvent {
        readonly attribute long            id;
        readonly attribute long            screenX;
        readonly attribute long            screenY;
        readonly attribute long            clientX;
        readonly attribute long            clientY;
        readonly attribute boolean         ctrlKey;
        readonly attribute boolean         shiftKey;
        readonly attribute boolean         altKey;
        readonly attribute boolean         metaKey;
        readonly attribute float           pressure;
        readonly attribute long            rectWidth;
        readonly attribute long            rectHeight;
        readonly attribute EventTarget     relatedTarget;

        [OldStyleObjC] void initTouchEvent(in DOMString type,
                                           in boolean canBubble,
                                           in boolean cancelable,
                                           in DOMWindow view,
                                           in long detail,
                                           in long id,
                                           in long screenX,
                                           in long screenY,
                                           in long clientX,
                                           in long clientY,
                                           in boolean ctrlKey,
                                           in boolean altKey,
                                           in boolean shiftKey,
                                           in boolean metaKey,
                                           in float pressure,
                                           in long rectWidth,
                                           in long rectHeight,
                                           in EventTarget relatedTarget);
    };
}

See detailed descriptions in WebCore::TouchEvent class reference page.

Behaviour

One touch event is fired for every touch point to the element under the touch point. Touch event gives ID for the touch and positional information. TouchEvent can have the following types: touchdown, touchup, touchmove.

ManipulateEvent

Definition

module events {
    interface [
        GenerateConstructor
    ] ManipulateEvent : UIEvent {
        readonly attribute long screenX;
        readonly attribute long screenY;
        readonly attribute long clientX;
        readonly attribute long clientY;

        readonly attribute boolean ctrlKey;
        readonly attribute boolean shiftKey;
        readonly attribute boolean altKey;
        readonly attribute boolean metaKey;

        readonly attribute long panX;
        readonly attribute long panY;
        readonly attribute long panSpeedX;
        readonly attribute long panSpeedY;
        readonly attribute float scale;
        readonly attribute float scaleSpeed;
        readonly attribute float rotation;
        readonly attribute float rotationSpeed;

        [OldStyleObjC] void initManipulateEvent(in DOMString type,
                                                in boolean canBubble,
                                                in boolean cancelable,
                                                in DOMWindow view,
                                                in long detail,
                                                in long screenX,
                                                in long screenY,
                                                in long clientX,
                                                in long clientY,
                                                in boolean ctrlKey,
                                                in boolean altKey,
                                                in boolean shiftKey,
                                                in boolean metaKey,
                                                in long panX,
                                                in long panY,
                                                in long panSpeedX,
                                                in long panSpeedY,
                                                in float scale,
                                                in float scaleSpeed,
                                                in float rotation,
                                                in float rotationSpeed);
   };
}

See detailed descriptions in WebCore::ManipulateEvent class reference page.

Behaviour

The target element for manipulatestart event is the element that was pressed first. All manipulatemove events and manipulateend event are fired to the same element than manipulatestart.

manipulatestart

Happens when finger or fingers appear on the screen for the first time.

The attribute values are set as follows:

manipulateend

Happens when all the remaining fingers are releasing from the screen. Attribute values are kept as the same as in the latest move event.

manipulatemove

In all cases finger that are higher order than two are simply ignored. Only two oldest are always considered.

Scale:

Rotation:

Pan:

Sending DOM-events

Introduction

DOM events coming from platfrom are processed synchronously. When dispatch-functions return JavaScript has processed the event completely. There is also asynchronous function for calling specific JavaScript functions from platform called MainThread::callOnMainThread but this does not concern event sending at all. Unless this specific function is called, communication between WebCore and JavaScriptCore is synchronous.

WebCore

What happens when DOM event is sent?

The following:

  1. Instance of Node gets message dispatchEvent. Let's call the instance N.

  2. N sends message dispatchGenericEvent to itself.
  3. N traverses DOM-tree up to the root and sends message handleLocalEvents to every node until root of the DOM tree is reached.

Node has a list of EventListener instances. Node::handleLocalEvents calls EventListener::handleEvent for each EventListener instance. In the context of this specification the following assumption can be made: EventListener instances are always JSEventListener instances.

JavaScriptCore

Let's call JSEventListener instance as E for the discussion. In handleEvent E configures JavaScript object that represents handleEvent message for the counter-part JavaScript object. After that E calls indirectly Interpreter::execute through global function call defined in CallData.h. This function actually executes the byte code.

Mouse emulation

Mouse emulation passes touch events to corresponding mouse event handlers in WebKit. Before passing the event it however:

Mouse emulation is cancelled if more than one fingers touch the screen. Mouse emulation will then be active only after all fingers have been lifted from the screen.

Selecting element from area

Criteria for best element selection:

Smart hit testing algorithm

Long tap

Hover mode ends when the finger is released from the screen.

Page manipulation

Deployment

MODIFIED:

ADDED:


Generated on Fri Oct 9 13:00:23 2009 for Starlight Touch by  doxygen 1.5.8