Safari DOM Extensions Reference

Safari DOM Extensions ReferenceUser Experience

2009-01-30

Apple Inc.© 2004, 2009 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, inany form or by any means, mechanical,electronic, photocopying, recording, orotherwise, without prior written permission ofApple Inc., with the following exceptions: Anyperson is hereby authorized to storedocumentation on a single computer forpersonal use only and to print copies ofdocumentation for personal use provided thatthe documentation contains Apple’s copyrightnotice.

The Apple logo is a trademark of Apple Inc.

Use of the “keyboard” Apple logo(Option-Shift-K) for commercial purposeswithout the prior written consent of Apple mayconstitute trademark infringement and unfaircompetition in violation of federal and statelaws.

No licenses, express or implied, are grantedwith respect to any of the technology describedin this document. Apple retains all intellectualproperty rights associated with the technologydescribed in this document. This document isintended to assist application developers todevelop applications only for Apple-labeledcomputers.

Every effort has been made to ensure that theinformation in this document is accurate. Appleis not responsible for typographical errors.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple, the Apple logo, QuickTime, and Safariare trademarks of Apple Inc., registered in theUnited States and other countries.

iPhone is a trademark of Apple Inc.

Java and all Java-based trademarks aretrademarks or registered trademarks of SunMicrosystems, Inc. in the U.S. and othercountries.

SPEC is a registered trademark of the StandardPerformance Evaluation Corporation (SPEC).

Simultaneously published in the United Statesand Canada.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,

EITHER EXPRESS OR IMPLIED, WITH RESPECT TOTHIS DOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT ISPROVIDED “AS IS,” AND YOU, THE READER, AREASSUMING THE ENTIRE RISK AS TO ITS QUALITYAND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, ORCONSEQUENTIAL DAMAGES RESULTING FROM ANYDEFECT OR INACCURACY IN THIS DOCUMENT, evenif advised of the possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Appledealer, agent, or employee is authorized to makeany modification, extension, or addition to thiswarranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and you may also haveother rights which vary from state to state.

Contents

Introduction Safari DOM Extensions Reference 9

Introduction 9See Also 9

Part I Classes 11

Chapter 1 CSSRule Additions 13

Overview 13Constants 13

Chapter 2 Document Additions 15

Overview 15Tasks 15Methods 15

Chapter 3 DOMApplicationCache 17

Overview 17Tasks 17Properties 18Methods 20Constants 20

Chapter 4 DOMWindow Additions 23

Overview 23Tasks 23Properties 23Methods 24

Chapter 5 GestureEvent 27


32009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

Chapter 6 Touch 33

Overview 33Tasks 33Properties 34

Chapter 7 TouchEvent 37


Chapter 8 TouchList 41


Chapter 9 WebKitAnimationEvent 43


Chapter 10 WebKitCSSKeyframeRule 47


Chapter 11 WebKitCSSKeyframesRule 49


Chapter 12 WebKitCSSMatrix 53



CONTENTS

Chapter 13 WebKitCSSTransformValue 65

Overview 65Tasks 65Properties 65Constants 66

Chapter 14 WebKitPoint 69


Chapter 15 WebKitTransitionEvent 71


Document Revision History 75

Index 77


CONTENTS


CONTENTS

Tables

Chapter 4 DOMWindow Additions 23

Table 4-1 Window orientation values 24



TABLES

Important: This is a preliminary document for an API or technology in development. Although this documenthas been reviewed for technical accuracy, it is not final. Apple is supplying this information to help you planfor the adoption of the technologies and programming interfaces described herein. This information is subjectto change, and software implemented according to this document should be tested with final software andfinal documentation. Newer versions of this document may be provided with future releases of the API ortechnology. For information about updates to this and other developer documentation, view the New &Updated sidebars in subsequent seeds of the Reference Library.

Introduction

This covers miscellaneous WebKit DOM extensions used by Safari on iPhone OS. These extensions includeDOM touch events for processing gestures for devices that have a touch screen and visual effects that support2D and 3D transforms, animation, and transitions. Most of the classes described in this reference are Appleextensions that may also be proposed W3C standards.

See Also

There are a variety of other resources for Safari web content developers using JavaScript.

If you are using DOM touch events, you should also read:

■ Safari Web Content Guide for iPhone OS, which describes how to create web content and applications forSafari on iPhone.

If you are using visual effects, you should read:

■ Safari Visual Effects Guide, which describes how to use the CSS transition, animation, and transformproperties.

If you want to use the JavaScript database classes, you should read:

■ Safari Client-Side Storage andOffline Applications ProgrammingGuide, which describes a simple relationaldatabase that you can use to store persistent data in JavaScript that cannot be stored in cookies.

If you want to use the JavaScript media APIs, then you should read:

■ JavaScript Scripting Guide for QuickTime, which describes how to use JavaScript to query and control theQuickTime plug-in directly.

Introduction 92009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

INTRODUCTION

Safari DOM Extensions Reference

If you want access to the DOM or use the canvas object, then read:

■ WebKitDOMProgrammingTopics, which describes how to use JavaScript in web content for WebKit-basedapplications.

■ WebKit DOM Reference, which describes the API for accessing the WebKit Document Object Model.

If you want to read the WebKit W3C proposals then go to: http://www.webkit.org/specs.

10 See Also2009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

INTRODUCTION

Safari DOM Extensions Reference

http://www.webkit.org/specs


PART I

Classes

Availability Available in iPhone OS 2.0 and later.

Companion guide Safari Visual Effects Guide

Overview

These extensions to the CSSRule class are used to access animation keyframe and keyframes rules.

Constants

DescriptionConstant

Keyframes rule type. Read WebKitCSSKeyframesRule (page 49) for details.const unsigned short WEBKIT_KEYFRAMES_RULE = 7;

Safari Note: In Safari 4.0 and later, the value is 8.

Available in Safari 4.0 and later.Available in iPhone OS 2.0 and later.

WEBKIT_KEYFRAMES_-RULE

Keyframe rule type. Read WebKitCSSKeyframeRule (page 47) for details.const unsigned short WEBKIT_KEYFRAME_RULE = 8;

Safari Note: In Safari 4.0 and later, the value is 9.


WEBKIT_KEYFRAME_RULE

Overview 132009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

CHAPTER 1

CSSRule Additions

14 Constants2009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

CHAPTER 1

CSSRule Additions


Companion guide Safari Web Content Guide for iPhone OS

Overview

These additions to the Document class are used to create touch event objects.

Tasks

Creating Touches

createTouch (page 15)Creates a new Touch object.

createTouchList (page 16)Creates a new TouchList object.

Methods

createTouchCreates a new Touch object.

Touch createTouch(in DOMWindow view, in EventTarget target, in long identifier, in long pageX, in long pageY, in long screenX, in long screenY) raises (

DOMException);

Parametersview

The view (DOM window) in which the event occurred.


CHAPTER 2

Document Additions

targetThe target of this gesture.

identifierThe unique identifier for this touch object.

pageXThe x-coordinate of the touch’s location, in page coordinates.

pageYThe y-coordinate of the touch’s location, in page coordinates.

screenXThe x-coordinate of the event’s location, in screen coordinates.

screenYThe y-coordinate of the event’s location, in screen coordinates.

AvailabilityAvailable in iPhone OS 2.0 and later.

createTouchListCreates a new TouchList object.

TouchList createTouchList() raises ( DOMException);


16 Methods2009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

CHAPTER 2

Document Additions

Availability Available in Safari 4.0 and later.Available in iPhone OS 2.2 and later.


Overview

A DOMApplicationCache object is used to store resources—such as, HTML, JavaScript, CSS, andimages—locally. This allows your web application to continue running offline when there is no networkconnection. The cache persists after Safari exits, so it can be used by multiple browser sessions. There is oneapplication cache per browsing context.

Tasks

Accessing Properties

status (page 19)The current status of the application cache. One of the values described in "Constants.”

Handling Events

onchecking (page 18)Sent when the cache update process begins.

onerror (page 19)Sent when an error occurs.

onnoupdate (page 19)Sent when the update process finishes but the manifest file does not change.

ondownloading (page 18)Sent when the update process begins downloading resources in the manifest file.

onprogress (page 19)Sent when each resource in the manifest file begins to download.

onupdateready (page 19)Sent when there is an existing application cache, the update process finishes, and there is a newapplication cache ready for use.


CHAPTER 3

DOMApplicationCache

oncached (page 18)Sent when the update process finishes for the first time—that is, the first time an application cacheis saved.

Updating the Cache

update (page 20)Manually triggers the update process.

swapCache (page 20)Replaces the active cache with the latest version.

Properties

oncachedSent when the update process finishes for the first time—that is, the first time an application cache is saved.

attribute EventListener oncached;

AvailabilityAvailable in Safari 4.0 and later.Available in iPhone OS 2.2 and later.

oncheckingSent when the cache update process begins.

attribute EventListener onchecking;


ondownloadingSent when the update process begins downloading resources in the manifest file.

attribute EventListener ondownloading;


18 Properties2009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

CHAPTER 3

DOMApplicationCache

onerrorSent when an error occurs.

attribute EventListener onerror;


onnoupdateSent when the update process finishes but the manifest file does not change.

attribute EventListener onnoupdate;


onprogressSent when each resource in the manifest file begins to download.

attribute EventListener onprogress;


onupdatereadySent when there is an existing application cache, the update process finishes, and there is a new applicationcache ready for use.

attribute EventListener onupdateready;


statusThe current status of the application cache. One of the values described in "Constants.”

readonly attribute unsigned short status;


Properties 192009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

CHAPTER 3

DOMApplicationCache

Methods

swapCacheReplaces the active cache with the latest version.

void swapCache() raises(DOMException);


updateManually triggers the update process.

void update() raises(DOMException);


Constants

Constants that indicate the status of the application cache.

DescriptionConstant

The object isn’t associated with an application cache. This can occur if the update process fails and there isno previous cache to revert to, or if there is no manifest file.

const unsigned short UNCACHED = 0;


UNCACHED

The cache is idle.const unsigned short IDLE = 1;


IDLE

The update has started but the resources are not downloaded yet—for example, this can happen when themanifest file is fetched.

const unsigned short CHECKING = 2;


CHECKING


CHAPTER 3

DOMApplicationCache

DescriptionConstant

The resources are being downloaded into the cache.const unsigned short DOWNLOADING = 3;


DOWNLOADING

Resources have finished downloading and the new cache is ready to be used.const unsigned short UPDATEREADY = 4;


UPDATEREADY

Constants 212009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

CHAPTER 3

DOMApplicationCache


CHAPTER 3

DOMApplicationCache

Availability Available in iPhone OS 1.1.1 and later.

Companion guides Safari Web Content Guide for iPhone OSSafari Visual Effects Guide

Overview

DOMWindow additions allow conversion of points from page- and node-coordinate systems for transitions.

Tasks


applicationCache (page 23)The application cache associated with the current document.

orientation (page 24)Specifies the orientation of the device.

Converting Points

webkitConvertPointFromPageToNode (page 25)Converts a point from page coordinates to a given node’s coordinates.

webkitConvertPointFromNodeToPage (page 24)Converts a point from a given node’s coordinates to page coordinates.

Properties

applicationCacheThe application cache associated with the current document.


CHAPTER 4

DOMWindow Additions

readonly attribute DOMApplicationCache applicationCache;


orientationSpecifies the orientation of the device.

readonly attribute long orientation;

DiscussionThis property is set to one of the values in Table 4-1 (page 24). For example, if the user starts with the devicein portrait orientation and then changes to landscape orientation by turning the device to the right, thewindow’s orientation property is set to -90. If the user instead changes to landscape by turning the deviceto the left, the window’s orientation property is set to 90. The default value is 0.

Table 4-1 Window orientation values

DescriptionValue

Portrait orientation. This is the default value.0

Landscape orientation with the screen turned clockwise.-90

Landscape orientation with the screen turned counterclockwise.90

Portrait orientation with the screen turned upside down. This value is currently not supported oniPhone.

180

AvailabilityAvailable in iPhone 1.1.1 and later.

Methods

webkitConvertPointFromNodeToPageConverts a point from a given node’s coordinates to page coordinates.

WebKitPoint webkitConvertPointFromNodeToPage(in Node node, in WebKitPoint p);

Parametersnode

The coordinate space for p.

pA point in node’s coordinates to convert to page coordinates.

Return ValueA point that is at the same location as p but in the page coordinates.


CHAPTER 4

DOMWindow Additions


webkitConvertPointFromPageToNodeConverts a point from page coordinates to a given node’s coordinates.

WebKitPoint webkitConvertPointFromPageToNode(in Node node, in WebKitPoint p);

Parametersnode

The coordinate space to convert the given point to.

pA point in page coordinates to convert to node’s coordinates.

Return ValueA point that is at the same location as p but in the node’s coordinates.


Methods 252009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

CHAPTER 4

DOMWindow Additions


CHAPTER 4

DOMWindow Additions

Inherits from UIEvent



Overview

The GestureEvent class encapsulates information about a multi-touch gesture.

GestureEvent objects are high-level events that encapsulate the low-level TouchEvent objects. BothGestureEvent and TouchEvent events are sent during a multi-touch sequence. Gesture events containscaling and rotation information allowing gestures to be combined, if supported by the platform. If notsupported, one gesture ends before another starts. Listen for GestureEvent events if you want to respondto gestures only, not process the low-level TouchEvent objects.

The different types of GestureEvent objects that can occur are:

gesturestartSent when two or more fingers touch the surface.

gesturechangeSent when fingers are moved during a gesture.

gestureendSent when the gesture ends (when there are 1 or 0 fingers touching the surface).

For example, for a two finger multi-touch gesture, the events occur in the following sequence:

1. touchstart for finger 1. Sent when the first finger touches the surface.

2. gesturestart. Sent when the second finger touches the surface.

3. touchstart for finger 2. Sent immediately after gesturestart when the second finger touches thesurface.

4. gesturechange for current gesture. Sent when both fingers move while still touching the surface.

5. gestureend. Sent when the second finger lifts from the surface.

6. touchend for finger 2. Sent immediately after gestureendwhen the second finger lifts from the surface.

7. touchend for finger 1. Sent when the first finger lifts from the surface.

See TouchEvent (page 37) if you want to process just low-level TouchEvent objects.


CHAPTER 5

GestureEvent

Tasks


altKey (page 28)If true, the alt key is pressed; otherwise, it is not. If there is no keyboard, this value is false.

ctrlKey (page 28)If true, the control key is pressed; otherwise, it is not. If there is no keyboard, this value is false.

metaKey (page 29)If true, the meta key is pressed; otherwise, it is not. If there is no keyboard, this value is false.

rotation (page 29)The delta rotation since the start of an event, in degrees, where clockwise is positive andcounter-clockwise is negative. The initial value is 0.0.

scale (page 29)The distance between two fingers since the start of an event, as a multiplier of the initial distance.The initial value is 1.0. If less than 1.0, the gesture is pinch close (to zoom out). If greater than 1.0,the gesture is pinch open (to zoom in).

shiftKey (page 29)If true, the Shift key is pressed; otherwise, it is not. If there is no keyboard, this value is false.

target (page 29)The target of this gesture.

Initializing

initGestureEvent (page 30)Initializes a newly created GestureEvent object.

Properties

altKeyIf true, the alt key is pressed; otherwise, it is not. If there is no keyboard, this value is false.

readonly attribute boolean altKey;


ctrlKeyIf true, the control key is pressed; otherwise, it is not. If there is no keyboard, this value is false.

28 Tasks2009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

CHAPTER 5

GestureEvent

readonly attribute boolean ctrlKey;


metaKeyIf true, the meta key is pressed; otherwise, it is not. If there is no keyboard, this value is false.

readonly attribute boolean metaKey;


rotationThe delta rotation since the start of an event, in degrees, where clockwise is positive and counter-clockwiseis negative. The initial value is 0.0.

readonly attribute float rotation;


scaleThe distance between two fingers since the start of an event, as a multiplier of the initial distance. The initialvalue is 1.0. If less than 1.0, the gesture is pinch close (to zoom out). If greater than 1.0, the gesture is pinchopen (to zoom in).

readonly attribute float scale;


shiftKeyIf true, the Shift key is pressed; otherwise, it is not. If there is no keyboard, this value is false.

readonly attribute boolean shiftKey;




CHAPTER 5

GestureEvent

readonly attribute EventTarget target;


Methods

initGestureEventInitializes a newly created GestureEvent object.

void initGestureEvent(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 EventTarget target, in float scale, in float rotation);

Parameterstype

The type of event that occurred.

canBubbleIndicates whether an event can bubble. If true, the event can bubble; otherwise, it cannot.

cancelableIndicates whether an event can have its default action prevented. If true, the default action can beprevented; otherwise, it cannot.

viewThe view (DOM window) where the event occurred.

detailSpecifies some detail information about the event depending on the type of event.

screenXThe x-coordinate of the event’s location in screen coordinates.

screenYThe y-coordinate of the event’s location in screen coordinates.

clientXThe x-coordinate of the event’s location relative to the window's viewport.


CHAPTER 5

GestureEvent

clientYThe y-coordinate of the event’s location relative to the window's viewport.

ctrlKeyIf true, the control key is pressed; otherwise, it is not.

altKeyIf true, the alt key is pressed; otherwise, it is not.

shiftKeyIf true, the Shift key is pressed; otherwise, it is not.

metaKeyIf true, the meta key is pressed; otherwise, it is not.


scaleThe distance between two fingers since the start of an event as a multiplier of the initial distance. Theinitial value is 1.0. If less than 1.0, the gesture is pinch close (to zoom out). If greater than 1.0, thegesture is pinch open (to zoom in).

rotationThe delta rotation since the start of an event, in degrees, where clockwise is positive andcounter-clockwise is negative. The initial value is 0.0.

DiscussionUse this method to programmatically create a GestureEvent object.



CHAPTER 5

GestureEvent


CHAPTER 5

GestureEvent



Overview

The Touch class represents a single touch on the surface. A touch is the presence or movement of a fingerthat is part of a unique multi-touch sequence.

Tasks


clientX (page 34)The x-coordinate of the touch’s location relative to the window’s viewport.

clientY (page 34)The y-coordinate of the touch’s location relative to the window’s viewport.

identifier (page 34)The unique identifier for this touch object.

pageX (page 34)The x-coordinate of the touch’s location in page coordinates.

pageY (page 34)The y-coordinate of the touch’s location in page coordinates.

screenX (page 35)The x-coordinate of the touch’s location in screen coordinates.

screenY (page 35)The y-coordinate of the touch’s location in screen coordinates.

target (page 35)The target of this touch.


CHAPTER 6

Touch

Properties

clientXThe x-coordinate of the touch’s location relative to the window’s viewport.

readonly attribute long clientX;


clientYThe y-coordinate of the touch’s location relative to the window’s viewport.

readonly attribute long clientY;


identifierThe unique identifier for this touch object.

readonly attribute unsigned long identifier;


pageXThe x-coordinate of the touch’s location in page coordinates.

readonly attribute long pageX;


pageYThe y-coordinate of the touch’s location in page coordinates.

readonly attribute long pageY;



CHAPTER 6

Touch

screenXThe x-coordinate of the touch’s location in screen coordinates.

readonly attribute long screenX;


screenYThe y-coordinate of the touch’s location in screen coordinates.

readonly attribute long screenY;


targetThe target of this touch.

readonly attribute EventTarget target;



CHAPTER 6

Touch


CHAPTER 6

Touch

Inherits from UIEvent



Overview

The TouchEvent class encapsulates information about a touch event.

The system continually sends TouchEvent objects to an application as fingers touch and move across asurface. A touch event provides a snapshot of all touches during a multi-touch sequence, most importantlythe touches that are new or have changed for a particular target. A multi-touch sequence begins when afinger first touches the surface. Other fingers may subsequently touch the surface, and all fingers may moveacross the surface. The sequence ends when the last of these fingers is lifted from the surface. An applicationreceives touch event objects during each phase of any touch.

The different types of TouchEvent objects that can occur are:

touchstartSent when a finger for a given event touches the surface.

touchmoveSent when a given event moves on the surface.

touchendSent when a given event lifts from the surface.

touchcancelSent when the system cancels tracking for the touch.

TouchEvent objects are combined together to form high-level GestureEvent objects that are also sentduring a multi-touch sequence. See GestureEvent (page 27) for details on GestureEvent objects and anexample of the events sent for a two finger multi-touch gesture.

Tasks


altKey (page 38)If true, the alt key is pressed; otherwise, it is not. If there is no keyboard, this value is false.


CHAPTER 7

TouchEvent

changedTouches (page 38)A collection of Touch objects representing all touches that changed in this event.

Initializing

initTouchEvent (page 38)Initializes a newly created TouchEvent object.

Properties

altKeyIf true, the alt key is pressed; otherwise, it is not. If there is no keyboard, this value is false.

readonly attribute boolean altKey;


changedTouchesA collection of Touch objects representing all touches that changed in this event.

readonly attribute TouchList changedTouches;


Methods

initTouchEventInitializes a newly created TouchEvent object.


CHAPTER 7

TouchEvent

void initTouchEvent(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 TouchList touches, in TouchList targetTouches, in TouchList changedTouches, in float scale, in float rotation);

Parameterstype

The type of event that occurred.

canBubbleIndicates whether an event can bubble. If true, the event can bubble; otherwise, it cannot.

cancelableIndicates whether an event can have its default action prevented. If true, the default action can beprevented; otherwise, it cannot.

viewThe view (DOM window) in which the event occurred.

detailSpecifies some detail information about the event depending on the type of event.

screenXThe x-coordinate of the event’s location in screen coordinates.

screenYThe y-coordinate of the event’s location in screen coordinates.

clientXThe x-coordinate of the event’s location relative to the window’s viewport.

clientYThe y-coordinate of the event’s location relative to the window’s viewport.

ctrlKeyIf true, the control key is pressed; otherwise, it is not.

altKeyIf true, the alt key is pressed; otherwise, it is not.

shiftKeyIf true, the shift key is pressed; otherwise, it is not.

metaKeyIf true, the meta key is pressed; otherwise, it is not.


CHAPTER 7

TouchEvent

touchesA collection of Touch objects representing all touches associated with this event.

targetTouchesA collection of Touch objects representing all touches associated with this target.

changedTouchesA collection of Touch objects representing all touches that changed in this event.

scaleThe distance between two fingers since the start of an event as a multiplier of the initial distance. Theinitial value is 1.0. If less than 1.0, the gesture is pinch close (to zoom out). If greater than 1.0, thegesture is pinch open (to zoom in).

rotationThe delta rotation since the start of an event, in degrees, where clockwise is positive andcounter-clockwise is negative. The initial value is 0.0.

DiscussionUse this method to programmatically create a TouchEvent object.



CHAPTER 7

TouchEvent



Overview

The TouchList class is used to represent a collection of Touch objects.

Tasks


length (page 41)The number of Touch objects in this TouchList object.

Getting Touch Objects

item (page 42)Returns the Touch object at the given index.

Properties

lengthThe number of Touch objects in this TouchList object.

readonly attribute unsigned long length;



CHAPTER 8

TouchList

Methods

itemReturns the Touch object at the given index.

Touch item(in unsigned long index);

Parametersindex

The index of the item to return.



CHAPTER 8

TouchList

Inherits from Event



Overview

WebKitAnimationEvent objects encapsulate information about running animations.

Several animation related events are available through the DOM Event system. The start and end of ananimation, and the end of each iteration of an animation all generate DOM events. An element can havemultiple properties that are animated simultaneously. This simultaneous animation can occur either by settinga single -webkit-animation-name value with keyframes containing multiple properties, or by settingmultiple -webkit-animation-name values. For the purposes of event dispatching, each CSS-webkit-animation-name property specifies a single animation. Therefore, an event is sent for each-webkit-animation-name property, not necessarily for each CSS property that is animated.

Each event contains the duration of the animation. This allows the event handler to determine the currentiteration of a looping animation or the current position of an alternating animation. This duration does notinclude time the animation was in the paused play state.

Types of Animation Events

The type property of an animation event can have the following string values:

webkitAnimationStartOccurs at the start of an animation. It can bubble and be canceled. Its animationName property isset.

webkitAnimationEndOccurs when the animation finishes. It can bubble and be canceled. Its animationName andelapsedTime properties are set.

webkitAnimationIterationOccurs at the end of each iteration of an animation when the-webkit-animation-iteration-count is greater than 1. It does not occur for animations withan iteration count of 1. It can bubble and be canceled. Its animationName and elapsedTimeproperties are set.


CHAPTER 9

WebKitAnimationEvent

Tasks


animationName (page 44)The name of the animation. The value of the CSS -webkit-animation-name property of theanimation that caused the event.

elapsedTime (page 44)The duration of the animation, in seconds, since this event was sent, excluding any time the animationis paused. This value is not affected by the value of the CSS -webkit-animation-delay property.If the type of the event is webkitAnimationStart, elapsedTime is 0.

Initializing Objects

initWebKitAnimationEvent (page 45)Initializes a new animation event object.

Properties

animationNameThe name of the animation. The value of the CSS -webkit-animation-name property of the animationthat caused the event.

readonly attribute DOMString animationName;


elapsedTimeThe duration of the animation, in seconds, since this event was sent, excluding any time the animation ispaused. This value is not affected by the value of the CSS -webkit-animation-delay property. If the typeof the event is webkitAnimationStart, elapsedTime is 0.

readonly attribute double elapsedTime;



CHAPTER 9


Methods

initWebKitAnimationEventInitializes a new animation event object.

voidinitWebKitAnimationEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString animationNameArg, in double elapsedTimeArg);

ParameterstypeArg

The type of event. See “Types of Animation Events” (page 43) for possible values.

canBubbleArgDetermines whether the event can bubble. Pass true if it can bubble; otherwise, false.

cancelableArgDetermines whether the event’s default action can be prevented. Pass true if it can be prevented;otherwise, false.

animationNameArgThe name of the animation associated with this event.

elapsedTimeArgThe duration of the animation, in seconds, since the event was sent.

DiscussionYou use this method to initialize the value of a WebKitTransitionEvent object that is created throughthe DocumentEvent interface. This method can only be invoked before the WebKitTransitionEventobject is dispatched via the dispatchEvent method (although it can be invoked multiple times during thatphase, if necessary). If it is invoked multiple times, the final invocation takes precedence.



CHAPTER 9



CHAPTER 9


Inherits from CSSRule



Overview

WebKitCSSKeyframeRule objects represent the style rule for a single keyframe in the @-webkit-keyframesCSS rule.

Tasks


keyText (page 47)A keyframe selector.

style (page 48)The style associated with this keyframe.

Properties

keyTextA keyframe selector.

attribute DOMString keyText;

DiscussionA keyframe selector represented as a percentage value or the keyword from or to. The selector is used tospecify the percentage along the duration of the animation. The keyframe is specified by the block of propertyvalues declared for the selector. The keyword from is equivalent to 0 percent and to is equivalent to 100percent.


CHAPTER 10

WebKitCSSKeyframeRule


styleThe style associated with this keyframe.

readonly attribute CSSStyleDeclaration style;



CHAPTER 10

WebKitCSSKeyframeRule

Inherits from CSSRule



Overview

WebKitCSSKeyframesRule objects represent the keyframes for a single animation, that is, the contents ofan @-webkit-keyframes CSS rule.

Tasks


name (page 50)The name of the target animation that is set using the -webkit-animation-name property.

cssRules (page 50)The set of style rules that define the keyframes following the animation name.

Changing Rules

insertRule (page 51)Adds a keyframe rule to the collection of keyframes.

deleteRule (page 50)Removes a keyframe rule from the collection of keyframes.

findRule (page 50)Returns the keyframe rule for the specified selector.


CHAPTER 11

WebKitCSSKeyframesRule

Properties

cssRulesThe set of style rules that define the keyframes following the animation name.

readonly attribute CSSRuleList cssRules;


nameThe name of the target animation that is set using the -webkit-animation-name property.

attribute DOMString name;


Methods

deleteRuleRemoves a keyframe rule from the collection of keyframes.

void deleteRule(in DOMString key);

Parameterskey

A selector for the rule that is either a percentage or the keyword from or to.


findRuleReturns the keyframe rule for the specified selector.

WebKitCSSKeyframeRule findRule(in DOMString key);

Parameterskey

A selector for the rule that is either a percentage or the keyword from or to.


CHAPTER 11


Return ValueReturns the keyframe rule corresponding to the given selector if it exists.


insertRuleAdds a keyframe rule to the collection of keyframes.

void insertRule(in DOMString rule);

Parametersrule

A string representing a selector and keyframe, where the selector is a percentage or keyword and thekeyframe is a block. The string must follow the format for keyframe blocks in the @-webkit-keyframesCSS rule.



CHAPTER 11



CHAPTER 11




Overview

WebKitCSSMatrix objects represent a 4x4 homogeneous matrix for 3D transforms or a vector for 2Dtransforms. You can use these objects to manipulate matrices in JavaScript. For example, you can multiply,translate, and scale matrices.

The values of a 3D matrix can be initialized from the matrix3d() string returned bywindow.getComputedStyle(element).webkitTransform(). To apply the final matrix to an element,construct a matrix3d() string using the 16 values, and assign it to element.style.webkitTransform.Similarly, you can construct a matrix for 2D transforms by setting 6 values, represented by the a-f properties.

Tasks


a (page 55)The first 2D vector value.

b (page 55)The second 2D vector value.

c (page 55)The third 2D vector value.

d (page 56)The fourth 2D vector value.

e (page 56)The fifth 2D vector value.

f (page 56)The sixth 2D vector value.

m11 (page 56)The 3D matrix value in the first row and first column.


CHAPTER 12

WebKitCSSMatrix

m12 (page 56)The 3D matrix value in the first row and second column.

m13 (page 57)The 3D matrix value in the first row and third column.

m14 (page 57)The 3D matrix value in the first row and fourth column.

m21 (page 57)The 3D matrix value in the second row and first column.

m22 (page 57)The 3D matrix value in the second row and second column.

m23 (page 58)The 3D matrix value in the second row and third column.

m24 (page 58)The 3D matrix value in the second row and fourth column.

m31 (page 58)The 3D matrix value in the third row and first column.

m32 (page 58)The 3D matrix value in the third row and second column.

m33 (page 59)The 3D matrix value in the third row and third column.

m34 (page 59)The 3D matrix value in the third row and fourth column.

m41 (page 59)The 3D matrix value in the fourth row and first column.

m42 (page 59)The 3D matrix value in the fourth row and second column.

m43 (page 60)The 3D matrix value in the fourth row and third column.

m44 (page 60)The 3D matrix value in the fourth row and fourth column.

Setting the Matrix

setMatrixValue (page 62)Sets the matrix values using a string representation.

Applying Operations

multiply (page 61)Returns the result of multiplying this matrix by a given matrix that is on the right.

inverse (page 60)Returns the inverse of this matrix.


CHAPTER 12

WebKitCSSMatrix

translate (page 63)Returns the result of translating this matrix by a given vector.

scale (page 62)Returns the result of scaling this matrix by a given vector.

rotate (page 61)Returns the result of rotating this matrix by a given vector.

rotateAxisAngle (page 61)Returns the result of rotating this matrix by a given vector and angle.

Converting the Matrix

toString (page 63)Returns a string representation of the matrix.

Properties

aThe first 2D vector value.

attribute float a;

AvailabilityAvailable in Safari 4.0 and later.

bThe second 2D vector value.

attribute float b;


cThe third 2D vector value.

attribute float c;



CHAPTER 12

WebKitCSSMatrix

dThe fourth 2D vector value.

attribute float d;


eThe fifth 2D vector value.

attribute float e;


fThe sixth 2D vector value.

attribute float f;


m11The 3D matrix value in the first row and first column.

attribute float m11;

DiscussionOne of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first rowand the second column.


m12The 3D matrix value in the first row and second column.




CHAPTER 12

WebKitCSSMatrix


m13The 3D matrix value in the first row and third column.




m14The 3D matrix value in the first row and fourth column.




m21The 3D matrix value in the second row and first column.




m22The 3D matrix value in the second row and second column.




CHAPTER 12

WebKitCSSMatrix


m23The 3D matrix value in the second row and third column.




m24The 3D matrix value in the second row and fourth column.




m31The 3D matrix value in the third row and first column.




m32The 3D matrix value in the third row and second column.




CHAPTER 12

WebKitCSSMatrix


m33The 3D matrix value in the third row and third column.




m34The 3D matrix value in the third row and fourth column.




m41The 3D matrix value in the fourth row and first column.




m42The 3D matrix value in the fourth row and second column.




CHAPTER 12

WebKitCSSMatrix


m43The 3D matrix value in the fourth row and third column.




m44The 3D matrix value in the fourth row and fourth column.




Methods

inverseReturns the inverse of this matrix.

WebKitCSSMatrix inverse() raises CSSException;

Return ValueA new matrix that is the inverse of this matrix.

DiscussionThis matrix is not modified by this method.



CHAPTER 12

WebKitCSSMatrix

multiplyReturns the result of multiplying this matrix by a given matrix that is on the right.

WebKitCSSMatrix multiply(in WebKitCSSMatrix secondMatrix) raises CSSException;

ParameterssecondMatrix

The matrix to multiply.

Return ValueA new matrix that is the result of multiplying this matrix by the given matrix.

DiscussionThe given matrix is on the right of the multiplication. This matrix is not modified by this method.


rotateReturns the result of rotating this matrix by a given vector.

WebKitCSSMatrix rotate(in float rotX, in float rotY, in float rotZ);

ParametersrotX

The x component in the vector, in degrees.

rotYThe y component in the vector, in degrees. If undefined, the x component is used.

rotZThe z component in the vector, in degrees. If undefined, the x component is used.

Return ValueA new matrix that is the result of rotating this matrix by each of the three rotation matrices about the majoraxes, first the x axes, y axes, and then z axes.



rotateAxisAngleReturns the result of rotating this matrix by a given vector and angle.

WebKitCSSMatrix rotateAxisAngle(in float x, in float y, in float z, in float angle);


CHAPTER 12

WebKitCSSMatrix

Parametersx

The x component in the vector, in degrees.

yThe y component in the vector, in degrees. If undefined, the x component is used.

zThe z component in the vector, in degrees. If undefined, the x component is used.

angleThe angle of rotation about the axis vector, in degrees.

Return ValueA new matrix that is the result of rotating this matrix by each of the three rotation matrices about the majoraxes and angle. The right-hand rule is used to determine the direction of rotation.



scaleReturns the result of scaling this matrix by a given vector.

WebKitCSSMatrix scale(in float scaleX, in float scaleY, in float scaleZ);

ParametersscaleX

The x component in the vector.

scaleYThe y component in the vector. If undefined, the x component is used.

scaleZThe z component in the vector. If undefined, 1 is used.

Return ValueA new matrix that is the result of scaling this matrix.



setMatrixValueSets the matrix values using a string representation.

void setMatrixValue(in DOMString string);


CHAPTER 12

WebKitCSSMatrix

Parametersstring

A matrix3d() string—typically returned bywindow.getComputedStyle(element).webkitTransform().


toStringReturns a string representation of the matrix.

DOMString toString();

Return ValueA string representation of the matrix’s values.


translateReturns the result of translating this matrix by a given vector.

WebKitCSSMatrix translate(in float x, in float y, in float z);

Parametersx

The x component in the vector.

yThe y component in the vector.

zThe z component in the vector. If undefined, 0 is used.

Return ValueA new matrix that is the result of translating this matrix.




CHAPTER 12

WebKitCSSMatrix


CHAPTER 12

WebKitCSSMatrix

Inherits from CSSValueList



Overview

WebKitCSSTransformValue objects represent one transform function in a CSS transform property. TheoperationType property in this class specifies which function is used. The objects also contain a list ofvalues which are the parameters to the function. The parameters appear in the same order as they appearin the function.

Tasks


operationType (page 65)The transform function used. Possible values are described in CSS_MATRIX (page 66).

Properties

operationTypeThe transform function used. Possible values are described in CSS_MATRIX (page 66).

readonly attribute unsigned short operationType;



CHAPTER 13

WebKitCSSTransformValue

Constants

DescriptionConstant

Specifies the matrix() transform function.const unsigned short CSS_MATRIX = 1;


CSS_MATRIX

Specifies the matrix3d() transform function.const unsigned short CSS_MATRIX3D = 2;

Available in iPhone OS 2.0 and later.

CSS_MATRIX3D

Specifies the perspective() transform function.const unsigned short CSS_PERSPECTIVE = 12;


CSS_PERSPECTIVE

Specifies the rotate() transform function.const unsigned short CSS_ROTATE = 3;


CSS_ROTATE

Specifies the rotate3d() transform function.const unsigned short CSS_ROTATE3D = 4;


CSS_ROTATE3D

Specifies the rotateX() transform function.const unsigned short CSS_ROTATEX = 13;


CSS_ROTATEX

Specifies the rotateY() transform function.const unsigned short CSS_ROTATEY = 14;


CSS_ROTATEY

Specifies the rotateZ() transform transform function.const unsigned short CSS_ROTATEZ = 15;


CSS_ROTATEZ

Specifies the scale() transform function.const unsigned short CSS_SCALE = 7;


CSS_SCALE


CHAPTER 13


DescriptionConstant

Specifies the scale3d() transform function.const unsigned short CSS_SCALE3D = 8;


CSS_SCALE3D

Specifies the scaleX() transform function.const unsigned short CSS_SCALEX = 19;


CSS_SCALEX

Specifies the scaleY() transform function.const unsigned short CSS_SCALEY = 20;


CSS_SCALEY

Specifies the scaleZ() transform function.const unsigned short CSS_SCALEZ = 21;


CSS_SCALEZ

Specifies the skew() transform function.const unsigned short CSS_SKEW = 8;

Available in Safari 4.0 and later.

CSS_SKEW

Specifies the skewX() transform function.const unsigned short CSS_SKEWX = 9;


CSS_SKEWX

Specifies the skewY() transform function.const unsigned short CSS_SKEWY = 10;


CSS_SKEWY

Specifies the translate() transform function.const unsigned short CSS_TRANSLATE = 5;


CSS_TRANSLATE

Specifies the translate3d() transform function.const unsigned short CSS_TRANSLATE3D = 6;


CSS_TRANSLATE3D

Constants 672009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.

CHAPTER 13


DescriptionConstant

Specifies the translateX() transform function.const unsigned short CSS_TRANSLATEX = 16;


CSS_TRANSLATEX

Specifies the translateY() transform function.const unsigned short CSS_TRANSLATEY = 17;


CSS_TRANSLATEY

Specifies the translateZ() transform function.const unsigned short CSS_TRANSLATEZ = 18;


CSS_TRANSLATEZ

An unknown function.const unsigned short CSS_UNKNOWN = 0;


CSS_UNKNOWN


CHAPTER 13




Overview

WebKitPoint objects represent a point in two-dimensional space used by transitions.

Tasks


x (page 69)The x coordinate for the point.

y (page 69)The y coordinate for the point.

Properties

xThe x coordinate for the point.

attribute float x;


yThe y coordinate for the point.


CHAPTER 14

WebKitPoint

attribute float y;



CHAPTER 14

WebKitPoint

Inherits from Event



Overview

WebKitTransitionEvent objects provide information about CSS transitions. An event is sent at the endof a transition for each CSS property in the transition. Each event contains the name of the CSS property andduration of the transition. You can use these events to perform some action that starts at the end of atransition.

Types of Transition Events

The only possible string value for a transition event’s type property is:

webKitTransitionEndSent when a transition completes.

Tasks


propertyName (page 72)The name of the CSS property associated with the transition.

elapsedTime (page 72)The duration of the transition, in seconds, since this event was sent. This value is not affected by thevalue of the CSS -webkit-transition-delay property.


CHAPTER 15

WebKitTransitionEvent

Initializing

initWebKitTransitionEvent (page 72)Initializes a new transition event object.

Properties

elapsedTimeThe duration of the transition, in seconds, since this event was sent. This value is not affected by the valueof the CSS -webkit-transition-delay property.

readonly attribute double elapsedTime;


propertyNameThe name of the CSS property associated with the transition.

readonly attribute DOMString propertyName;


Methods

initWebKitTransitionEventInitializes a new transition event object.

void initWebKitTransitionEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString propertyNameArg, in double elapsedTimeArg);

ParameterstypeArg

The type of event.

Possible values for this argument are described in “Types of Transition Events” (page 71). This typeof event can bubble and be canceled. Its propertyName property is always set.

canBubbleArgDetermines whether the event can bubble. Pass true if it can bubble; otherwise, false.


CHAPTER 15


cancelableArgDetermines whether the event’s default action can be prevented. Pass true if it can be prevented;otherwise, false.

propertyNameArgThe name of the CSS property associated with this event.

elapsedTimeArgThe duration of the transition, in seconds, since the event was sent.

DiscussionYou use this method to initialize the value of a WebKitTransitionEvent object that is created throughthe DocumentEvent interface. This method can only be invoked before the WebKitTransitionEventobject is dispatched via the dispatchEvent method (although, it can be invoked multiple times duringthat phase, if necessary). If it is invoked multiple times, the final invocation takes precedence.



CHAPTER 15



CHAPTER 15


This table describes the changes to Safari DOM Extensions Reference.

NotesDate

Updated per Safari 4.0 changes.2009-01-30

Added the DOMApplicationCache class.2008-11-21

Changed the title from "Safari DOM Touch Reference for iPhone OS" and addedvisual effects reference.

2008-10-15

Revised document that describes Safari on iPhone-only JavaScript functionsand properties.

2008-07-11


REVISION HISTORY

Document Revision History


REVISION HISTORY

Document Revision History

A

a property 55altKey property 28, 38animationName property 44applicationCache property 23

B

b property 55

C

c property 55changedTouches property 38CHECKING constant 20clientX property 34clientY property 34createTouch method 15createTouchList method 16cssRules property 50CSS_MATRIX constant 66CSS_MATRIX3D constant 66CSS_PERSPECTIVE constant 66CSS_ROTATE constant 66CSS_ROTATE3D constant 66CSS_ROTATEX constant 66CSS_ROTATEY constant 66CSS_ROTATEZ constant 66CSS_SCALE constant 66CSS_SCALE3D constant 67CSS_SCALEX constant 67CSS_SCALEY constant 67CSS_SCALEZ constant 67CSS_SKEW constant 67CSS_SKEWX constant 67CSS_SKEWY constant 67CSS_TRANSLATE constant 67

CSS_TRANSLATE3D constant 67CSS_TRANSLATEX constant 68CSS_TRANSLATEY constant 68CSS_TRANSLATEZ constant 68CSS_UNKNOWN constant 68ctrlKey property 28

D

d property 56deleteRule method 50DOWNLOADING constant 21

E

e property 56elapsedTime property 44, 72

F

f property 56findRule method 50

I

identifier property 34IDLE constant 20initGestureEvent method 30initTouchEvent method 38initWebKitAnimationEvent method 45initWebKitTransitionEvent method 72insertRule method 51inverse method 60item method 42


Index

K

keyText property 47

L

length property 41

M

m11 property 56m12 property 56m13 property 57m14 property 57m21 property 57m22 property 57m23 property 58m24 property 58m31 property 58m32 property 58m33 property 59m34 property 59m41 property 59m42 property 59m43 property 60m44 property 60metaKey property 29multiply method 61

N

name property 50

O

oncached property 18onchecking property 18ondownloading property 18onerror property 19onnoupdate property 19onprogress property 19onupdateready property 19operationType property 65orientation property 24

P

pageX property 34pageY property 34propertyName property 72

R

rotate method 61rotateAxisAngle method 61rotation property 29

S

scale method 62scale property 29screenX property 35screenY property 35setMatrixValue method 62shiftKey property 29status property 19style property 48swapCache method 20

T

target property 29, 35toString method 63translate method 63

U

UNCACHED constant 20update method 20UPDATEREADY constant 21

W

webkitConvertPointFromNodeToPage method 24webkitConvertPointFromPageToNode method 25WEBKIT_KEYFRAMES_RULE constant 13WEBKIT_KEYFRAME_RULE constant 13


INDEX

X

x property 69

Y

y property 69


INDEX

Safari DOM Extensions Reference

Documents

Transcript of Safari DOM Extensions Reference