Safari CSS Animation Guide for iPhone OS Internet & Web > Web Content

2008-10-15

Apple Inc. © 2008 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, 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. 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

Introduction 7 Organization of This Document 7 See Also 7

Animation and Safari 9 Transitions 13 What are Transitions? 13 What CSS Properties are Animatable? 14 CSS Transition Properties 16 -webkit-transition-property 16 -webkit-transition-duration 17 -webkit-transition-timing-function 17 -webkit-transition-delay 19 -webkit-transition Shorthand Property 20

Animations 21 Animation Keyframes 21 Invoking an Animation 23 CSS Animation Properties 25 -webkit-animation-name 25 -webkit-animation-duration 25 -webkit-animation-timing-function 26 -webkit-animation-iteration-count 27 -webkit-animation-direction 27 -webkit-animation-play-state 28 -webkit-animation-delay 28 -webkit-animation 29 Animation Events 29

Document Revision History 31

3 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

C O N T E N T S

4 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Figures, Tables, and Listings Animation and Safari 9 Figure 1 Figure 2

Circle Poster example 10 Card Flip example 11

Transitions 13 Figure 1 Table 1 Table 2 Table 3 Table 4 Table 5 Listing 1 Listing 2 Listing 3 Listing 4 Listing 5 Listing 6

Cubic Bezier timing function 18 -webkit-transition-property definition 16 -webkit-transition-duration definition 17 -webkit-transition-timing-function definition 19 -webkit-transition-delay definition 19 -webkit-transition definition 20

Simple transition definition 13 opacity transition example 13 Transition definition for multiple CSS properties 14 Example -webkit-transition-timing-function code fragment 18 Example -webkit-transition-delay code fragment 19 Example -webkit-transition code fragment 20

Animations 21 Table 1 Table 2 Table 3 Table 4 Table 5 Table 6 Table 7 Table 8 Listing 1 Listing 2 Listing 3 Listing 4 Listing 5 Listing 6

-webkit-animation-name definition 25 -webkit-animation-duration definition 26 -webkit-animation-timing-function definition 26 -webkit-animation-iteration-count definition 27 -webkit-animation-animation-direction definition 27 -webkit-animation-play-state definition 28 -webkit-animation-delay definition 28 -webkit-animation definition 29

Example @-web-keyframes declaration 21 Declared animation using -webkit-animation-timing-function 22 Declared animation using both duration and iteration-count properties 23 Complete ‘diagonal slide’ animation fragment 23 Restarting an animation 24 Example of using animation events 29

5 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

F I G U R E S ,

T A B L E S ,

A N D

6 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

L I S T I N G S

I N T R O D U C T I O N

Introduction

This document is an introduction to the CSS animation features in Safari for iPhone. You should read this document if you want your web content to take advantage of the new CSS animation features provided in Safari for iPhone. Definitely read this document if you are creating a custom web application for iPhone.

Organization of This Document Safari CSS Animation Guide for iPhone consists of the following chapters: ■

“Animation on the Web” (page 9) provides an overview of what the current animation options on the WWW and the new features that CSS animation offer.

■

“Transitions” (page 13) discusses transition animations that happen automatically when an animatable CSS property is altered.

■

“Animations” (page 21) discusses defined animations that are explicitly created and invoked.

See Also If you want to learn more about the CSS animation and transform properties, then you should read: ■

Safari CSS Transform Guide for iPhone OS describes how to use the CSS transform properties.

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

Organization of This Document 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

7

I N T R O D U C T I O N

Introduction

8

See Also 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Animation and Safari

Safari for iPhone introduces new CSS a animation properties that provide powerful animation possibilities without having to use Flash or Dynamic HTML. Using these new animation properties elements can be animated as they move, resize, change color and opacity, and other visual changes. When combined with the new Safari for iPhone CSS transforms you can also animate rotation, scaling, and translation in two- and three-dimensional space. These new CSS properties support two types of animation: implicit animation (which we call transitions) and declared animation. Transitions are triggered when you set a new value for an animatable CSS property. The transition causes the property to animate to the new value over a specified duration. Declared animation, on the other hand, allows you to specify a value, or series of values, which a property will have over a time period, and to apply that animation directly to an element. The following chapters discuss the CSS animation properties and their possible values, along with example code fragments illustrating their usage. The animations in Figure 1 and Figure 2 show some of the possibilities of using Safari’s CSS animation and transform properties together.

9 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Animation and Safari

Figure 1

Circle Poster example

10 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Animation and Safari

Figure 2

Card Flip example

11 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Animation and Safari

12 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Transitions

This chapter describes new CSS properties that are used to animate smoothly from the element old state to the new state, over time.

What are Transitions? Normally when the value of a CSS property changes, the affected elements are rendered immediately using the new property value. Changing the value of an element’s left style property from a current value of 100px to 300px causes the element to immediately move to the new value. While this is fine for static pages, it provides for a limited user-interface experience when designing rich web applications. A JavaScript function could be used to iterate over an array of intermediate values, constantly updating the left property with new values, but this is computationally expensive and requires significantly more code. Safari for iPhone defines new CSS transition properties that are used to define new transitional behavior. If you change a CSS property for which a transition has been configured, it will smoothly move to the new value without requiring any further interaction from your code. The transition for a property is defined using a number of new CSS properties. Listing 1 shows the definition of a simple transition on the opacity property of a div element: Listing 1

Simple transition definition

div { -webkit-transition-property: opacity; -webkit-transition-duration: 2s; }

The above example defines a transition on the opacity property that, when a new value is assigned to that property, it will cause a smooth change between the old value and the new value over a period of two seconds. The example in Listing 2 shows an HTML implementation that will cause a blue box to fade away when you tap it. Listing 2

opacity transition example

div { -webkit-transition-property: opacity; -webkit-transition-duration: 2s; } div.fadeAway { opacity:0; }

What are Transitions? 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

13

Transitions



Tap to fade

Each of the CSS transition properties can also accept a comma-separated list, allowing multiple transitions to be defined, each acting on a different property. Each transition property takes its parameters from the corresponding index in the other transition properties. For example, in Listing 3 transitions are defined for both the opacity and the left CSS properties with two and four second durations respectively. Listing 3

Transition definition for multiple CSS properties

div { -webkit-transition-property: opacity, left; -webkit-transition-duration: 2s, 4s; }

What CSS Properties are Animatable? Any CSS property which accepts values that are numbers, lengths, percentages or colors can be animated. Also, some CSS properties that accept discrete values, such as the visibility property can be animated, although they will display a jump between values rather than a smooth transition. Any CSS property which accepts values that are numbers, lengths, percentages or colors can be animated. Also, some CSS properties that accept discrete values, such as 'visibility' can be animated, although they will display a jump between values rather than a smooth transition. The following is a list of CSS properties Safari for iPhone can currently animate:

14

■

left

■

right

■

top

■

bottom

■

width

■

height

■

border-left-width

■

border-right-width

■

border-top-width

What CSS Properties are Animatable? 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Transitions

■

border-bottom-width

■

margin-left

■

margin-right

■

margin-top

■

margin-bottom

■

padding-left

■

padding-right

■

padding-top

■

padding-bottom

■

color

■

background-color

■

-webkit-column-rule-color

■

-webkit-column-rule-width

■

-webkit-column-gap

■

-webkit-column-count

■

-webkit-column-width

■

text-stroke-color

■

text-fill-color

■

-webkit-border-horizontal-spacing

■

-webkit-border-vertical-spacing

■

border-left-color

■

border-right-color

■

border-top-color

■

border-bottom-color

■

z-index

■

line-height

■

outline-color

■

outline-offset

■

outline-width

■

letter-spacing

■

word-spacing

■

-webkit-box-shadow

■

text-shadow

■

-webkit-border-left-radius

■

-webkit-border-right-radius

What CSS Properties are Animatable? 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

15

Transitions

■

-webkit-border-top-radius

■

-webkit-border-bottom-radius

■

visibility

■

-webkit-transform-origin-x

■

-webkit-transform-origin-y

■

-webkit-transform-origin-z

■

-webkit-transform (The animation of this property has been optimized in the current implementation.

However, the value returned via the computed style during the animation is not accurate.) ■

opacity (The animation of this property has been optimized in the current implementation. However,

the value returned via the computed style during the animation is not accurate.)

CSS Transition Properties Safari for iPhone defines new CSS properties for specifying the CSS property to transition, the duration of the transition, the timing of the transition (how intermediate values are distributed over the duration), and delaying the start time of the transition. In addition, a “shorthand” property is defined that allows all these transition properties to be combined into one.

-webkit-transition-property The -webkit-transition-property property specifies the name of the CSS property to which the transition is applied. Multiple properties can be supplied, separated by commas. Property names should be bare, unquoted names. Table 1

-webkit-transition-property definition

Name:

-webkit-transition-property

Value:

none | all | [ ] [ , ]*

Initial:

all

Applies to:

block-level and inline-level elements

Inherited:

no

Percentages:

N/A

Media:

visual

Computed value: Same as specified value.

16

CSS Transition Properties 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Transitions

-webkit-transition-duration The -webkit-transition-duration property defines how long the transition from the old value to the new value should take. By default the value is 0, meaning that the transition is immediate (there will be no animation). A negative value for -webkit-transition-duration is treated as 0. Non-zero times must specify a unit: s for seconds, ms for milliseconds. Table 2

-webkit-transition-duration definition

Name:

-webkit-transition-duration

Value:

[, ]*

Initial:

0

Applies to:

block-level and inline-level elements

Inherited:

no

Percentages:

N/A

Media:

visual

Computed value: Same as specified value.

-webkit-transition-timing-function The -webkit-transition-timing-function property describes how the intermediate values used during a transition will be calculated. It allows for a transition to change speed over its duration. These effects are commonly called easing functions. These are mathematical functions that produce a smooth curve. The timing function is specified using a cubic Bezier curve, which is defined by four control points, P0 through P3 (see Figure 1). P0 and P3 are always set to (0,0) and (1,1). The -webkit-transition-timing-function property is used to specify the values for points P1 and P2. These can be set to preset values using the keywords listed below, or can be set to specific values using the cubic-bezier function. In the cubic-bezier function, P1 and P2 are each specified by both an X and Y value.

CSS Transition Properties 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

17

Transitions

Figure 1

Cubic Bezier timing function

1.0

P3

P2

Output percentage

0.5

P1 P0 Input percentage

1.0

0.5

The timing function takes as its input the current elapsed percentage of the transition duration and outputs a percentage that determines how close the transition is to its goal state. Listing 4

Example -webkit-transition-timing-function code fragment

div.zoom-fade { -webkit-transition-property: -webkit-transform, opacity; -webkit-transition-duration: 4s, 2s; -webkit-transition-timing-function: ease-out, cubic-bezier(0.5, 0.2, 0.3, 1.0); }

The timing functions have the following definitions. Value

Definition

auto (This will change to ease

The auto function is equivalent to cubic-bezier(0.25, 0.1, 0.25, 1.0).

post-beta.)

18

linear

The linear function is equivalent to cubic-bezier(0.0, 0.0, 1.0, 1.0).

ease-in

The ease-in function is equivalent to cubic-bezier(0.42, 0, 1.0, 1.0).

ease-out

The ease-out function is equivalent to cubic-bezier(0, 0, 0.58, 1.0).

ease-in-out

The ease-in-out function is equivalent to cubic-bezier(0.42, 0, 0.58, 1.0)

CSS Transition Properties 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Transitions

Value

Definition

cubic-bezier(P1x,P1y,P2x,P2y) Specifies a cubic-bezier curve. The four values specify points P1 and P2 of the curve as (x1, y1, x2, y2).

Table 3

-webkit-transition-timing-function definition

Name:

-webkit-transition-timing-function

Value:

auto | linear | ease-in | ease-out | ease-in-out | cubic-bezier(, , , ) [, auto | linear | ease-in | ease-out | ease-in-out | cubic-bezier(, , , )]* (Note: Post-beta the keyword auto will change to ease.)

Initial:

auto (Note: Post-beta the keyword auto will change to ease.)

Applies to:

block-level and inline-level elements

Inherited:

no

Percentages:

N/A

Media:

visual

Computed value: Same as specified value.

-webkit-transition-delay The -webkit-transition-delay property defines when the transition will start. It allows a transition to begin execution some period of time from when it is applied. A -webkit-transition-delay value of 0 means the transition will execute as soon as the property is changed. Otherwise, the value specifies an offset from the moment the property is changed, and the transition will delay execution by that offset. Non-zero times must specify a unit: s for seconds, ms for milliseconds. Listing 5

Example -webkit-transition-delay code fragment

div.zoom-fade { -webkit-transition-property: -webkit-transform, opacity; -webkit-transition-duration: 4s, 2s; -webkit-transition-delay: 2s, 0; }

Table 4

-webkit-transition-delay definition

Name:

-webkit-transition-delay

Value:

[, ]*

Initial:

0

CSS Transition Properties 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

19

Transitions

Applies to:

block-level and inline-level elements

Inherited:

no

Percentages:

N/A

Media:

visual

Computed value: Same as specified value.

-webkit-transition Shorthand Property The -webkit-transition shorthand property combines the four properties described above into a single property. Listing 6

Example -webkit-transition code fragment

div.sliding { -webkit-transition: opacity 500ms ease-out 100ms; }

Table 5

-webkit-transition definition

Name:

-webkit-transition

Value:

[ || || || [, [ || || || ]]*

Initial:

see individual properties

Applies to:

block-level and inline-level elements

Inherited:

no

Percentages:

N/A

Media:

visual

Computed value: Same as specified value.

20

CSS Transition Properties 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Animations

Animations are similar to transitions in that they change the presentational value of CSS properties over time. The principal difference is that while transitions trigger implicitly when property values change, animations are explicitly executed when the animation properties are applied. Because of this, animations require explicit values for the properties being animated. This chapter discusses animation keyframes, the mechanism through which values are specified for explicit animations.

Animation Keyframes Keyframes are specified using a specialized at-rule. A @-webkit-keyframes rule consists of the keyword "@-webkit-keyframes", followed by the name of the target animation (using -webkit-animation-name), followed by a set of style rules (delimited by curly braces). For example, in Listing 1, the keyframes rule describes an animation with the name “wobble”. The keyframe selector for a keyframe style rule consists of a percentage value or the keywords from or to. The selector is used to specify the percentage along the duration of the animation or transition that the keyframe represents. The keyframe itself is specified by the block of property values declared on the selector. The keyword from is equivalent to the value 0%. The keyword to is equivalent to the value 100%. For example, in Listing 1, the keyframes rule contains keyframes describing the state of the animation at the start, at 40% and 60% into the animation, and at the end. The keyframe declaration for a keyframe rule consists of properties and values which describe the state of those properties at that point in the animation. Properties that are not animating are ignored in these rules, with the exception of -webkit-animation-timing-function. The @-webkit-keyframes rule that is used by an animation will be the last one encountered in sorted rules order that matches the name of the animation. @-webkit-keyframes rules do not cascade; therefore an animation will never derive keyframes from more than one @-webkit-keyframes rule. To determine the set of keyframes, all of the values in selectors are sorted in increasing order by time. If there are any duplicates, then the last keyframe specified inside the @-webkit-keyframes rule will be used to provide the keyframe information for that time. There is no cascading within a @-webkit-keyframes rule if multiple keyframes specify the same keyframe selector values. Listing 1 shows an @-web-keyframes declared animation called “wobble”, which moves the left position of the target element back and forth over time. Listing 1

Example @-web-keyframes declaration

@-webkit-keyframes 'wobble' { 0% { left: 100px;

Animation Keyframes 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

21

Animations

} 40% { left: 150px; } 60% { left: 75px; } 100% { left: 100px; } }

Four keyframes are specified for the transition or animation named "wobble". In the first keyframe, the value of the left property of the animation is 100px. By 40% of the animation duration, the value of the left property has animated to 150px. At 60% of the animation duration, the value of the left property has animated back to 75px. At the end of the animation cycle, the value of the left property has returned to 100px. A keyframe style rule may also declare the timing function that is to be used as the animation moves to the next keyframe. Listing 2 shows a declared animation that specifies several timing functions. Listing 2

Declared animation using -webkit-animation-timing-function

@-webkit-keyframes 'bounce' { from { top: 100px; -webkit-animation-timing-function: ease-out; } 25% { top: 50px; -webkit-animation-timing-function: ease-in; } 50% { top: 100px; -webkit-animation-timing-function: ease-out; } 75% { top: 75px; -webkit-animation-timing-function: ease-in; } to { top: 100px; } }

22

Animation Keyframes 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Animations

Five keyframes are specified for the transition or animation named "bounce". Between the first and second keyframe (the first quarter of the duration) an ease-out timing function is used. Between the second and third keyframe (second quarter of the duration) an ease-in timing function is used. And so on. The effect will appear as an element that moves up the page 50px, slowing down as it reaches its highest point then speeding up as it falls back to 100px. The second half of the animation behaves in a similar manner, but only moves the element 25px units up the page. See “-webkit-animation-timing-function” (page 26) for more information about the available timing functions. The declared animation in Listing 3 will produce an animation that moves an element from (0, 0) to (100px, 100px) over five seconds and repeats itself nine times (for a total of ten iterations). Listing 3

Declared animation using both duration and iteration-count properties

.diagonalslide { -webkit-animation-name: 'diagonal-slide'; -webkit-animation-duration: 5s; -webkit-animation-iteration-count: 10; } @-webkit-keyframes 'diagonal-slide' { from { left: 0; top: 0; } to { left: 100px; top: 100px; } }

Invoking an Animation Once you have declared an animation, you must invoke it to make it actually animate. This is accomplished by creating a style that set -webkit-animation-name to the name of the declared animation. Listing 4 (page 23) shows a complete code fragement using the diagonal slide animation shown in Listing 3 (page 23). Listing 4

Complete ‘diagonal slide’ animation fragment

div { width:100px; height:100px; background-color:blue; position:absolute; } .diagonalslide { -webkit-animation-name: 'diagonal-slide'; -webkit-animation-duration: 5s;

Invoking an Animation 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

23

Animations

-webkit-animation-iteration-count: 10; } @-webkit-keyframes 'diagonal-slide' { from { left: 0; top: 0; } to { left: 100px; top: 100px; } }

Tap to slide CodeLine

When the user taps in the blue box that says “Tap to slide” the onClick attribute changes the style class of the div to diagonalslide and the animation begins. The effects of an animation will cease once the animation completes, or if the animation is removed. Removing an animation can be accomplished by setting the -webkit-animation-name property to a value that does not include the name of that animation. When an animation finishes running, because it has executed the number of times described in its iteration count, then the properties that were being animated return to their original, non-animated values. To restart an animation, set the -webkit-animation-name property to a value that includes the name of that animation. Because style changes are coalesced, you may have to do this after a short delay. Listing 5 shows how to restart the “bounce” animation declared in Listing 2. Listing 5

Restarting an animation

div.bounce { -webkit-animation-name: 'bounce'; -webkit-animation-duration: 4s; -webkit-animation-iteration-count: 3; } function restartBounce(element) { element.style.webkitAnimationName = ''; window.setTimeout(function() { element.style.webkitAnimationName = 'bounce'; }, 0); }

24

Invoking an Animation 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Animations



CSS Animation Properties Safari for iPhone defines new CSS properties for specifying animations. Many aspects of an animation can be controlled, including its duration, how many times the animation iterates, whether or not it alternates between the begin and end values, and whether or not the animation should be running or paused. An animation can also delay its start time. Each animation has a name that associates it with a keyframes declaration (see previous section). The name and other animation parameters are defined via CSS, with each parameter having a corresponding CSS property. In addition, a “shorthand” property is defined that allows all these animation properties to be combined into one style rule. This section describes each of the Safari CSS animation properties.

-webkit-animation-name The -webkit-animation-name property defines a name for the animation. The name is used to select the keyframe at-rule that provides the property values for the animation. If the name does not match any keyframe at-rule, there are no properties to be animated and the animation will not execute. Table 1

-webkit-animation-name definition

Name:

-webkit-animation-name

Value:

[, ]*

Initial:

""

Applies to:

block-level and inline-level elements

Inherited:

No

Percentages

N/A

Media:

visual

Computed value: Same as specified value.

-webkit-animation-duration The -webkit-animation-duration property defines the length of time that an animation takes to complete one cycle.

CSS Animation Properties 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

25

Animations

By default the value is 0, meaning that the animation cycle is immediate (there will be no animation). A negative value for -webkit-animation-duration is treated as 0. Table 2

-webkit-animation-duration definition

Name:

-webkit-animation-duration

Value:

[, ]*

Initial:

0

Applies to:

block-level and inline-level elements

Inherited:

No

Percentages

N/A

Media:

visual

Computed value: Same as specified value.

-webkit-animation-timing-function The -webkit-animation-timing-function property describes how the animation will progress over one cycle of its duration. See “-webkit-transition-timing-function” (page 17) for a complete description. For a keyframed animation, the -webkit-animation-timing-function applies between keyframes, not over the entire animation. For example, in the case of an ease-in-out timing function, an animation will ease in at the start of the keyframe and ease out at the end of the keyframe. A -webkit-animation-timing-function defined within a keyframe block applies to that keyframe, otherwise the timing function specified for the animation is used. Table 3

-webkit-animation-timing-function definition

Name:

-webkit-animation-timing-function

Value:

auto | linear | ease-in | ease-out | ease-in-out | cubic-bezier(, , , ) [, auto | linear | ease-in | ease-out | ease-in-out | cubic-bezier(, , , )]* (Note: Post-beta the keyword auto will change to ease.)

Initial:

ease-in

Applies to:

block-level and inline-level elements

Inherited:

No

Percentages

N/A

Media:

visual

Computed value: Same as specified value.

26

CSS Animation Properties 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Animations

-webkit-animation-iteration-count The -webkit-animation-iteration-count property defines the number of times an animation cycle is played. The default value is 1, meaning the animation will play from beginning to end once. A value of infinite will cause the animation to repeat forever. Non-integer numbers will cause the animation to end part-way through a cycle. Negative values for -webkit-animation-iteration-count are treated as zero. This property is often used with an -webkit-animation-direction value of alternate, which will cause the animation to play in reverse on alternate cycles. Table 4

-webkit-animation-iteration-count definition

Name:

-webkit-animation-iteration-count

Value:

infinite | [, infinite | ]*

Initial:

1

Applies to:

block-level and inline-level elements

Inherited:

No

Percentages

N/A

Media:

visual

Computed value: Same as specified value.

-webkit-animation-direction The -webkit-animation-direction property defines whether or not the animation should play in reverse on alternate cycles. If alternate is specified, the animation cycle iterations that are odd counts are played in the normal direction, and the animation cycle iterations that are even counts are played in a reverse direction. When an animation is played in reverse the timing functions are also reversed. For example, when played in reverse an ease-in animation would appear to be an ease-out animation. Table 5

-webkit-animation-animation-direction definition

Name:

-webkit-animation-direction

Value:

normal | alternate [, normal | alternate]*

Initial:

normal

Applies to:

block-level and inline-level elements

Inherited:

No

Percentages

N/A

Media:

visual

Computed value: Same as specified value.

CSS Animation Properties 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

27

Animations

-webkit-animation-play-state The -webkit-animation-play-state property defines whether the animation is running or paused. A running animation can be paused by setting this property to paused. To continue running a paused animation this property can be set to running. A paused animation will continue to display the current value of the animation in a static state, as if the time of the animation is unchanging. When a paused animation is resumed, it restarts from the current value, not from the beginning of the animation. Table 6

-webkit-animation-play-state definition

Name:

-webkit-animation-play-state

Value:

running | paused [, running | paused]*

Initial:

running

Applies to:

block-level and inline-level elements

Inherited:

No

Percentages

N/A

Media:

visual

Computed value: Same as specified value.

-webkit-animation-delay The -webkit-animation-delay property defines when the animation will start. It allows an animation to begin execution some time after it is applied. An -webkit-animation-delay value of 0 means the animation will execute as soon as it is applied. Otherwise, the value specifies an offset from the moment the animation is applied, and the animation will delay execution by that offset. Table 7

-webkit-animation-delay definition

Name:

-webkit-animation-delay

Value:

[, ]*

Initial:

0

Applies to:

block-level and inline-level elements

Inherited:

No

Percentages

N/A

Media:

visual

Computed value: Same as specified value.

28

CSS Animation Properties 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

Animations

-webkit-animation The -webkit-animation shorthand property combines the five animation properties into a single property. Table 8

-webkit-animation definition

Name:

-webkit-animation

Value:

[ || || || || ] [, [ || || || || ]]*

Initial:

see individual properties

Applies to:

block-level and inline-level elements

Inherited:

No

Percentages

N/A

Media:

visual

Computed value: Same as specified value.

Animation Events 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. The animation names are animationstart, animationloop and animationend. The example in Listing 6 adds an event listener for animationend events at page load time on the div element with the id box. When the animationend event is received, the function checks to see if the animation was the “bounce” animation, and, if so, hides the box by setting the element’s display style to hidden. Listing 6

Example of using animation events

div.bounce { -webkit-animation-name: 'bounce'; -webkit-animation-duration: 4s; -webkit-animation-iteration-count: 3; } @-webkit-keyframes 'bounce' { from { top: 100px; -webkit-animation-timing-function: ease-out; }

Animation Events 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

29

Animations

25% { top: 50px; -webkit-animation-timing-function: ease-in; } 50% { top: 100px; -webkit-animation-timing-function: ease-out; } 75% { top: 75px; -webkit-animation-timing-function: ease-in; } to { top: 100px; } } function listenForEnd() { var element = document.getElementById('box'); element.addEventListener('animationend', function(event) { if (event.animationName == 'bounce') element.style.display = 'none'; }, false) } window.addEventListener('load', listenForEnd, false);

An element can have multiple properties being animated simultaneously. This can occur either with a single animation-name value with keyframes containing multiple properties, or with multiple animation-name values. For the purposes of events, each animation-name specifies a single animation. Therefore an event will be generated for each animation-name value and not necessarily for each property being animated. The time the animation has been running is sent with each event generated. This allows the event handler to determine the current iteration of a looping animation or the current position of an alternating animation. This time does not include any time the animation was in the paused play state.

30

Animation Events 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

R E V I S I O N

H I S T O R Y

Document Revision History

This table describes the changes to Safari CSS Animation Guide for iPhone OS. Date

Notes

2008-10-15

Minor edits throughout.

2008-07-11

New document that describes how to use the CSS animation properties.

31 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.

R E V I S I O N

H I S T O R Y

Document Revision History

32 2008-10-15 | © 2008 Apple Inc. All Rights Reserved.