iPhone in Action

SKDatabase 1.1: A SQLite Library for the iPhone

On pp.303-313 of iPhone in Action we talk about SQLite. In the middle of that is an example of a very rudimentary database class for the iPhone, called SKDatabase. It takes the somewhat nonintuitive functions that are built into SQLite3 and turns them into slightly more intuitive methods.

Since the publication of that book, I've dramatically expanded the library for use in my own iPhone Store Apps. I'd always planned to publish it here as another "SDK Class Recipe", but then something new came along: iPhone OS 3.0 and with it support for Core Data, a more robust and better integrated way to store and change data.

Because of the release of  Core Data for the iPhone, I've opted to abandon new work on my SQLite library. However, rather than have it go entirely to waste, I'm publishing it here, for your usage. Understand that even more than normal, this is offered with no guarantees or warranties.

I haven't really dug through the library to polish it up. I also don't believe that it row lookup methods work correctly if one or more of the columns is actually a calculation (like MAX, SUM, COUNT). Finally, I haven't made sure that every parallel method exists.

I will say that it seems stable and that I did use it in a program released through the App Store, so it's probably a fine starting place if you want to do SQLite work of your own.

Here's a zip file of the library:
Download SKDatabase

Core Data v. SQLite

Before I get into the API for my SQLite Library, I want to briefly address the question of whether you should be using Core Data or SQLite.

Core Data is broadly a tool that you can use to manage, store, and recover data. Most of the time you don't set any requirements as to how the back end of Core Data works. It could be a database, or a XML file, or a plain text file. As part of the standard Apple programming paradigm, Core Data comes with an attractive GUI which you can use to set up your data structures. Then you can use some standard APIs to access and retrieve your data.

I generally think that Core Data is scads more complex than SQLite. There are all sorts of abstractions with weird names. I don't find it very programmer friendly to learn. However, learning should be a one-time process, so if you're planning to spend a lot of time programming on iPhones you can amortize your educational costs.

The benefit is that I expect Core Data to be more robust and better able to take advantage of the specific hardware of the iPhone than SQLite. That's why I'm moving over, despite 20+ years of SQL experience going back to CS186 at Berkeley.

You'll need to make that same trade-off calculation when deciding what to use in your own program. If you want to choose the easy route, the quick route, or the one-time use route, then SQLite should still be viable. Use my library here. However if you have the time to spend and want to become an iPhone guru, start learning Core Data instead (and I hope to offer some articles to make that process easier sometime in the future on this blog).

The SQLite3 Library API

If you've stuck around, it's probably because you're planning to use my API for SQLite.Here's all the  methods that are available:

init Methods

- (id)initWithFile:(NSString *)dbFile;
- (id)initWithDynamicFile:(NSString *)dbFile;

There are two ways to create a database object. Use "initWithFile:" if you're just reading from a database and "initWithDynamicFile:" if you are reading and writing. The latter function copies your database from the main bundle to the doc folder if it's not there already, as you can't modify objects in the main bundle folder without corrupting your program's checksum (see iPhone in Action pp.299-300).

It also sets a flag that says you're allowed to make changes to the database. If you try and make a change to a non-dynamic database, your program will crash with a "Tried to use a dynamic function on a static database" error.

Lookup Methods

- (id)lookupColForSQL:(NSString *)sql;
- (NSDictionary *)lookupRowForSQL:(NSString *)sql;
- (NSArray *)lookupAllForSQL:(NSString *)sql;

There are three simple methods that you can use to lookup data using this library. They could be named better. You can lookupCol, which just returns one element of data; you can lookupRow, for multiple columns in the same row; or you can lookupAll, which returns multiple rows which each might contain multiple elements of data.

Note that multiple rows are returned as an NSArray which contains one or more NSDictionaries. The keys for each element in the NSDictionary are set to the database column name of that datum. The type of each element is set as best the library can determine (which is an improvement over the library in the book, where you had to use different method calls to retrieve different sorts of data, but still isn't as robust as it should be; problems figuring out type are why MAX, COUNT, and SUM don't work as part of these larger calls). Expect to see NSNumbers set to floats, ints, or booleans, and NSStrings.

In these and future methods, SQL should be the plain text string of a complete SQL call. It's automatically turned into a prepared statement as part of the lookup method, just as was the case in our simpler example on pp.307-308 of iPhone in Action.

Calculated Lookup Methods

- (int)lookupCountWhere:(NSString *)where forTable:(NSString *)table;
- (int)lookupMax:(NSString *)key Where:(NSString *)where forTable:(NSString *)table;
- (int)lookupSum:(NSString *)key Where:(NSString *)where forTable:(NSString *)table;

If you want to use calculated lookups, the library supports these three single-lookup method calls. For a polished library, I would have offered a few more iterations of these method calls, but for now you got what I used; it'd be easy to expand them.

Rather than requesting full SQL input, these methods put together a complete SQL statement for you. In each case, WHERE is what would go after the WHERE clause of an SQL statement (what Core Data would call a predicate). Count works differently from the rest because it does a COUNT(*) where the others do MAX($key) and SUM($key).

Insert Methods

- (void)insertDictionary:(NSDictionary *)dbData forTable:(NSString *)table;

If you use this method to hand the database class a dictionary where the keys match columns in your database table, it will insert one row of data appropriately.

There's also an insertArray:forTable: method in the code which instead lets you insert an NSArray full of NSDictionary with "key" and "value" entries. I ultimately decided it wasn't as useful as insertDictionary:forTable:, and thus it never even got tested. I've left it in case it's more useful to you, but haven't included it in my API listing because of its entirely untested nature.

Update Methods

- (void)updateDictionary:(NSDictionary *)dbData forTable:(NSString *)table;
- (void)updateDictionary:(NSDictionary *)dbData forTable:(NSString *)table where:(NSString *)where;
- (void)updateSQL:(NSString *)sql forTable:(NSString *)table;

There are three options here. updateSQL:forTable: just allows you to enter your entire update SQL statement. The forTable: argument is redundant, but is included so that the database protocol will work (on which, more shortly). updateDictionary:forTable:where: replaces all the keyed elements in the NSDictionary based on the where statement. Usually you'll set the where statement to define a singular row in your database. updateDictionary:forTable: does it for everything in the table.

Of these three, I used updateSQL:forTable: the most. It's not abstracted like the others, but it was sure easier to write an SQL statement than put together a whole NSDictionary each time. That tends to be a constant war in OOP: simplicity versus abstraction.

There are also updateArray: methods, and I haven't included them in the listing for the same reason as the insertArray: methods: they're totally untested, and I suspect not as useful.

Delete Methods

- (void)deleteWhere:(NSString *)where forTable:(NSString *)table;

There's just one way to delete: you hand off a where predicate, and appropriate rows are removed from the table.

Internal Methods

- (BOOL)runDynamicSQL:(NSString *)sql forTable:(NSString *)table;
- (sqlite3_stmt *)prepare:(NSString *)sql;
- (void)close;

These methods are used only internally, and should be of no interest to you. prepare: is used by just about every other method to create a prepared statement. runDynamicSQL: is used by all the update, insert, and delete method calls, mainly to get all of the SQLite3 and dynamic-testing logic in one place. close is used by dealloc; it shuts down the database.

The Database Delegate Protocol

@protocol SKDatabaseDelegate <NSObject>
@optional
- (void)databaseTableWasUpdated:(NSString *)table;
@end

There is a database protocol which has one optional method: you can be alerted whenever a database table is updated, which is very useful if you've got a UITableview built on the database table in question.

Conclusion

That's the entirety of my SQLite3 library, warts and all. It should generally work, aside from the select issues I mention. If there are more bugs, however, I leave them to you, as I'm no longer actively working on SQLite code.

I hope you find it useful!

Creating a Splash Screen: splashView 1.1

In March I created a splashView class which makes it easy to create a splash screen in your iPhone program. Since then, it's achieved a lot of attention,causing me to put together a slightly revised version of the class, along with some hopefully more straightforward instructions on how to use the class.

They follow, below.

The Code

You can download the new splashView class here: Download SplashView 1.1.

I've also put together a sample project with the splashView already in place. You can find that here: Download NavSample. It builds the splashView into the navigation template. That was chosen pretty arbitrarily; you could put the splashView into any other template, as you see fit.

Below is what you need to know about the class. Most of this, I've copied straight from my earlier article, but updated to correctly describe the usage for the current version of splashView. I'll talk about the changes a bit later.

The Methods

There are just two methods intended for external use.

initWithImage:

- (id)initWithImage:(UIImage *)screenImage;

Give the SplashView a 320x460 image that will be used to fill the screen.

startSplash

- (void)startSplash;

Once you've set all your properties, run this to start the timer of the SplashView going.

The Properties

I filled SplashView with properties, so that you can use it in whatever manner you see fit. Here's a run-down of all of the ones intended to be user accessible:

animation (enum). What sort of animation to show when the SplashView disappears. Options are SplashViewAnimationNone, SplashViewAnimationSlideLeft, and SplashViewAnimationFade. Default is SplashViewAnimationNone (no animation).

animationDelay (NSTimeInterval). How long the animation should run. Default is 1s.

delay (NSTimeInterval). How long the SplashView displays before it disappears. Default is 2s.

delegate (id). What object will listen for splashView's optional delegate protocol.

touchAllowed (BOOL). Whether a user can touch the splash screen to immediately make it disappear (or start animating away). Default is NO.

The Protocol

Sometimes you'll want to know when your splashView closes down. That's what the protocol allows. You just need to set your responding object as the splashView's delegate and have it respond to the splashViewDelegate protocol. This will give you access to one protocol method:

splashIsDone

- (void)splashIsDone;

If you want a reminder on how protocols are used, you should consult iPhone in Action p.179. If you want a reminder on how new protocols are created, you should read Create Delegate Protocols for the iPhone, an earlier article.

Using the Class

If you want to use this class in your program, you can do so under a simple Creative Commons license, which basically says that you'll leave our credits in the comments of the class. Other than that, it's free for your use.

Here's the steps to get it running:

1. Copy the splashView.h and splashView.m files into your program using "Add > Existing Files". When you do so, be sure to check the box that says to physically copy them.
2. Add the QuartzCore framework to your project.
3. Decide which file you're going to activate the splashView from. I suggest the app delegate as the most obvious location for this sort of big-picture content, but I think the splashView is now set up correctly so that you can run it from anywhere.
4. #import "splashView.h" into the appropriate file.
5. Create your 320x460 PNG. I suggest naming it Default.png. Copy it into your program using "Add > Existing Files", again being sure to check the box so that it gets physically copied.
6. Code the splashView startup.

Coding the splashView startup just requires the use of the init and startSplash methods previously noted. Here's a minimalist example:

splashView *mySplash = [[splashView alloc] initWithImage:
        [UIImage imageNamed:@"Default.png"]];
[mySplash startSplash];
[mySplash release];

For a less minimalist example, you'd set some of the properties before running startSplash. If anything isn't clear about how to put these pieces together, you should take a look at the navSample class, linked above.

About Default.png: So why did I suggest using Default.png for the filename? It's because the iPhone will automatically show a file by that name while a program is being loaded. It doesn't do any of the fancy transitions that this class does, nor does it offer any guarantees about how long it'll stay up, but other than that it could be used as a low-budget splash screen (though the purpose was actually to imply that the program was loading faster than it really was).

If you name your image Default.png, then you get the best of both worlds. The PNG will show while the program loads, then the splashView will simultaneously start with your same image, which will eventually transition out via whatever animation method you defined. If you do this, you probably want to tune down the delay once you test it out on a real iPhone, so that users don't feel like they're looking at your splash screen for tool long.

The Changes

I'm going to talk a little bit about the code here, and you might want to first read part two of my original article series, which covers the header file and part three, which covers the source code file. Not only will this give you better context for this update, but it'll also show you the techniques that were used to create the splashView, building on the information from iPhone in Action.

There were two notable changes in this version of splashView.

The first thing I did was improve how the splashView got displayed. In the original version of the program, you had to add the splashView by hand as a subview of the main window. It restricted where you could run splashView, and it also required you to do the right thing or the class wouldn't work.

You'll notice that now you don't add the splashView as a subview at all(!). Somehow, the splashView is magically added to the main window.

It's actually down in the startSplash method, right at the start:

[[[[UIApplication sharedApplication] windows] objectAtIndex:0] addSubview:self];

This takes advantage of the fact that UIApplication has a listing of all the windows, and automatically places splashView atop the first one.

The second thing I did was add the protocol. This methodology is all covered in the creating delegate protocols article I already referenced. After setting up the protocol, I referenced it from dismissSplashFinish:

if (self.delegate != NULL
  && [self.delegate respondsToSelector:@selector(splashIsDone)]) {
    [delegate splashIsDone];
}

As before, if you have questions, comments, or suggestions for improvements, please include them in the comments.

I can't at this time guarantee that the splashView works in iPhone OS 3.0, as I'm currently doing live development on 2.2.1.

Creating a Splash Screen, Part Three

This is the third part of a series covering a "class recipe" for splash screens, providing you with everything you need to quickly incorporate a splash screen into your own programs, using our SplashView class. If you haven't already, you should read the previous articles and download the class files:

• Read Part One
• Read Part Two
• Download SplashView Class

In this third and final article, we're going to be covering the source code file, talking about some of the topics therein that we didn't cover in depth in iPhone in Action.

An Overview of the Source Code

The SplashView class is broadly broken into three parts: the init method, the start method, and the finish methods.

There is very little of note in the initWithImage: class. It primarily exists to create a class object and set all of the object's default properties--which is pretty much the definition of what an init class should do, as we discuss on pp.184-187 of iPhone in Action.

After I started posting this article series, I realized should I should have also written an initWithFrame: method inside SplashView, and actually called that from initWithImage:. This way if a programmer called initWithFrame: they'd get SplashView's method, rather than its parent's method. The result would be slightly more programmer-friendly.

Ah well, I leave that as a bit of programming philosophy at the moment and will update it in v1.1 of the class. (In the meantime if you'd like to see any updates or expansions to the class, let me know in the comments, and I'll be happy to include those as well if they're reasonable and doable.)

The startSplash Method

Though the init method creates a SplashView object, it doesn't actually start it running. This is because I took a page from the book of the UIActivityIndicatorView class (which we demonstrate on pp.340-342). I wanted to give a programmer the opportunity to set properties before I started the animation in motion ... and thus required the programmer to start the SplashView timer after the object has been created.

The startSplash method has one interesting method call it in, the one that starts the timer for the splash screen:

- (void)startSplash {
    splashImage = [[UIImageView alloc] initWithImage:self.image];
    [self addSubview:splashImage];
    [self performSelector:@selector(dismissSplash) withObject:self afterDelay:self.delay]; }

The timer is kicked off by UIView's performSelector:withObject:afterDelay:. This is the simplest possible timer that you can use. It runs the method in question after the selected amount of time has elapsed. You can do much fancier work with the NSTimer and NSRunLoop methods, but this was sufficient for the needs of this class.

The Finishing Methods

The rest of the class is broken into a few different steps. First, "dismissSplash" can be called either by the timer running out or by a user touching the iPhone's screen. If there is no animation scheduled, then dismissSplashFinish immediately gets called; otherwise it gets called when the animation is done.

Most of this work is pretty rudimentary. However, what I want to call special attention to is the use of Core Animation in dismissSplash, which I think shows a better real-world example of how to integrate CA into your programs than the examples we used in the book (which were mainly intended to show how the frameworks worked).

Here's the animation code:

} else if (self.animation == SplashViewAnimationSlideLeft) {
    CABasicAnimation *animSplash
        = [CABasicAnimation animationWithKeyPath:@"transform"];   
    animSplash.duration = self.animationDelay;
    animSplash.removedOnCompletion = NO;
    animSplash.fillMode = kCAFillModeForwards;
    animSplash.toValue = [NSValue valueWithCATransform3D:     
        CATransform3DMakeAffineTransform
            (CGAffineTransformMakeTranslation(-320, 0))];
    animSplash.delegate = self;
    [self.layer addAnimation:animSplash forKey:@"animateTransform"];
} else if (self.animation == SplashViewAnimationFade) {
    CABasicAnimation *animSplash
        = [CABasicAnimation animationWithKeyPath:@"opacity"];
    animSplash.duration = self.animationDelay;
    animSplash.removedOnCompletion = NO;
    animSplash.fillMode = kCAFillModeForwards;
    animSplash.toValue = [NSNumber numberWithFloat:0];
    animSplash.delegate = self;
    [self.layer addAnimation:animSplash forKey:@"animateOpacity"];
}

As you can see, we outlined two different animations here, very similar to the animations we depicted in Listing 19.13 (p.393): a translation and an opacity change. The translation is what allows the SlideLeft animation; creating animations for SlideRight, SlideUp, or SlideDown would be trivial using this as a basis. The opacity change is what allows for the fade out; a similar fade-in animation would be equally simple, though it would require some new infrastructure to allow a front-end animation (whereas all of the current animations are back-end).

We opted to use explicit animations (with CABasicAnimation) because of the extra control they give us. I actually wrote this for the first time as an implicit animation, and when it went too fast, I converted it over.

There are two interesting new elements in this code.

First are the removedOnCompletion and fillMode properties. fillMode determines what an animation does when it's done; the constant kCAFillModeForwards says to leave the animation in its final state; you should consult the fillMode property for other options. However, when an animation is completed, it usually exits ... which would return the screen state to its initial state anyway. That's where removedOnCompletion comes in. It makes sure that the animation sticks around, to keep the screen in its final state (per the fillMode property).

Second, you'll note a call to a delegate. The animation delegate methods are described in the CAAnimation Class Reference as the rest of the animation basics. There are two of them: animationDidStart: and animationDidStop:finished:. It's the latter that's important here, because it allows us to finish shutting down the SplashView class when the animation is done:

- (void)animationDidStop:(CAAnimation *)theAnimation finished:(BOOL)flag {
     [self dismissSplashFinish];
}

And that's a complete look at our new SplashView class, the first of our SDK Class Recipes. Now get out there and use it in your own code!

[5/22/09: Now that you've read all about how the class was created, be sure to go and look at the updated version of the class.]

Creating a Splash Screen, Part Two

In the last article, we discussed the importance of splash screens for iPhone programs

• Read Part One
• Download SplashView Class

If you download the Creative-Commons-licensed class from the previous article, you can begin coding with splash screens immediately. However, we're also going to take the time in this article and the next to discuss some of SplashView's code, particularly paying attention to coding elements that we didn't cover in iPhone in Action.

All About the Header File

This article is going to be all about the header file. To be honest, header files aren't that interesting; there's a reason we very rarely included them in our code snippets in iPhone in Action. However, the SplashView header contains one design element that we didn't discuss in our book, so it deserves some discussion here.

At the start of the header file, before the actual @class definition, you'll find a typedefed enum:

typedef enum {
    SplashViewAnimationNone,
    SplashViewAnimationSlideLeft,
    SplashViewAnimationFade,
} SplashViewAnimation;

A typedef is an entirely standard C feature. It allows you to define a standard variable type with a new name. It's used a lot in the SDK. For example, an NSTimeInterval is really a double with a typedef.

An enum is another standardC  feature, the "enumeration constant." It's essentially a set of #defines, with incrementing value, starting with 0.

When you put these together, you can define a new sort of variable which responds to one of several constants. This methodology is also used throughout the SDK. For example, the UITabBarSystemItem variable, which lets you choose a standard look-and-feel for a tab bar button, is a typedefed enum; there are many more examples.

Thus, if you want to mimic the way the SDK works when you're defining new classes (and generally you should), you want to use a typedefed enum when you're defining a property that can be set to one of a limited number of options. In this case, we wanted to offer an option between a few animation types (with the possibility of more in the future), and so a typedefed enum seemed like an obvious choice.

After you've written your typedef, you can use it to define variables like normal:

SplashViewAnimation animation;

And that typedef is the only element of particular importance in the SplashView header file.

However, we'll also call your attention to the use of properties. There are lots of them, most notably for animation, animationDelay, delay, and touchAllowed, our "public" instance variables. Any class is ultimately a combination of variables and methods, wrapped together; properties let you include those variables in your class while doing almost no extra work.

In this example, the properties are defined in the header file, synthesized in the source code file, and defined (for default values) in the init method. No other code is written, because the synthesis takes care of all our getters and setters for us.

After this rather short look at the header file, we'll get into the guts of SplashView, by looking at the source code file, on Friday.

Creating a Splash Screen, Part One

This article is the first in a new series for the iPhone in Action blog: SDK Class Recipes. In each we'll present a complete class for the SDK that you can immediately copy and use in your own programs. We'll also explain how all the code works, just as we do with our code examples in iPhone in Action.

[5/22/09: Please note, there is now an updated version of this splashView class, which offers slightly improved functionality. I still suggest reading part two and part three of this article, for discussion of how the class was written, but afterward you'll want to jump to the new version for complete installation and usage instructions.]

---

Splash screens are a part of almost any iPhone program. You pop up a screen as your program loads that shows off your program's name, your company's name, and any other information that you want to include, then after a second or two you get rid of it so that you can continue with your actual program.

Because they're so frequently used in iPhone programs, they offer a great opportunity for the creation of a brand-new class that meets the general requires of good iPhone class making. It should be clean, reusable, and dynamic. As a result, we've decided to present our own SplashView class as the first of our SDK Class Recipes. In a three-part article series we're going to: present the interface of the class (along with its actual code); dig through the class' header file; and dig through the class' body of code.

The Code

You can download the code for the Splash Screen class directly: Download SplashView.

That's a Zip file of the class files, splashView.h and splashView.m. We've released them under a Creative Commons attribution license: you're free to use them in any project, commercial or non-commercial, as long as you leave our credits in the code files (which most importantly includes a link to this blog).

We've done our best to create a simple, yet robust and dynamic interface for the SplashView Class. Here's what you need to know about it:

The Methods

There are just two methods intended for external use.

initWithImage:

- (id)initWithImage:(UIImage *)screenImage;

Give the SplashView a 320x460 image that will be used to fill the screen.

startSplash

- (void)startSplash;

Once you've set all your properties, run this to start the timer of the SplashView going.

The Properties

We filled SplashView with properties, so that you can use it in whatever manner you see fit. Here's a run-down of all of the ones intended to be user accessible:

animation (enum). What sort of animation to show when the SplashView disappears. Options are SplashViewAnimationNone, SplashViewAnimationSlideLeft, and SplashViewAnimationFade. Default is SplashViewAnimationNone (no animation).

animationDelay (NSTimeInterval). How long the animation should run. Default is 1s.

delay (NSTimeInterval). How long the SplashView displays before it disappears. Default is 2s.

touchAllowed (BOOL). Whether a user can touch the splash screen to immediately make it disappear (or start animating away). Default is NO.

Using the Class

The first thing you must do to use the class is include the QuartzCore framework, which is required for the animations. If you prefer not to have to include the animation framework, just replace the entirety of the dismissSplash method (in splashView.m) with a call to dismissSplashFinish:

[self dismissSplashFinish];

Afterward, you'll need to copy the class files into your program by whatever method you prefer.

In order to correctly use the SplashView you should run it in your AppDelegate (or somewhere else where you have access to the window property, as you'll want to make the SplashView a subclass of your window). There are four steps required to run your SplashView:

1. init the SplashView with your image
2. Set any SplashView properties
3. Make your SplashView a subview of your window
4. Run startSplash

Here's an example of what you might do, using the Splash screen image that we kicked off this article with:

// #1: Init
splashView *mySplash = [[splashView alloc] initWithImage:
    [UIImage imageNamed:@"rpgnet-splash.png"]];

// #2: Properties
mySplash.animation = SplashViewAnimationFade;
mySplash.touchAllowed = YES;

// #3: Subview
[window addSubview:mySplash];

// #4: startSplash
[mySplash startSplash];

Final Notes

You don't need to know anything else to use the SplashView, and thus create Splash screens for any of your programs. However, in the next two articles we're going to explain the bits of code which go beyond and above the techniques we describe in iPhone in Action. Be back here for those articles this Wednesday and Friday.

In the meantime, we'd love to hear your comments and feature requests for SplashView, as well as your suggestions for future classes that we could offer up as part of an SDK Class Cookbook.