Issuu on Google+

Safari DOM Extensions Reference User 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, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple’s copyright notice. The Apple logo is a trademark of Apple Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial purposes without the prior written consent of Apple may constitute trademark infringement and unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, QuickTime, and Safari are trademarks of Apple Inc., registered in the United States and other countries. iPhone is a trademark of Apple Inc. Java and all Java-based trademarks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. SPEC is a registered trademark of the Standard Performance Evaluation Corporation (SPEC). Simultaneously published in the United States and Canada. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION,

EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.


Contents Introduction

Safari DOM Extensions Reference 9 Introduction 9 See Also 9

Part I

Classes 11

Chapter 1

CSSRule Additions 13 Overview 13 Constants 13

Chapter 2

Document Additions 15 Overview 15 Tasks 15 Methods 15

Chapter 3

DOMApplicationCache 17 Overview 17 Tasks 17 Properties 18 Methods 20 Constants 20

Chapter 4

DOMWindow Additions 23 Overview 23 Tasks 23 Properties 23 Methods 24

Chapter 5

GestureEvent 27 Overview 27 Tasks 28 Properties 28 Methods 30

3 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


CONTENTS

Chapter 6

Touch 33 Overview 33 Tasks 33 Properties 34

Chapter 7

TouchEvent 37 Overview 37 Tasks 37 Properties 38 Methods 38

Chapter 8

TouchList 41 Overview 41 Tasks 41 Properties 41 Methods 42

Chapter 9

WebKitAnimationEvent 43 Overview 43 Tasks 44 Properties 44 Methods 45

Chapter 10

WebKitCSSKeyframeRule 47 Overview 47 Tasks 47 Properties 47

Chapter 11

WebKitCSSKeyframesRule 49 Overview 49 Tasks 49 Properties 50 Methods 50

Chapter 12

WebKitCSSMatrix 53 Overview 53 Tasks 53 Properties 55 Methods 60

4 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


CONTENTS

Chapter 13

WebKitCSSTransformValue 65 Overview 65 Tasks 65 Properties 65 Constants 66

Chapter 14

WebKitPoint 69 Overview 69 Tasks 69 Properties 69

Chapter 15

WebKitTransitionEvent 71 Overview 71 Tasks 71 Properties 72 Methods 72

Document Revision History 75 Index 77

5 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


CONTENTS

6 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


Tables Chapter 4

DOMWindow Additions 23 Table 4-1

Window orientation values 24

7 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


TABLES

8 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


INTRODUCTION

Safari DOM Extensions Reference

Important: This is a preliminary document for an API or technology in development. Although this document has been reviewed for technical accuracy, it is not final. Apple is supplying this information to help you plan for the adoption of the technologies and programming interfaces described herein. This information is subject to change, and software implemented according to this document should be tested with final software and final documentation. Newer versions of this document may be provided with future releases of the API or technology. 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 include DOM touch events for processing gestures for devices that have a touch screen and visual effects that support 2D and 3D transforms, animation, and transitions. Most of the classes described in this reference are Apple extensions 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 for Safari 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 transform properties.

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

Safari Client-Side Storage and Offline Applications Programming Guide, which describes a simple relational database 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 the QuickTime plug-in directly.

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

9


INTRODUCTION

Safari DOM Extensions Reference

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

WebKit DOM Programming Topics, which describes how to use JavaScript in web content for WebKit-based applications.

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 Also 2009-01-30 | © 2004, 2009 Apple Inc. All Rights Reserved.


PART I

Classes

11 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


PART I

Classes

12 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


CHAPTER 1

CSSRule Additions

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 Constant

Description

WEBKIT_KEYFRAMES_RULE

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_KEYFRAME_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. Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

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

13


CHAPTER 1

CSSRule Additions

14

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


CHAPTER 2

Document Additions

Availability

Available in iPhone OS 2.0 and later.

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 createTouch Creates 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);

Parameters view

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

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

15


CHAPTER 2

Document Additions

target

The target of this gesture. identifier

The unique identifier for this touch object. pageX

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

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

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

The y-coordinate of the event’s location, in screen coordinates. Availability Available in iPhone OS 2.0 and later.

createTouchList Creates a new TouchList object. TouchList createTouchList() raises ( DOMException);

Availability Available in iPhone OS 2.0 and later.

16

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


CHAPTER 3

DOMApplicationCache

Availability

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

Companion guide

Safari Web Content Guide for iPhone OS

Overview A DOMApplicationCache object is used to store resources—such as, HTML, JavaScript, CSS, and images—locally. This allows your web application to continue running offline when there is no network connection. The cache persists after Safari exits, so it can be used by multiple browser sessions. There is one application 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 new application cache ready for use.

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

17


CHAPTER 3

DOMApplicationCache

oncached (page 18)

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

Updating the Cache update (page 20)

Manually triggers the update process. swapCache (page 20)

Replaces the active cache with the latest version.

Properties oncached Sent when the update process finishes for the first time—that is, the first time an application cache is saved. attribute EventListener oncached;

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

onchecking Sent when the cache update process begins. attribute EventListener onchecking;

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

ondownloading Sent when the update process begins downloading resources in the manifest file. attribute EventListener ondownloading;

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

18

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


CHAPTER 3

DOMApplicationCache

onerror Sent when an error occurs. attribute EventListener onerror;

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

onnoupdate Sent when the update process finishes but the manifest file does not change. attribute EventListener onnoupdate;

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

onprogress Sent when each resource in the manifest file begins to download. attribute EventListener onprogress;

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

onupdateready Sent when there is an existing application cache, the update process finishes, and there is a new application cache ready for use. attribute EventListener onupdateready;

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

status The current status of the application cache. One of the values described in "Constants.� readonly attribute unsigned short status;

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

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

19


CHAPTER 3

DOMApplicationCache

Methods swapCache Replaces the active cache with the latest version. void swapCache() raises(DOMException);

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

update Manually triggers the update process. void update() raises(DOMException);

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

Constants Constants that indicate the status of the application cache. Constant

Description

UNCACHED

The object isn’t associated with an application cache. This can occur if the update process fails and there no previous cache to revert to, or if there is no manifest file. const unsigned short UNCACHED = 0;

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

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

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

The update has started but the resources are not downloaded yet—for example, this can happen when th manifest file is fetched. const unsigned short CHECKING = 2;

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

20

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


CHAPTER 3

DOMApplicationCache

Constant

Description

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

Available in Safari 4.0 and later. Available in iPhone OS 2.2 and later. UPDATEREADY Resources have finished downloading and the new cache is ready to be used. const unsigned short UPDATEREADY = 4;

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

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

21


CHAPTER 3

DOMApplicationCache

22

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


CHAPTER 4

DOMWindow Additions

Availability

Available in iPhone OS 1.1.1 and later.

Companion guides

Safari Web Content Guide for iPhone OS Safari Visual Effects Guide

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

Tasks Accessing Properties 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 applicationCache The application cache associated with the current document.

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

23


CHAPTER 4

DOMWindow Additions

readonly attribute DOMApplicationCache applicationCache;

Availability Available in iPhone OS 2.2 and later.

orientation Specifies the orientation of the device. readonly attribute long orientation;

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

Window orientation values

Value Description 0

Portrait orientation. This is the default value.

-90

Landscape orientation with the screen turned clockwise.

90

Landscape orientation with the screen turned counterclockwise.

180

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

Availability Available in iPhone 1.1.1 and later.

Methods webkitConvertPointFromNodeToPage Converts a point from a given node’s coordinates to page coordinates. WebKitPoint webkitConvertPointFromNodeToPage(in Node node, in WebKitPoint p);

Parameters node

The coordinate space for p. p

A point in node’s coordinates to convert to page coordinates. Return Value A point that is at the same location as p but in the page coordinates.

24

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


CHAPTER 4

DOMWindow Additions

Availability Available in iPhone OS 2.0 and later.

webkitConvertPointFromPageToNode Converts a point from page coordinates to a given node’s coordinates. WebKitPoint webkitConvertPointFromPageToNode(in Node node, in WebKitPoint p);

Parameters node

The coordinate space to convert the given point to. p

A point in page coordinates to convert to node’s coordinates. Return Value A point that is at the same location as p but in the node’s coordinates. Availability Available in iPhone OS 2.0 and later.

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

25


CHAPTER 4

DOMWindow Additions

26

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


CHAPTER 5

GestureEvent

Inherits from

UIEvent

Availability

Available in iPhone OS 2.0 and later.

Companion guide

Safari Web Content Guide for iPhone OS

Overview The GestureEvent class encapsulates information about a multi-touch gesture. GestureEvent objects are high-level events that encapsulate the low-level TouchEvent objects. Both GestureEvent and TouchEvent events are sent during a multi-touch sequence. Gesture events contain

scaling and rotation information allowing gestures to be combined, if supported by the platform. If not supported, one gesture ends before another starts. Listen for GestureEvent events if you want to respond to gestures only, not process the low-level TouchEvent objects. The different types of GestureEvent objects that can occur are: gesturestart

Sent when two or more fingers touch the surface. gesturechange

Sent when fingers are moved during a gesture. gestureend

Sent 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 the

surface. 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 gestureend when 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.

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

27


CHAPTER 5

GestureEvent

Tasks Accessing Properties 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 and counter-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 altKey If true, the alt key is pressed; otherwise, it is not. If there is no keyboard, this value is false. readonly attribute boolean altKey;

Availability Available in iPhone OS 2.0 and later.

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

28

Tasks 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


CHAPTER 5

GestureEvent

readonly attribute boolean ctrlKey;

Availability Available in iPhone OS 2.0 and later.

metaKey If true, the meta key is pressed; otherwise, it is not. If there is no keyboard, this value is false. readonly attribute boolean metaKey;

Availability Available in iPhone OS 2.0 and later.

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

Availability Available in iPhone OS 2.0 and later.

scale 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). readonly attribute float scale;

Availability Available in iPhone OS 2.0 and later.

shiftKey If true, the Shift key is pressed; otherwise, it is not. If there is no keyboard, this value is false. readonly attribute boolean shiftKey;

Availability Available in iPhone OS 2.0 and later.

target The target of this gesture.

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

29


CHAPTER 5

GestureEvent

readonly attribute EventTarget target;

Availability Available in iPhone OS 2.0 and later.

Methods initGestureEvent Initializes 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);

Parameters type

The type of event that occurred. canBubble

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

Indicates whether an event can have its default action prevented. If true, the default action can be prevented; otherwise, it cannot. view

The view (DOM window) where the event occurred. detail

Specifies some detail information about the event depending on the type of event. screenX

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

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

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

30

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


CHAPTER 5

GestureEvent

clientY

The y-coordinate of the event’s location relative to the window's viewport. ctrlKey If true, the control key is pressed; otherwise, it is not. altKey

If true, the alt key is pressed; otherwise, it is not. shiftKey If true, the Shift key is pressed; otherwise, it is not. metaKey If true, the meta key is pressed; otherwise, it is not. target

The target of this gesture. scale

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). rotation

The delta rotation since the start of an event, in degrees, where clockwise is positive and counter-clockwise is negative. The initial value is 0.0. Discussion Use this method to programmatically create a GestureEvent object. Availability Available in iPhone OS 2.0 and later.

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

31


CHAPTER 5

GestureEvent

32

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


CHAPTER 6

Touch

Availability

Available in iPhone OS 2.0 and later.

Companion guide

Safari Web Content Guide for iPhone OS

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

Tasks Accessing Properties 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.

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

33


CHAPTER 6

Touch

Properties clientX The x-coordinate of the touch’s location relative to the window’s viewport. readonly attribute long clientX;

Availability Available in iPhone OS 2.0 and later.

clientY The y-coordinate of the touch’s location relative to the window’s viewport. readonly attribute long clientY;

Availability Available in iPhone OS 2.0 and later.

identifier The unique identifier for this touch object. readonly attribute unsigned long identifier;

Availability Available in iPhone OS 2.0 and later.

pageX The x-coordinate of the touch’s location in page coordinates. readonly attribute long pageX;

Availability Available in iPhone OS 2.0 and later.

pageY The y-coordinate of the touch’s location in page coordinates. readonly attribute long pageY;

Availability Available in iPhone OS 2.0 and later.

34

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


CHAPTER 6

Touch

screenX The x-coordinate of the touch’s location in screen coordinates. readonly attribute long screenX;

Availability Available in iPhone OS 2.0 and later.

screenY The y-coordinate of the touch’s location in screen coordinates. readonly attribute long screenY;

Availability Available in iPhone OS 2.0 and later.

target The target of this touch. readonly attribute EventTarget target;

Availability Available in iPhone OS 2.0 and later.

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

35


CHAPTER 6

Touch

36

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


CHAPTER 7

TouchEvent

Inherits from

UIEvent

Availability

Available in iPhone OS 2.0 and later.

Companion guide

Safari Web Content Guide for iPhone OS

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 a surface. A touch event provides a snapshot of all touches during a multi-touch sequence, most importantly the touches that are new or have changed for a particular target. A multi-touch sequence begins when a finger first touches the surface. Other fingers may subsequently touch the surface, and all fingers may move across the surface. The sequence ends when the last of these fingers is lifted from the surface. An application receives touch event objects during each phase of any touch. The different types of TouchEvent objects that can occur are: touchstart

Sent when a finger for a given event touches the surface. touchmove

Sent when a given event moves on the surface. touchend

Sent when a given event lifts from the surface. touchcancel

Sent when the system cancels tracking for the touch. TouchEvent objects are combined together to form high-level GestureEvent objects that are also sent during a multi-touch sequence. See GestureEvent (page 27) for details on GestureEvent objects and an

example of the events sent for a two finger multi-touch gesture.

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

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

37


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 altKey If true, the alt key is pressed; otherwise, it is not. If there is no keyboard, this value is false. readonly attribute boolean altKey;

Availability Available in iPhone OS 2.0 and later.

changedTouches A collection of Touch objects representing all touches that changed in this event. readonly attribute TouchList changedTouches;

Availability Available in iPhone OS 2.0 and later.

Methods initTouchEvent Initializes a newly created TouchEvent object.

38

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


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);

Parameters type

The type of event that occurred. canBubble

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

Indicates whether an event can have its default action prevented. If true, the default action can be prevented; otherwise, it cannot. view

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

Specifies some detail information about the event depending on the type of event. screenX

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

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

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

The y-coordinate of the event’s location relative to the window’s viewport. ctrlKey If true, the control key is pressed; otherwise, it is not. altKey

If true, the alt key is pressed; otherwise, it is not. shiftKey If true, the shift key is pressed; otherwise, it is not. metaKey If true, the meta key is pressed; otherwise, it is not.

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

39


CHAPTER 7

TouchEvent

touches

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

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

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

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). rotation

The delta rotation since the start of an event, in degrees, where clockwise is positive and counter-clockwise is negative. The initial value is 0.0. Discussion Use this method to programmatically create a TouchEvent object. Availability Available in iPhone OS 2.0 and later.

40

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


CHAPTER 8

TouchList

Availability

Available in iPhone OS 2.0 and later.

Companion guide

Safari Web Content Guide for iPhone OS

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

Tasks Accessing Properties 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 length The number of Touch objects in this TouchList object. readonly attribute unsigned long length;

Availability Available in iPhone OS 2.0 and later.

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

41


CHAPTER 8

TouchList

Methods item Returns the Touch object at the given index. Touch item( in unsigned long index);

Parameters index

The index of the item to return. Availability Available in iPhone OS 2.0 and later.

42

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


CHAPTER 9

WebKitAnimationEvent

Inherits from

Event

Availability

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

Companion guide

Safari Visual Effects Guide

Overview WebKitAnimationEvent objects encapsulate information about running animations. Several animation related events are available through the DOM Event system. The start and end of an animation, and the end of each iteration of an animation all generate DOM events. An element can have multiple properties that are animated simultaneously. This simultaneous animation can occur either by setting a single -webkit-animation-name value with keyframes containing multiple properties, or by setting multiple -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 current iteration of a looping animation or the current position of an alternating animation. This duration does not include 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: webkitAnimationStart

Occurs at the start of an animation. It can bubble and be canceled. Its animationName property is set. webkitAnimationEnd

Occurs when the animation finishes. It can bubble and be canceled. Its animationName and elapsedTime properties are set. webkitAnimationIteration

Occurs 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 with an iteration count of 1. It can bubble and be canceled. Its animationName and elapsedTime properties are set.

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

43


CHAPTER 9

WebKitAnimationEvent

Tasks Accessing Properties animationName (page 44)

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

The duration of the animation, in seconds, since this event was sent, excluding any time the animation is 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 animationName The name of the animation. The value of the CSS -webkit-animation-name property of the animation that caused the event. readonly attribute DOMString animationName;

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

elapsedTime The duration of the animation, in seconds, since this event was sent, excluding any time the animation is 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. readonly attribute double elapsedTime;

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

44

Tasks 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


CHAPTER 9

WebKitAnimationEvent

Methods initWebKitAnimationEvent Initializes a new animation event object. voidinitWebKitAnimationEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString animationNameArg, in double elapsedTimeArg);

Parameters typeArg

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

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

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

The name of the animation associated with this event. elapsedTimeArg

The duration of the animation, in seconds, since the event was sent. Discussion You use this method to initialize the value of a WebKitTransitionEvent object that is created through the DocumentEvent interface. This method can only be invoked before the WebKitTransitionEvent object is dispatched via the dispatchEvent method (although it can be invoked multiple times during that phase, if necessary). If it is invoked multiple times, the final invocation takes precedence. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

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

45


CHAPTER 9

WebKitAnimationEvent

46

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


CHAPTER 10

WebKitCSSKeyframeRule

Inherits from

CSSRule

Availability

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

Companion guide

Safari Visual Effects Guide

Overview WebKitCSSKeyframeRule objects represent the style rule for a single keyframe in the @-webkit-keyframes

CSS rule.

Tasks Accessing Properties keyText (page 47)

A keyframe selector. style (page 48)

The style associated with this keyframe.

Properties keyText A keyframe selector. attribute DOMString keyText;

Discussion A keyframe selector represented as a percentage value or the keyword from or to. The selector is used to specify the percentage along the duration of the animation. The keyframe is specified by the block of property values declared for the selector. The keyword from is equivalent to 0 percent and to is equivalent to 100 percent.

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

47


CHAPTER 10

WebKitCSSKeyframeRule

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

style The style associated with this keyframe. readonly attribute CSSStyleDeclaration style;

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

48

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


CHAPTER 11

WebKitCSSKeyframesRule

Inherits from

CSSRule

Availability

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

Companion guide

Safari Visual Effects Guide

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

Tasks Accessing Properties 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.

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

49


CHAPTER 11

WebKitCSSKeyframesRule

Properties cssRules The set of style rules that define the keyframes following the animation name. readonly attribute CSSRuleList cssRules;

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

name The name of the target animation that is set using the -webkit-animation-name property. attribute DOMString name;

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

Methods deleteRule Removes a keyframe rule from the collection of keyframes. void deleteRule(in DOMString key);

Parameters key

A selector for the rule that is either a percentage or the keyword from or to. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

findRule Returns the keyframe rule for the specified selector. WebKitCSSKeyframeRule findRule(in DOMString key);

Parameters key

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

50

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


CHAPTER 11

WebKitCSSKeyframesRule

Return Value Returns the keyframe rule corresponding to the given selector if it exists. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

insertRule Adds a keyframe rule to the collection of keyframes. void insertRule(in DOMString rule);

Parameters rule

A string representing a selector and keyframe, where the selector is a percentage or keyword and the keyframe is a block. The string must follow the format for keyframe blocks in the @-webkit-keyframes CSS rule. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

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

51


CHAPTER 11

WebKitCSSKeyframesRule

52

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


CHAPTER 12

WebKitCSSMatrix

Availability

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

Companion guide

Safari Visual Effects Guide

Overview WebKitCSSMatrix objects represent a 4x4 homogeneous matrix for 3D transforms or a vector for 2D

transforms. 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 by window.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 Accessing Properties 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.

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

53


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.

54

Tasks 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


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 a The first 2D vector value. attribute float a;

Availability Available in Safari 4.0 and later.

b The second 2D vector value. attribute float b;

Availability Available in Safari 4.0 and later.

c The third 2D vector value. attribute float c;

Availability Available in Safari 4.0 and later.

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

55


CHAPTER 12

WebKitCSSMatrix

d The fourth 2D vector value. attribute float d;

Availability Available in Safari 4.0 and later.

e The fifth 2D vector value. attribute float e;

Availability Available in Safari 4.0 and later.

f The sixth 2D vector value. attribute float f;

Availability Available in Safari 4.0 and later.

m11 The 3D matrix value in the first row and first column. attribute float m11;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m12 The 3D matrix value in the first row and second column. attribute float m12;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column.

56

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


CHAPTER 12

WebKitCSSMatrix

Availability Available in iPhone OS 2.0 and later.

m13 The 3D matrix value in the first row and third column. attribute float m13;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m14 The 3D matrix value in the first row and fourth column. attribute float m14;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m21 The 3D matrix value in the second row and first column. attribute float m21;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m22 The 3D matrix value in the second row and second column. attribute float m22;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column.

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

57


CHAPTER 12

WebKitCSSMatrix

Availability Available in iPhone OS 2.0 and later.

m23 The 3D matrix value in the second row and third column. attribute float m23;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m24 The 3D matrix value in the second row and fourth column. attribute float m24;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m31 The 3D matrix value in the third row and first column. attribute float m31;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m32 The 3D matrix value in the third row and second column. attribute float m32;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column.

58

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


CHAPTER 12

WebKitCSSMatrix

Availability Available in iPhone OS 2.0 and later.

m33 The 3D matrix value in the third row and third column. attribute float m33;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m34 The 3D matrix value in the third row and fourth column. attribute float m34;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m41 The 3D matrix value in the fourth row and first column. attribute float m41;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m42 The 3D matrix value in the fourth row and second column. attribute float m42;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column.

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

59


CHAPTER 12

WebKitCSSMatrix

Availability Available in iPhone OS 2.0 and later.

m43 The 3D matrix value in the fourth row and third column. attribute float m43;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

m44 The 3D matrix value in the fourth row and fourth column. attribute float m44;

Discussion One of the 16 values for the 4x4 homogeneous matrix. For example, m12 represents the value in the first row and the second column. Availability Available in iPhone OS 2.0 and later.

Methods inverse Returns the inverse of this matrix. WebKitCSSMatrix inverse() raises CSSException;

Return Value A new matrix that is the inverse of this matrix. Discussion This matrix is not modified by this method. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

60

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


CHAPTER 12

WebKitCSSMatrix

multiply Returns the result of multiplying this matrix by a given matrix that is on the right. WebKitCSSMatrix multiply(in WebKitCSSMatrix secondMatrix) raises CSSException;

Parameters secondMatrix

The matrix to multiply. Return Value A new matrix that is the result of multiplying this matrix by the given matrix. Discussion The given matrix is on the right of the multiplication. This matrix is not modified by this method. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

rotate Returns the result of rotating this matrix by a given vector. WebKitCSSMatrix rotate(in float rotX, in float rotY, in float rotZ);

Parameters rotX

The x component in the vector, in degrees. rotY

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

The z component in the vector, in degrees. If undefined, the x component is used. Return Value A new matrix that is the result of rotating this matrix by each of the three rotation matrices about the major axes, first the x axes, y axes, and then z axes. Discussion This matrix is not modified by this method. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

rotateAxisAngle Returns 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);

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

61


CHAPTER 12

WebKitCSSMatrix

Parameters x

The x component in the vector, in degrees. y

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

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

The angle of rotation about the axis vector, in degrees. Return Value A new matrix that is the result of rotating this matrix by each of the three rotation matrices about the major axes and angle. The right-hand rule is used to determine the direction of rotation. Discussion This matrix is not modified by this method. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

scale Returns the result of scaling this matrix by a given vector. WebKitCSSMatrix scale(in float scaleX, in float scaleY, in float scaleZ);

Parameters scaleX

The x component in the vector. scaleY

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

The z component in the vector. If undefined, 1 is used. Return Value A new matrix that is the result of scaling this matrix. Discussion This matrix is not modified by this method. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

setMatrixValue Sets the matrix values using a string representation. void setMatrixValue(in DOMString string);

62

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


CHAPTER 12

WebKitCSSMatrix

Parameters string

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

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

toString Returns a string representation of the matrix. DOMString toString();

Return Value A string representation of the matrix’s values. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

translate Returns the result of translating this matrix by a given vector. WebKitCSSMatrix translate(in float x, in float y, in float z);

Parameters x

The x component in the vector. y

The y component in the vector. z

The z component in the vector. If undefined, 0 is used. Return Value A new matrix that is the result of translating this matrix. Discussion This matrix is not modified by this method. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

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

63


CHAPTER 12

WebKitCSSMatrix

64

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


CHAPTER 13

WebKitCSSTransformValue

Inherits from

CSSValueList

Availability

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

Companion guide

Safari Visual Effects Guide

Overview WebKitCSSTransformValue objects represent one transform function in a CSS transform property. The operationType property in this class specifies which function is used. The objects also contain a list of

values which are the parameters to the function. The parameters appear in the same order as they appear in the function.

Tasks Accessing Properties operationType (page 65)

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

Properties operationType The transform function used. Possible values are described in CSS_MATRIX (page 66). readonly attribute unsigned short operationType;

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

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

65


CHAPTER 13

WebKitCSSTransformValue

Constants Constant

Description

CSS_MATRIX

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

= 1;

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

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

= 2;

Available in iPhone OS 2.0 and later. CSS_PERSPECTIVE Specifies the perspective() transform function. const unsigned short CSS_PERSPECTIVE = 12;

Available in iPhone OS 2.0 and later. CSS_ROTATE

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

= 3;

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

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

= 4;

Available in iPhone OS 2.0 and later. CSS_ROTATEX

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

= 13;

Available in iPhone OS 2.0 and later. CSS_ROTATEY

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

= 14;

Available in iPhone OS 2.0 and later. CSS_ROTATEZ

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

= 15;

Available in iPhone OS 2.0 and later. CSS_SCALE

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

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

66

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

= 7;


CHAPTER 13

WebKitCSSTransformValue

Constant

Description

CSS_SCALE3D

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

= 8;

Available in iPhone OS 2.0 and later. CSS_SCALEX

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

= 19;

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

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

= 20;

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

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

= 21;

Available in iPhone OS 2.0 and later. CSS_SKEW

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

= 8;

Available in Safari 4.0 and later. CSS_SKEWX

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

= 9;

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

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

= 10;

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

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

= 5;

Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later. CSS_TRANSLATE3D Specifies the translate3d() transform function. const unsigned short CSS_TRANSLATE3D = 6;

Available in iPhone OS 2.0 and later.

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

67


CHAPTER 13

WebKitCSSTransformValue

Constant

Description

CSS_TRANSLATEX

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

= 16;

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

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

= 17;

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

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

= 18;

Available in iPhone OS 2.0 and later. CSS_UNKNOWN

An unknown function. const unsigned short CSS_UNKNOWN

Available in iPhone OS 2.0 and later.

68

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

= 0;


CHAPTER 14

WebKitPoint

Availability

Available in iPhone OS 2.0 and later.

Companion guide

Safari Visual Effects Guide

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

Tasks Accessing Properties x (page 69)

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

The y coordinate for the point.

Properties x The x coordinate for the point. attribute float x;

Availability Available in iPhone OS 2.0 and later.

y The y coordinate for the point.

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

69


CHAPTER 14

WebKitPoint

attribute float y;

Availability Available in iPhone OS 2.0 and later.

70

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


CHAPTER 15

WebKitTransitionEvent

Inherits from

Event

Availability

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

Companion guide

Safari Visual Effects Guide

Overview WebKitTransitionEvent objects provide information about CSS transitions. An event is sent at the end

of a transition for each CSS property in the transition. Each event contains the name of the CSS property and duration of the transition. You can use these events to perform some action that starts at the end of a transition.

Types of Transition Events The only possible string value for a transition event’s type property is: webKitTransitionEnd

Sent when a transition completes.

Tasks Accessing Properties 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 the value of the CSS -webkit-transition-delay property.

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

71


CHAPTER 15

WebKitTransitionEvent

Initializing initWebKitTransitionEvent (page 72)

Initializes a new transition event object.

Properties elapsedTime The duration of the transition, in seconds, since this event was sent. This value is not affected by the value of the CSS -webkit-transition-delay property. readonly attribute double elapsedTime;

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

propertyName The name of the CSS property associated with the transition. readonly attribute DOMString propertyName;

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

Methods initWebKitTransitionEvent Initializes a new transition event object. void initWebKitTransitionEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in DOMString propertyNameArg, in double elapsedTimeArg);

Parameters typeArg

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

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

72

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


CHAPTER 15

WebKitTransitionEvent

cancelableArg

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

The name of the CSS property associated with this event. elapsedTimeArg

The duration of the transition, in seconds, since the event was sent. Discussion You use this method to initialize the value of a WebKitTransitionEvent object that is created through the DocumentEvent interface. This method can only be invoked before the WebKitTransitionEvent object is dispatched via the dispatchEvent method (although, it can be invoked multiple times during that phase, if necessary). If it is invoked multiple times, the final invocation takes precedence. Availability Available in Safari 4.0 and later. Available in iPhone OS 2.0 and later.

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

73


CHAPTER 15

WebKitTransitionEvent

74

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


REVISION HISTORY

Document Revision History

This table describes the changes to Safari DOM Extensions Reference. Date

Notes

2009-01-30

Updated per Safari 4.0 changes.

2008-11-21

Added the DOMApplicationCache class.

2008-10-15

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

2008-07-11

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

75 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


REVISION HISTORY

Document Revision History

76 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


Index

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

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

D B b property 55

C

d property 56 deleteRule method 50 DOWNLOADING constant 21

E

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

e property 56 elapsedTime property 44, 72

F f property 56 findRule method 50

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

77 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


INDEX

K

P

keyText property 47

pageX property 34 pageY property 34 propertyName property 72

L length property 41

R

M

rotate method 61 rotateAxisAngle method 61 rotation property 29

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

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

T target property 29, 35 toString method 63 translate method 63

N name property 50

U UNCACHED constant 20 update method 20 UPDATEREADY constant 21

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

78 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.

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


INDEX

X x property 69

Y y property 69

79 2009-01-30 | Š 2004, 2009 Apple Inc. All Rights Reserved.


Safari DOM Extensions Reference