A Tweening Library for Objective-C
GSTween is now available via CocoaPods!
The documentation is currently being created and will be updated constantly as required.
The instructions will be added soon.
- Xcode 5
- Tested on iOS 6.1 and higher
- ARC
As a first simple example, we want to tween the frame-value of a UIView
to CGRectMake(0, 0, 320, 568)
with a bouncing ease out.
-
Add this import to the top of your file (We need to import the GSTween and the easing we want to use, or we can import all easing header files):
//import GSTween #import <GSTween/GSTween.h> //import all easing header files #import <GSTween/Easings.h>
-
Create a GSTween Object to create and instantly run the animation:
[GSTween tweenWithTarget:self time:3.0f ease:[Bounce easeOut] params:@{ @"frame": @"{{0,0},{320,568}}" }];
In this case we create a tween inside a
UIView
. We set the target to self, the animation time to 3 seconds and adding a bouncing ease out. Next we set the parameters in theNSDictionary
. We want to tween the property frame, so we name the key of the dictionary the same and than we add the value we want to tween to. What you see in this example is the string representation for a CGRect.
Currently you can tween any property that is not readonly of the type CGFloat
, NSInteger
, CGRect
, CGSize
or CGPoint
. If GSTween don't find the property on the target, it will throw you a warning in the log.
Here are some examples how to write the values into the dictionary:
@{ "floatValue": @4.2f };
@{ "integerValue": @42 };
@{ "rectValue": @"{{100, 100}, {200, 200}}" };
@{ @"sizeValue": @"{100, 100}" };
@{ @"pointValue": @"{42, 42}" };
And as a bonus, you can tween as many values as you want in one tween-object:
[GSTween tweenWithTarget:self time:3.0f ease:[Bounce easeOut] params:@{ @"frame": @"{{0,0},{320,568}}", @"floatValue": @4.2f, @"integerValue": @42 }];
There are some special properties to use: x
, y
, width
, height
, frameOrigin
, frameSize
. If you have a UIView
and you have no property named like one of these, GSTween will automatically create a tween of the frame property for you, otherwise it will tween your property as you would expect.
You can choose between the following easings:
- Back (easeIn, easeOut, easeInOut, here you also have some parameters)
- Bounce (easeIn, easeOut, easeInOut)
- Circular (easeIn, easeOut, easeInOut)
- Cubic (easeIn, easeOut, easeInOut)
- Elastic (easeIn, easeOut, easeInOut, here you also have some parameters)
- Expo (easeIn, easeOut, easeInOut)
- Linear (easeNone)
- Quadratic (easeIn, easeOut, easeInOut)
- Quintic (easeIn, easeOut, easeInOut)
- Sine (easeIn, easeOut, easeInOut)
The easings based on the equations of Robert Penner and they are licensed under the BSD License. For more information, go here: http://www.robertpenner.com/easing_terms_of_use.html
But you can also create your own easings or use this easings in your own project. They are block-based and you can easily replace them, or create new ones:
typedef CGFloat (^easeBlock)(CGFloat time);
You can use the following optional parameters in the params-dictionary:
- kGSTweenDelay (CGFloat, default 0.0f)
- Add a delay to the beginning of the tween
- kGSTweenYoYo (BOOL, default NO)
- Add a YoYo-effect to your tween, playing the tween forward and rewind
- kGSTweenAutoStart (BOOL, default YES)
- Prevent the tween from auto-start, you can control with
[tween start]
when you want to start your tween
- Prevent the tween from auto-start, you can control with
- kGSTweenRepeat (NSInteger, default 0)
- Control the number of repeats for a tween, -1 is an endless repeat, 0 is the default
- kGSTweenSpeed (CGFloat, default 1.0f)
- Control the playback speed of your tween or play it backwards (is used for the YoYo-effect)
- kGSTweenOnStart
- A block that is fired when the tween starts
typedef void (^tweenBlock)();
- A block that is fired when the tween starts
- kGSTweenOnUpdate
- A block that is fired when the tween is updated, where progress is the current time elapsed (from 0.0f - 1.0f) and value the easing value (from 0.0f - 1.0f)
typedef void (^updateTweenBlock)(CGFloat progress, CGFloat value);
- A block that is fired when the tween is updated, where progress is the current time elapsed (from 0.0f - 1.0f) and value the easing value (from 0.0f - 1.0f)
- kGSTweenOnComplete
- A block that is fired when the tween stops
typedef void (^tweenBlock)();
- A block that is fired when the tween stops
[GSTween tweenWithTarget:self time:3.0f ease:[Bounce easeOut] params:@{ @"frame": @"{{0,0},{320,568}}", kGSTweenDelay: @2.0f, kGSTweenYoYo: @YES }];
[GSTween tweenWithTarget:self time:3.0f ease:[Bounce easeOut] params:@{ @"frame": @"{{0,0},{320,568}}", kGSTweenDelay: @2.0f, kGSTweenOnUpdate: ^(CGFloat progress, CGFloat value) {
NSLog(@"Current progress: %f", progress);
} }];
You can start, stop, pause or resume a tween
This Library is licensed under the MIT License. Please refer to the LICENSE.txt
for more information.