Skip to content

Commit b6d6b28

Browse files
committed
[SpritedAnimationView] Updates readme.
Reviewers: ajsecord, #material_components_ios_owners Projects: #material_components_ios_owners Differential Revision: http://codereview.cc/D69
1 parent c344f10 commit b6d6b28

File tree

1 file changed

+53
-5
lines changed

1 file changed

+53
-5
lines changed

components/SpritedAnimationView/README.md

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,64 @@
11
# SpritedAnimationView
22

3-
This control provides an alternative to animating an array of images with a UIImageView. Only
4-
a single image composed of individual sprite frames is used, and animation simply consists of
5-
updating the layer contentsRect.
3+
This control provides an alternative to animating an array of images with an `UIImageView`. Only a
4+
single image composed of individual sprite frames is used, and animation simply consists of
5+
updating the layer `contentsRect`.
66

77
## Requirements
88

9-
- Xcode 7.0 or higher.
10-
- iOS SDK version 7.0 or higher.
9+
- Xcode 7.0 or higher
10+
- iOS SDK version 7.0 or higher
11+
12+
## Create a sprite sheet asset
13+
14+
A sprite sheet consists of a single image composed of a single column of individual sprite frames.
15+
The individual sprite frames must be sized and spaced evenly across the overall image bounds. A
16+
typical use case is to generate three sprite sheet images (1x, 2x, and 3x) and add these to an
17+
`.xcassets` file for use in the app by the `spritedAnimationView`.
18+
19+
## Animating the sprite sheet
20+
21+
Once a sprite sheet is added to a `spritedAnimationView` (either at `init` or adding later), the
22+
`spritedAnimationView` can animate the image from the first sprite frame to the last sprite frame.
23+
Properties are available to set the frame rate, which defaults to 60 fps (frames per second). The
24+
animation can happen once or be looped via the `animationRepeatCount` property. To start the
25+
animation, use the `-startAnimationWithCompletion:` method. A completion block gets called once
26+
the animation is finished. However, if the `animationRepeatCount` is set to loop infinitely (with
27+
a 0 setting), this block will not get called. Additional methods are provided to reset the
28+
`spritedAnimationView` to the beginning or end without animation.
29+
30+
## Achieving two-state animation
31+
32+
It is enough to provide a single sprite sheet, animate the image, and simply reset to the beginning
33+
once finished. However, in some cases, a nice user experience can be achieved by providing two
34+
separate sprite sheets. One showing an animation from state A to state B, then another sprite sheet
35+
showing state B going back to state A. This way, the sprite sheet can be swapped out after the
36+
animation completes for each state, and be replaced with the other sprite image.
37+
38+
#### Two sample sprite sheets (showing Hide and Show states)
39+
40+
| Checkmark Sprite Sheet (Hide) | Checkmark Sprite Sheet (Show) |
41+
| :---------------------------: | :---------------------------: |
42+
| ![Checkmark Hide](examples/SpritedAnimationViewExample/Assets.xcassets/mdc_sprite_check__hide.imageset/mdc_sprite_check__hide.png) | ![Checkmark Show](examples/SpritedAnimationViewExample/Assets.xcassets/mdc_sprite_check__show.imageset/mdc_sprite_check__show.png) |
43+
44+
#### Two-state example
45+
46+
```objectivec
47+
// Animate the sprited view.
48+
[_animationView startAnimatingWithCompletion:^{
49+
50+
// When animation completes, toggle image.
51+
_checked = !_checked;
52+
UIImage *spriteImage =
53+
[UIImage imageNamed:_checked ? kSpriteCheckedImage : kSpriteUncheckedImage];
54+
_animationView.spriteSheetImage = spriteImage;
55+
}];
56+
```
1157
1258
## Usage
1359
60+
Integrating the `spritedAnimationView` is somewhat similar to adding an `UIImageView` to a view.
61+
1462
```objectivec
1563
#import "MaterialSpritedAnimationView.h"
1664

0 commit comments

Comments
 (0)