http://cocoadevcentral.com/articles/000084.php
In a nutshell: saving data created by the user
Most applications need a way to save data to disk and bring it back later. In many cases, the best built-in class to use for this is NSKeyedArchiver. It doesn't provide the scalability of a SQL database, but it is incredibly easy to use.
In this tutorial, you'll add saving support to the MailDemo application, which was originally used in the Cocoa Bindings tutorial. It's not necessary to read that tutorial first, but you do need to understand Objective-C and general Cocoa concepts.
Download the project so you can follow along and make the changes as they're described. Note that this is not the finished project, just the starting point. Mac OS X 10.3 (Panther) is required to use this project.
> Download the MailDemo Xcode project 56k
Most Cocoa applications are typically either "regular" or
multi-document. TextEdit, for example, is a multi-documentation application,
whereas AddressBook is not. This tutorial does not discuss multi-document
applications, though the concepts are very similar.
1 of 9
NSKeyedArchiver in a Nutshell
The NSKeyedArchiver class accepts data objects from your application and stores them on disk. It stores the objects in a file as binary data.
Interface Builder, for example, typically stores NIB files in a binary format.
2 of 9
Adding Saving Support to Mailbox
The process of converting objects into binary data is called encoding. Your job is to tell Cocoa how your data should be encoded. Here's the code to add to Mailbox.m to do that:
Mailbox.m
- (void) encodeWithCoder: (NSCoder *)coder
{
[coder encodeObject: properties forKey:@"properties"];
[coder encodeObject: emails forKey:@"emails"];
}
This method adds the Mailbox's data to the NSCoder object that's passed in,
using the The -initWithCoder: method is called when data is being loaded back from disk. Here's the version of that method to put in Mailbox.m:
- (id) initWithCoder: (NSCoder *)coder
{
if (self = [super init])
{
[self setProperties: [coder decodeObjectForKey:@"properties"]];
[self setEmails: [coder decodeObjectForKey:@"emails"]];
}
return self;
}
Finally, change Mailbox.h to indicate that the Mailbox class now conforms to the NSCoding protocol:
Mailbox.h
@interface Mailbox : NSObject <NSCoding>
That's all we need to do in this file.
3 of 9
Adding Saving Support to Email
Here's the code to add to Email.m to enable saving for the Email class:
Email.m
- (void) encodeWithCoder: (NSCoder *)coder
{
[coder encodeObject: properties forKey:@"properties"];
}
Here's the code to enable loading from disk:
- (id) initWithCoder: (NSCoder *)coder
{
if (self = [super init])
{
[self setProperties: [coder decodeObjectForKey:@"properties"]];
}
return self;
}
This code is nearly identical to the methods added to Mailbox. The difference is that
there's one less instance variable to store.
Just as before, add NSCoding to Email.h:
Email.h
@interface Email : NSObject <NSCoding>
We're now done with this file.
4 of 9
Declare New Methods in MyController.h
We'll create three new methods to MailDemo's MyController class to support saving. Add these declarations to the MyController.h file:
MyController.h
- (NSString *) pathForDataFile;
- (void) saveDataToDisk;
- (void) loadDataFromDisk;
The first method returns the destination path of the data file. The other two
methods are used to save and load the data, respectively.
5 of 9
Choosing the File Location
Before an application can save, the developer must select a location for the data. Mac OS X applications generally store such things in ~/Library/Application Support/<Application>/. The application must create that directory if it doesn't already exist.Here's the code to add to MyController.m to do all of this:
MyController.m
- (NSString *) pathForDataFile
{
NSFileManager *fileManager = [NSFileManager defaultManager];
NSString *folder = @"~/Library/Application Support/MailDemo/";
folder = [folder stringByExpandingTildeInPath];
if ([fileManager fileExistsAtPath: folder] == NO)
{
[fileManager createDirectoryAtPath: folder attributes: nil];
}
NSString *fileName = @"MailDemo.cdcmaildemo";
return [folder stringByAppendingPathComponent: fileName];
}
On the first line of this method, we set up an instance of NSFileManager. Many of the
file-related tasks that you would typically do by hand with the Finder can be accomplished
using NSFileManager.
Next, we create an NSString named folder, and set it to the path of the destination folder.
The next line is a bit tricky in that it re-assigns the folder variable to a different version of the same string. The -stringByExpandingTildeInPath method returns a version of the folder path with the tilde replaced by the user's home directory, such as "/Users/scott".
On the next line, we ask NSFileManager if the folder already exists. If it doesn't, we request that it is created by sending the -createDirectoryAtPath:attributes: message.
Finally, we append the file name to the folder path and return the complete path.
6 of 9
Archiving the Data
Now that you have added the NSCoding methods to the data classes, you can ask NSKeyedArchiver to write your objects to disk. You only need to tell the archiver about your top-level objects. In this case, the term "top level" just means the objects which are listed as instance variables in MyController.h.The only top-level object for the MyController class is the "mailboxes" array. Here's the code to add to MyController.m to save the array (and everything it contains) to disk:
MyController.m
- (void) saveDataToDisk
{
NSString * path = [self pathForDataFile];
NSMutableDictionary * rootObject;
rootObject = [NSMutableDictionary dictionary];
[rootObject setValue: [self mailboxes] forKey:@"mailboxes"];
[NSKeyedArchiver archiveRootObject: rootObject toFile: path];
}
On the first line, we retrieve the destination file path. After that, we create an
NSMutableDictionary and place the mailboxes array in it. If you have other
top-level objects, add them to this dictionary.
This dictionary is considered the "root object" -- a master object which contains a tree of all other data objects. We pass this dictionary to NSKeyedArchiver in the +archiveRootObject:toFile: class method.
7 of 9
How Archiving Works
Once NSKeyedArchiver receives the +archiveRootObject:toFile: message, it recursively calls
8 of 9
Reloading Data at Startup
Now we will implement a method in MyController.m to load the data from disk:
MyController.m
- (void) loadDataFromDisk
{
NSString * path = [self pathForDataFile];
NSDictionary * rootObject;
rootObject = [NSKeyedUnarchiver unarchiveObjectWithFile:path];
[self setMailboxes: [rootObject valueForKey:@"mailboxes"]];
}
This is essentially the reverse of the saving method. Once again, we retrieve the path to
the file and create a dictionary which will serve as the root object.
This time, though, we're talking to the NSKeyedUnarchiver class, which is similar to NSKeyedArchiver, but specializes in loading data from disk. We send it the
After that, it's just a matter of using -setMailboxes to repopulate the mailboxes array with the saved data.
9 of 9
Automating Save and Reload
MailDemo can now save and reload data, but the process should ideally be transparent to the user. We only need to add a few lines of code to MyController.m to make that happen:
MyController.m
- (void) awakeFromNib
{
[NSApp setDelegate: self];
[self loadDataFromDisk];
}
The -setDelegate message registers MyController to be the application delegate.
It's possible to do this in Interface Builder as well.
The next line of code simply calls -loadDataFromDisk. Since MailDemo uses Cocoa bindings, the table views are automatically updated after the data is loaded.
To complete the cycle, we need to make sure the data is saved when the application quits. To do this, add the -applicationWillTerminate delegate method show below:
- (void) applicationWillTerminate: (NSNotification *)note
{
[self saveDataToDisk];
}
We're all set! Build and run the project. You should see that your data stays intact between
sessions. If you encountered any difficulties, go back and repeat the steps above.
Wrap Up
We've added NSCoding support to the data classes and saving support to the application. Implementing encoding also sets your application up to support copy/paste and drag-and-drop. Both are typically accomplished by writing encoded objects to the pasteboard.> Download the Finished MailDemo Xcode project 57k
As always, let us know what you think about the tutorial.
No comments:
Post a Comment