FTUtils iPhone Utility Code Library

The code in FTUtils is common utility code extracted from Free Time Studios iPhone projects. Currently, there is only one primary utility (FTAnimationManager) and some simple preprocessor macros. Some unit tests exist for the code, but more are needed. The documentation is also still under development.

Setting Up FTUtils

FTUtils is most easily used by simply copying FTUtils.h, FTAnimationManager.h and FTAnimationManager.m into your project. Be sure to add the QuartzCore framework to your project as well (step 5 below). The preferred way to integrate FTUtils into your projects is by adding it as a static library. This will keep it separate from your code.

The following is the process to add the FTUtils static library to your Xcode project (these steps were borrowed from the three20 project and modified):

1. Clone the ftutils git repository: git clone git://github.com/neror/ftutils.git. Make sure you store the repository in a permanent place because Xcode will need to reference the files every time you compile your project.

   1(a). If you are already using git to manage your source files, you can also add the ftutils repository as a submodule to your project.

2. Locate the "FTUtils.xcodeproj" file under "ftutils". Drag FTUtils.xcodeproj and drop it onto the root of your Xcode project's "Groups and Files" sidebar. A dialog will appear -- make sure "Copy items" is unchecked and "Reference Type" is "Relative to Project" before clicking "Add".

3. Now you need to link the FTUtils static library to your project. Click the "FTUtils.xcodeproj" item that has just been added to the sidebar. Under the "Details" table, you will see a single item: libFTUtils.a. Check the checkbox on the far right of libFTUtils.a.

4. Now you need to add FTUtils as a dependency of your project, so Xcode compiles it whenever you compile your project. Expand the "Targets" section of the sidebar and double-click your application's target. Under the "General" tab you will see a "Direct Dependencies" section. Click the "+" button, select "FTUtils", and click "Add Target".

5. Now you need to add the Core Animation framework to your project. Right click on the "Frameworks" group in your project (or equivalent) and select Add > Existing Frameworks. Then locate QuartzCore.framework and add it to the project.

6. Finally, we need to tell your project where to find the FTUtils headers. Open your "Project Settings" and go to the "Build" tab. Look for "Header Search Paths" and double-click it. Add the relative path from your project's directory to the "ftutils/Headers" directory.

7. While you are in Project Settings, go to "Other Linker Flags" under the "Linker" section, and add "-ObjC" and "-all_load" to the list of flags.

You're ready to go! Just import the header(s) in your code for the parts of the library you'd like to use. The FTAnimation.h header includes everything in the library. So you can just include it:

#import <FTUtils/FTAnimation.h>

Enjoy! And extra super special thanks to Joe Hewitt for writing these steps out for his three20 project! I don't think I have the patience to pull it off.

Using FTAnimation

FTAnimation was designed to make complex Core Animation based animations simple to create and use. The primary interface into the pre-built animations is a category on UIView. Animating a view is as simple as:

[myView slideInFrom:kFTAnimationBottom duration:.33f delegate:self];

You can also access the CAAnimation instances that power the category methods via the FTAnimationManager singleton like so:

CAAnimation *anim = [[FTAnimationManager sharedManager] slideInAnimationFor:myView direction:kFTAnimationBottom
                                                        duration:.33f delegate:self];

modify it to your satisfaction and/or add it to a CAAnimationGroup and add it to the view's layer when you're ready to use it:

anim.timingFunction = [CAMediaTimingFunction functionWithName:kCAMediaTimingFunctionEaseInOut];
[myView.layer addAnimation:anim forKey:@"MySpecialAnimation"];

See the code for details.

The FTAnimation UIView Category

FTAnimation ships with 13 canned UIView animations for animating the showing and hiding of views in the interface. These animations are all available through a category on the UIView class.

Contributors

FTUtils was written by Nathan Eror (@neror) for use in iPhone games built and distributed by Free Time Studios (@freetimestudios).

License

The MIT License

Copyright (c) 2009 Free Time Studios and Nathan Eror

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.