Transform Action Event Interface




Editor:
Cathy Chan, Nokia

Copyright © 2010 Nokia

Abstract

This document describes event types that can be used for building directly manipulated user interfaces.

Status of This Document

Nokia hereby grants to the W3C a perpetual, nonexclusive, royalty-free, world-wide right and license under any Nokia copyrights on this contribution, to copy, publish and distribute the contribution under the W3C document licenses.

Additionally, should the submission be used as a contribution towards a W3C Activity, Nokia grants a right and license of the same scope to any derivative works prepared by the W3C and based on, or incorporating all or part of, the contribution. Nokia further agrees that any derivative works of this contribution prepared by the W3C shall be solely owned by the W3C.

Nokia Corporation agrees to offer W3C members and non-members granting reciprocal terms a non-assignable, non-sublicensable, worldwide and royalty free license to make, have made, use, sell, have sold, offer to sell, import, and distribute and dispose of implementations of any portion of the submission that is subsequently incorporated into a W3C Recommendation. Such license shall extend to all Essential Claims owned or controlled by Nokia Corporation and shall be available as long as the Recommendation is in effect.

Table of Contents

1. Introduction

Touch screens with directly manipulated user interface have become mainstream in portable devices. Current web technology is specified for mouse use and implementation of direct manipulation is kludgy and non portable at best.

This document describes three new event types to enable direct manipulation of a DOM element. Typically these events are generated as the user does an action or gesture such as "pan", "zoom", or "rotate" requesting transformation of a visual element. As the gestures and actions to transform a visual element vary from device to device, this proposal abstracts them out and provides interface to the actual action the end user is attempting to do.

1.1 Usage Examples

Example 1.

A box that can be dragged, rotated, and scaled on the screen.

<html> 
<head> 
    <style> 
        #box {
            position: absolute;
            border: 3px solid black;
            width: 200px;
            height: 200px;
            left: 200px;
            top: 100px;
        }
    </style> 
</head> 
<body> 
    <div id="box"
        ontransformactionstart="transformStart(event);"
        ontransformactionupdate="transformUpdate(event);"
        ontransformactionend="transformEnd(event);"></div> 
    <script> 
            // Initialize the current transform values
            var curX = 0;
            var curY = 0;
            var curRotation = 0;
            var curScalefactor = 1.0;
            var box = document.getElementById("box");
 
            function transformStart(e) {
                // Prevent browser zoom
                e.preventDefault();
            }
    
            function transformUpdate(e) {
                // Set the new transform
                box.style.transform = 
                    "translate(" + (curX + e.translateX) + "px, " + (curY + e.translateY) + "px) " +
                    "rotate(" + (curRotation + e.rotate) + "rad) " +
                    "scale(" + (curScalefactor * e.scale) + ") ";
            }
 
            function transformEnd(e) {
                // Update the current transform values
                curX += e.translateX;
                curY += e.translateY;
                curRotation += e.rotate;
                curScalefactor *= e.scale;
            }
    </script> 
</body> 
</html>

2. Security and Privacy Considerations

No security or privacy issues identified.

3. Event definitions

The following events are defined in this specification

NameDescriptionHow often?When?
transformactionstartThe new transform action starts.OnceMust be dispatched first.
transformactionupdateThe transform action continues.Zero or moreMay be dispatched zero or more times after a transformactionstart.
transformactionendThe transform action ends.OnceMust be dispatched last.

User agents must implement these events such that by default they do bubble, and are cancelable.

User agents must ensure that these events trigger event listeners attached on the element nodes for that event on the capture and target phases.

Default action for these events is implementation specific (for example, adjustment of the user agent zoom level.)

These events are in the null namespace. Initialisation method assigns the null namespace automatically.

In the transformactionstart event, attributes rotate, translateX, translateY, rotateSpeed, scaleSpeed, translateSpeedX, and translateSpeedY must always have the value zero and attribute scale must always have the value one.

4. Event firing order

The user agent must dispatch a transformactionstart event when the user starts the interaction (for example, touches the screen).

The user agent must dispatch one or more transformactionupdate events when the user continues the interaction (for example, moves finger(s) on the touch screen).

When the user end the interfaction (for example, stops touching the screen), the user agent must dispatch a transformactionend event.

In short, for the DOM element in question, there must one transformactionstart event, followed by zero or more transformactionupdate, followed by one transformactionend event.

The user agent must dispatch all transformaction events immediately after related lower level events if such lower level event exists. For example, if the source of transformaction events is a touch screen, the transformaction events must be dispatched immediately after the touch events.

5. TransformActionEvent module

5.1 TransformActionEvent interface

The TransformAction interface exposes the information in transformactionstart, transformactionupdate, and transformactionend events.

[Supplemental]
interface TransformActionEvent : UIEvent {
    readonly attribute long screenX;
    readonly attribute long screenY;
    readonly attribute long offsetX;
    readonly attribute long offsetY;
    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 translateX;
    readonly attribute long translateY;
    readonly attribute long translateSpeedX;
    readonly attribute long translateSpeedY;
    readonly attribute float scale; 
    readonly attribute float scaleSpeed;
    readonly attribute float rotate; 
    readonly attribute float rotateSpeed;
 
    void initTransformActionEvent (in DOMString type, in boolean canBubble, in boolean cancelable, in DOMWindow view, 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 translateX, in long translateY, in long translateSpeedX, in long translateSpeedY, in float scale, in float scaleSpeed, in float rotate, in float rotateSpeed); };

5.1.1 Attributes

altKey of type boolean, readonly
Status of the alt key during the event.
No exceptions.
clientX of type long, readonly
The horizontal coordinate at which the event occurred relative to the origin of the viewport.
No exceptions.
clientY of type long, readonly
The vertical coordinate at which the event occurred relative to the origin of the viewport.
No exceptions.
ctrlKey of type boolean, readonly
Status of the control key during the event.
No exceptions.
metaKey of type boolean, readonly
Status of the meta key during the event.
No exceptions.
offsetX of type long, readonly
The horizontal coordinate at which the event occurred relative to the origin of the padding edge of the target node. [CSSOMView]
No exceptions.
offsetY of type long, readonly
The vertical coordinate at which the event occurred relative to the origin of the padding edge [CSSOMView] of the target node. [CSSOMView]
No exceptions.
rotate of type float, readonly

Rotation angle in radians, increasing angle meaning rotation clockwise.

If just a single finger touches the screen, rotation is 0.

No exceptions.
rotateSpeed of type float, readonly
Rotation speed in radians per second. The user agent should use best effort to approximate the speed.
No exceptions.
scale of type float, readonly

Scale factor, between 0 and 1.0 for scale down, greater than 1.0 for scale up.

For example 2.5 when the distance of touch points has increased 2.5-fold, i.e. element should be scaled 2.5 times its original size.

If just a single finger touches the screen, scale is 1.0.

No exceptions.
scaleSpeed of type float, readonly
Speed of scaling in normalized scale factor change per second. The user agent should use best effort to approximate the speed.
No exceptions.
screenX of type long, readonly
The horizontal coordinate at which the event occurred relative to the origin of the screen.
No exceptions.
screenY of type long, readonly
The vertical coordinate at which the event occurred relative to the origin of the screen.
No exceptions.
shiftKey of type boolean, readonly
Status of the shift key during the event.
No exceptions.
translateSpeedX of type long, readonly
The horizontal panning speed in pixels per seconds in client coordinate space. The user agent should use best effort to approximate the speed.
No exceptions.
translateSpeedY of type long, readonly
The vertical panning speed in pixels per seconds in client coordinate space. The user agent should use best effort to approximate the speed.
No exceptions.
translateX of type long, readonly

The horizontal coordinate in client coordinate space that indicates the panning of the element. Translation coordinates are activated even with a single finger.

Translation coordinates are always relative to the start of the touch. Thus there is no need to calculate absolute offsets of elements on the page when moving an element. Translation values can only be added to the starting position of an element.

No exceptions.
translateY of type long, readonly

The vertical coordinate in client coordinate space that indicates the panning of the element. Translation coordinates are activated even with a single finger.

Translation coordinates are always relative to the start of the touch. Thus there is no need to calculate absolute offsets of elements on the page when moving an element. Translation values can only be added to the starting position of an element.

No exceptions.

5.1.2 Methods

initTransformActionEvent

This method is used to initialize the value of a TransformActionEvent object and has the same behavior as Event.initEventNS(), where the value of the namespace parameter is specified as null [D3E].

ParameterTypeNullableOptionalDescription
typeDOMString??This must be one of transformactionstart, transformactionupdate, or transformactionend. If it is not one of those values then this specification does not define the resulting event. Refer to the Event.initEvent() method [D3E] for further description of this parameter.
canBubbleboolean??Specifies Event.bubbles. This parameter overrides the intrinsic bubbling behavior of the event and determines whether the event created will bubble
cancelableboolean??Specifies Event.cancelable. This parameter overrides the intrinsic cancel behavior of the event and determines whether the event created is cancelable
viewDOMWindow??Specifies the DOM window in which the event occurred.
screenXlong??The horizontal coordinate at which the event occurred relative to the origin of the screen.
screenYlong??The vertical coordinate at which the event occurred relative to the origin of the screen.
clientXlong??The horizontal coordinate at which the event occurred relative to the origin of the viewport.
clientYlong??The vertical coordinate at which the event occurred relative to the origin of the viewport.
ctrlKeyboolean??Status of the control key during the event.
altKeyboolean??Status of the shift key during the event.
shiftKeyboolean??Status of the alt key during the event.
metaKeyboolean??Status of the meta key during the event.
translateXlong??The horizontal coordinate in client coordinate space that indicates the panning of the element.
translateYlong??The vertical coordinate in client coordinate space that indicates the panning of the element.
translateSpeedXlong??The horizontal panning speed in pixels per seconds in client coordinate space. The user agent should use best effort to approximate the speed.
translateSpeedYlong??The vertical panning speed in pixels per seconds in client coordinate space. The user agent should use best effort to approximate the speed.
scalefloat??Scale factor, between 0 and 1.0 for scale down, greater than 1.0 scale up. For example 2.5 when the distance of touch points has increased 2.5-fold, i.e. element should be scaled 2.5 times its original size.
scaleSpeedfloat??Speed of scaling in normalized scale factor change per second. The user agent should use best effort to approximate the speed.
rotatefloat??Rotation angle in radians, increasing angle meaning rotation clockwise.
rotateSpeedfloat??Rotation speed in radians per second. The user agent should use best effort to approximate the speed.
No exceptions.
Return type: void

A. References

A.1 Normative references

No normative references.

A.2 Informative references

No informative references.