TweetFollow Us on Twitter

The Road to Code: One for the Archives

Volume Number: 24 (2008)
Issue Number: 07
Column Tag: The Road to Code

The Road to Code: One for the Archives

Archiving objects and document—based applications

by Dave Dribin

One Year Later

This is the thirteenth article in the Road to Code column: happy one—year anniversary! We've covered a lot of ground in the last year, but we've still got the pedal to the metal. There's plenty of pavement left to cover!

In last month's article, I said that we'd talk more about NSTableView in this article, but I've decided to put that topic off for a bit. This month we're going to cover document—based applications, which includes how to save and open – or load – custom file types.

Document—based applications are a class of Mac OS X applications that allow the user to create, save, and open documents. Since this is a common type of application, Cocoa provides a lot of the common architecture, or plumbing, to minimize the amount of code the developer has to write.

Archiving

Before we talk about the user interface help that Cocoa provides for document—based applications, we're going to start from the back—end and talk about saving and loading objects. The Foundation framework provides a mechanism for converting a collection of objects to a sequence of bytes called archiving. Once we have the objects as a sequence of bytes, these bytes can be stored on disk or even sent across the network. To recreate the collection of objects from the sequence of bytes, you can use a mechanism called unarchiving. In Java, this conversion of objects to and from bytes is called serialization.

Before we get into the nitty—gritty, we need to cover some more terminology. A collection of objects has a fancy name called object graph. An object graph is a collection of objects, along with the relationship between the objects. An object graph can be represented as a diagram showing each object, with arrows indicating relationships. For example, if we have an NSMutableArray object that contains three Rectangle objects, the object graph would look like Figure 1. The arrows point from the array to the rectangles because the array maintains a reference to each of its members. Often, an object graph contains one object that is at the top of the graph called the root object. In this case, the array is the root object.


Figure 1: Simple object graph

Recall from the article about inheritance, You Have Your Mother's Eyes, that Objective—C has a concept called a protocol. As a quick refresher, protocols are just like class interface declarations, except that there are no instance variables. Protocols also have no implementation. Other classes may implement protocols, and these classes must provide implementations to all required methods. Protocols are used to ensure a class implements a set of methods.

Encoding

Foundation's archiving and unarchiving works on object graphs. Not all objects may be archived, however. Only objects that implement the NSCoding protocol may be archived and unarchived. The NSCoding protocol is shown in Listing 1.

Listing 1: NSCoding protocol

@protocol NSCoding
— (void)encodeWithCoder:(NSCoder *)coder;
— (id)initWithCoder:(NSCoder *)decoder;
@end

The encodeWithCoder: method is used for archiving while initWithCoder: is used for unarchiving. You'll notice that both of these methods use a class called NSCoder. NSCoder and its subclasses are responsible for the actual transformation to and from bytes. An example will help clear this up. Let's modify our Rectangle class to work with archiving. The most recent interface for Rectangle from the last article is shown in Listing 2.

Listing 2: Rectangle interface, without NSCoding support

#import <Foundation/Foundation.h>
@interface Rectangle : NSObject
{
    float _leftX;
    float _bottomY;
    float _width;
    float _height;
}
@property float leftX;
@property float bottomY;
@property float width;
@property float height;
@property (readonly) float area;
@property (readonly) float perimeter;
— (id)    initWithLeftX: (float) leftX
                bottomY: (float) bottomY
                 rightX: (float) rightX
                   topY: (float) topY;
@end

Since Rectangle's superclass, NSObject, does not implement the NSCoding protocol, the first step is to tell the compiler that we want to implement the NSCoding by changing the @interface declaration:

@interface Rectangle : NSObject <NSCoding>

The rest of the header file stays the same. We must now implement encodeWithCoder: and initWithCoder: or else the compiler will warn us about an incomplete implementation. This warning is very helpful and one of the benefits of statically typed languages. Okay, so how do we implement these methods? Let's start with archiving and encodeWithCoder:.

When encodeWithCoder: is called on your object, you need to save all your vital instance variables by encoding their values in the coder. Vital instance variables are all instance variables that cannot be calculated in any way. For our Rectangle class, all four instance variables are vital, and we must encode them all. Our implementation would be:

— (void) encodeWithCoder: (NSCoder *) coder
{
    [coder encodeFloat: _leftX forKey: @"leftX"];
    [coder encodeFloat: _bottomY forKey: @"bottomY"];
    [coder encodeFloat: _width forKey: @"width"];
    [coder encodeFloat: _height forKey: @"height"];
}

We encode each of our instance variables, one by one, using the encodeFloat:forKey: method of NSCoder. We are using a variant of encoding called keyed encoding. Keyed encoding associates each value with a string key, or name, similar to how NSDictionary maps keys and values. All keys in an inheritance chain must be unique. This means your key must not only be unique to all your encoded values, but also to any of your superclasses' encoded values. The simplest way to ensure this is to use the name of the instance variable. I tend to leave off the underscore prefix, but that's just old habit. Separate inheritance chains can reuse keys. For example a Bitmap class that inherits from NSObject could also encode values using the width and height keys without conflict from Rectangle.

There are encoding methods for all primitive types and for other objects that implement the NSCoding protocol. Many of the classes in the Foundation framework such as strings, arrays, and dictionaries implement NSCoding so you should be able to easily encode all of your instance variables. Don't forget that if your superclass implements NSCoding, you must call encodeWithCoder: on the superclass before you encode your instance variables to make sure that all of its instance variables are encoded, as well:

— (void) encodeWithCoder: (NSCoder *) coder
{
    [super encodeWithCoder: coder];
    //...
}

As a side note, NSCoder does allow encoding values without keys, called non—keyed encoding, however this method is no longer recommended. Keyed encoding was introduced in Mac OS X 10.2 and non—keyed encoding should only be used for legacy applications that either need to run on or interoperate with old versions of software. Since we are writing an application for Mac OS X 10.5, we only use keyed encoding.

To use this method, we need an NSCoder instance. NSCoder is an abstract class, meaning that you cannot create instances of it directly; rather, you should use one of its concrete subclasses. The main subclass for encoding is NSKeyedArchiver, and typically, you use one of its class methods that do all the hard work for you:

    Rectangle * rectangle = ...;
    NSData * data =
        [NSKeyedArchiver archivedDataWithRootObject: rectangle];

The NSData class is part of the Foundation framework and it holds a sequence of bytes. Once you have the rectangle represented as an NSData instance, you can write it to disk or send it over a network.

Decoding

Now that we've covered archiving objects by encoding objects with an NSCoder instance, we need to go the other way around. Unarchiving objects takes a sequence of bytes and creates new instances of the encoded objects. To support unarchiving, our class must implement the initWithCoder: method. For our Rectangle class, there are no real surprises. We must decode each instance variable using the same key we used for encoding:

— (id) initWithCoder: (NSCoder *) decoder
{ 
    self = [super init];
    if (self == nil)
        return nil;
    
    _leftX = [decoder decodeFloatForKey: @"leftX"];
    _bottomY = [decoder decodeFloatForKey: @"bottomY"];
    _width = [decoder decodeFloatForKey: @"width"];
    _height = [decoder decodeFloatForKey: @"height"];
    
    return self;
}

Note that this is a constructor method and thus creates a new instance of our object. Since our superclass is NSObject and it does not implement NSCoding, we just call init. However, if your superclass also supports NSCoding, be sure to call initWithCoder: instead:

— (id) initWithCoder: (NSCoder *) decoder
{ 
    self = [super initWithCoder: decoder];
    //...
}

While you can decode the keys in any order, it's imperative that the keys match up between your encoding and decoding. Also, if you decode any objects, you must remember to retain them if you keep strong references to them as the decodeObjectForKey: returns autoreleased objects. Of course, if you are using garbage collection, you don't have to worry about the retains.

To unarchive objects from a sequence bytes created with NSKeyedArchiver, you should use the NSKeyedUnarchiver, which is also a concrete subclass of NSCoder. It has a convenient class method to unarchive an object directly from an NSData instance:

    NSData * data = ...;
    Rectangle * rectangle =
        [NSKeyedUnarchiver unarchiveObjectWithData: data];

Now that our Rectangle class fully implements the NSCoding protocol, we can convert instances of our class to a sequence of bytes and back again.

Archiving objects has many uses. For example, Interface Builder nib files are really just archived objects. The object graph for your entire GUI is created by Interface Builder and saved as a nib file. When your application runs, the objects are unarchived and ready to use. We will also be using this new ability to create custom rectangle documents using a document—based application.

You may be wondering what happens if we add or remove instance variables to our rectangle class? And what if the newer rectangle class needs to read archives saved by the older rectangle class? The way to handle this is with a technique called versioning. Versioning is a bit advanced to cover in full here, but I just wanted to let you know that it is possible to handle this situation. Read Apple's developer documentation for full details.

Document—Based Applications

As I mentioned above, many applications allow the user to create and edit documents, and then save them to and open them from disk. Since this is such a common type of application, Cocoa provides an architecture to help with the common tasks of managing documents. Applications that utilize this architecture are called document—based applications. The three classes that make up this architecture are NSDocument, NSWindowController, and NSDocumentController and are found in the Application Kit framework, along with all the GUI classes such as NSView and NSControl.

For simple cases, you generally don't have to interact with NSWindowController or NSDocumentController. However, you must always subclass NSDocument to implement saving and loading. We're going to walk through a simple document—based application that allows a user to save and load rectangle data.

Xcode has a project template for document—based applications, so we're going create a fresh project from this template. Select File > New ProjectÉ from Xcode and choose a Cocoa Document—based Application from the New Project assistant, as shown in Figure 2. Click Next, and create a project named Rectangles in the directory of your choice. Finally, enable garbage collection by modifying the project's build settings.


Figure 2: Creating a document—based application

If you take a look at the Groups & Files list for this project, you'll notice that it is slightly different than the non—document—based applications we've created so far, as shown in Figure 3. First, it creates a subclass of NSDocument called MyDocument for us in the Classes group. Second, it creates two nib files in the Resources group: MainMenu.nib and MyDocument.nib.


Figure 3: Generated files

We've previously only used a single nib file that contained both the main menu and the single application window. Because we can have multiple document windows open, we use a separate nib file for document windows. Remember that nib files are archived windows, views, and controls, so every time a new document window is created, Cocoa's document architecture unarchives MyDocument.nib to create a new window. The MainMenu.nib file only gets loaded once at application startup and contains only the menu bar items.

You can already run the application as—is, but it's quite limited. First, the window contains a nice message that you are supposed to add your own controls to it. Also, saving and loading are not implemented, and you get an error if you try and save. You can, however, create new documents using File > New or Command—N.

Creating the User Interface

We're going to start by making the document window look just like the window of our Hello World application. Figure 4 shows the final result. Open MyDocument.nib with Interface Builder and layout the controls and formatters like we did before. Also setup the proper resizing springs and struts. (See last month's article if you need a reminder of how to do this.)


Figure 4: MyDocument.nib window

The MyDocument class takes the place of HelloWorldController from the previous articles. It contains all the outlets and actions for the window. Add outlets for the four text fields, a calculate action, and an instance variable for a single rectangle, as shown in Listing 3:

Listing 3: MyDocument.h

#import <Cocoa/Cocoa.h>
@class Rectangle;
@interface MyDocument : NSDocument
{
    IBOutlet NSTextField * _widthField;
    IBOutlet NSTextField * _heightField;
    IBOutlet NSTextField * _areaLabel;
    IBOutlet NSTextField * _perimiterLabel;
    
    Rectangle * _rectangle;
}
— (IBAction)calculate:(id)sender;
@end

Now save MyDocument.h, and go back to Interface Builder. Connect up the outlets and actions to the appropriate controls. The File's Owner is setup to be our document class, MyDocument, so use this when connecting the outlets and actions.

Now, add the Rectangle class that we modified to support NSCoding protocol above to this project. In MyDocument, change the init method, and add the calculate: and updateAreaAndPerimeter methods to match this:

— (id)init
{
    self = [super init];
    if (self == nil)
        return nil;
    
    _rectangle = [[Rectangle alloc]    initWithLeftX: 0
                                             bottomY: 0
                                              rightX: 5
                                                topY: 10];
    
    return self;
}
— (void)updateAreaAndPerimeter
{
    [_areaLabel setFloatValue: _rectangle.area];
    [_perimiterLabel setFloatValue: _rectangle.perimeter];
}
— (IBAction)calculate:(id)sender
{
    _rectangle.width = [_widthField floatValue];
    _rectangle.height = [_heightField floatValue];
    [self updateAreaAndPerimeter];
}

This creates a new rectangle instance in the constructor and also implements the calculate: action. Remember, though, that we needed to implement the awakeFromNib to ensure the text fields and labels were correct on application launch. For NSDocument subclasses, you override the windowControllerDidLoadNib: instead of awakeFromNib. Their purpose is very similar, though, and allows you to execute code after the outlets and actions from the nib have been connected. Modify the supplied stub implementation to match this:

— (void)windowControllerDidLoadNib:(NSWindowController *) aController
{
    [super windowControllerDidLoadNib:aController];
    [_widthField setFloatValue: _rectangle.width];
    [_heightField setFloatValue: _rectangle.height];
    [self updateAreaAndPerimeter];
}

Now build and run the application. You should see a window similar to Figure 5. The initial width should be five and height should be ten. If you change the width or height and press the Calculate button, the area and perimeter should update accordingly.


Figure 5: Running document window

This works like our first Hello World application. However, you can now create new windows with the File > New menu. We now want to implement saving and loading of documents.

Registering File Extensions

In order to identify our new file types, we need to come up with a new file extension. Since our document contains a single rectangle, let's use ".rectangle" as our file extension. We need to tell the operating system that our application can load and save files with this extension. This is done by editing the properties of our application. Open up the Targets group in the Groups & Files section of the project. Double click on the Rectangles target to bring up the Info panel for our application. Change to the Properties tab of the Info panel.

There are a couple of important properties we need to change. First, we need to change the identifier. Identifiers must be unique for every application released on Mac OS X. The recommended way to do this uses so—called reverse DNS notation. DNS is how websites are named. For example, my personal website is at www.dribin.org. The technical name for this website address is the DNS name. DNS names are unique, i.e. there is one and only one dribin.org out there. Reverse DNS takes advantage of the uniqueness of website names. It's called reverse DNS because you list the components in the opposite order that you use them for websites. The default value is com.yourcompany.Rectangles, which may be fine for testing, but you should really change it to a properly unique name.

Let's change it to org.dribin.dave.mactech.jul08.rectangles.

Next, we need to change the document types for our application. The Document Types list should already have one document type in it. Edit it so that the name is Rectangle File and that the extension is rectangle (do not include the period). The final result should look similar to Figure 6.


Figure 6: Application properties

These application properties are stored in a file called Info.plist. You can see this file in the Resources group. This file gets included along with your built application. How this works is beyond the scope of this article, but suffice it to say that applications on Mac OS X are really directories with a special structure called bundles. We will talk more about bundles in a later article.

One word of warning: I find that whenever I change the application's properties or Info.plist file, I need to force Xcode to rebuild the whole application. You do this by using the Build > Clean All Targets menu item. Cleaning removes all files generated during the build process. By cleaning the target, you force the next build to rebuild everything. Be sure to clean your project before proceeding.

Saving and Loading

With our file extension in place, we can now proceed to implement saving and loading of rectangle files. The MyDocument class already contains stub methods for saving and loading that we need to fill in. Saving is handled by the dataOfType:error: method. You are supposed to return an NSData representation of your document, and the document architecture will take care of writing it to a file. The default implementation returns nil and sets an error.

The only data we need to save is our _rectangle instance variable. Since the Rectangle class now implements the NSCoding protocol, we can use an NSKeyedArchiver to convert our instance variable into NSData:

— (NSData *)dataOfType:(NSString *)typeName
                 error:(NSError **)outError
{
    NSData * rectangleData =
        [NSKeyedArchiver archivedDataWithRootObject:_rectangle];
    return rectangleData;
}

In order to load rectangle files, we need to implement the readFromData:ofType:error: method. We can use NSKeyedArchiver to convert the supplied NSData to an NSRectangle and store it in our instance variable:

— (BOOL)readFromData:(NSData *)data
              ofType:(NSString *)typeName
               error:(NSError **)outError
{
    _rectangle = [NSKeyedUnarchiver unarchiveObjectWithData:data];
    return YES;
}

If you are not using garbage collection, be sure to release the old rectangle and retain the new one.

With these two methods implemented, you should be able to save and open rectangle files. Give it a shot. The files should have the ".rectangle" extension we setup, too. You can even double click on saved rectangle files in the Finder, and it should automatically launch our application. As always, the completed project may be downloaded from the MacTech website.

Well, that's pretty much all there is to a document—based application. Due to the document architecture, there's really not that much extra code to write compared to non—document—based applications. Our MyDocument class is very similar to the HelloWorldController we wrote earlier. We just needed to add methods to save and load files, and that's really easy if the classes to be saved can be archived.

Given that we only had to implement two extra methods, we get a lot of functionality "for free" from the Cocoa document architecture:

A file open sheet is created when the user chooses File > OpenÉ

A file save sheet is created when the user choose File > Save or Save AsÉ

Saving and loading to and from disk is handled automatically

The window title changes to the name of the document

The document—based architecture really shows how Cocoa helps the developer write applications faster with less code. You can also get undo support easily, but that will have to wait for a future article.


Dave Dribin has been writing professional software for over eleven years. After five years programming embedded C in the telecom industry and a brief stint riding the Internet bubble, he decided to venture out on his own. Since 2001, he has been providing independent consulting services, and in 2006, he founded Bit Maki, Inc. Find out more at http://www.bitmaki.com/ and http://www.dribin.org/dave/.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Latest Forum Discussions

See All

Whitethorn Games combines two completely...
If you have ever gone fishing then you know that it is a lesson in patience, sitting around waiting for a bite that may never come. Well, that's because you have been doing it wrong, since as Whitehorn Games now demonstrates in new release Skate... | Read more »
Call of Duty Warzone is a Waiting Simula...
It's always fun when a splashy multiplayer game comes to mobile because they are few and far between, so I was excited to see the notification about Call of Duty: Warzone Mobile (finally) launching last week and wanted to try it out. As someone who... | Read more »
Albion Online introduces some massive ne...
Sandbox Interactive has announced an upcoming update to its flagship MMORPG Albion Online, containing massive updates to its existing guild Vs guild systems. Someone clearly rewatched the Helms Deep battle in Lord of the Rings and spent the next... | Read more »
Chucklefish announces launch date of the...
Chucklefish, the indie London-based team we probably all know from developing Terraria or their stint publishing Stardew Valley, has revealed the mobile release date for roguelike deck-builder Wildfrost. Developed by Gaziter and Deadpan Games, the... | Read more »
Netmarble opens pre-registration for act...
It has been close to three years since Netmarble announced they would be adapting the smash series Solo Leveling into a video game, and at last, they have announced the opening of pre-orders for Solo Leveling: Arise. [Read more] | Read more »
PUBG Mobile celebrates sixth anniversary...
For the past six years, PUBG Mobile has been one of the most popular shooters you can play in the palm of your hand, and Krafton is celebrating this milestone and many years of ups by teaming up with hit music man JVKE to create a special song for... | Read more »
ASTRA: Knights of Veda refuse to pump th...
In perhaps the most recent example of being incredibly eager, ASTRA: Knights of Veda has dropped its second collaboration with South Korean boyband Seventeen, named so as it consists of exactly thirteen members and a video collaboration with Lee... | Read more »
Collect all your cats and caterpillars a...
If you are growing tired of trying to build a town with your phone by using it as a tiny, ineffectual shover then fear no longer, as Independent Arts Software has announced the upcoming release of Construction Simulator 4, from the critically... | Read more »
Backbone complete its lineup of 2nd Gene...
With all the ports of big AAA games that have been coming to mobile, it is becoming more convenient than ever to own a good controller, and to help with this Backbone has announced the completion of their 2nd generation product lineup with their... | Read more »
Zenless Zone Zero opens entries for its...
miHoYo, aka HoYoverse, has become such a big name in mobile gaming that it's hard to believe that arguably their flagship title, Genshin Impact, is only three and a half years old. Now, they continue the road to the next title in their world, with... | Read more »

Price Scanner via MacPrices.net

B&H has Apple’s 13-inch M2 MacBook Airs o...
B&H Photo has 13″ MacBook Airs with M2 CPUs and 256GB of storage in stock and on sale for up to $150 off Apple’s new MSRP, starting at only $849. Free 1-2 day delivery is available to most US... Read more
M2 Mac minis on sale for $100-$200 off MSRP,...
B&H Photo has Apple’s M2-powered Mac minis back in stock and on sale today for $100-$200 off MSRP. Free 1-2 day shipping is available for most US addresses: – Mac mini M2/256GB SSD: $499, save $... Read more
Mac Studios with M2 Max and M2 Ultra CPUs on...
B&H Photo has standard-configuration Mac Studios with Apple’s M2 Max & Ultra CPUs in stock today and on Easter sale for $200 off MSRP. Their prices are the lowest available for these models... Read more
Deal Alert! B&H Photo has Apple’s 14-inch...
B&H Photo has new Gray and Black 14″ M3, M3 Pro, and M3 Max MacBook Pros on sale for $200-$300 off MSRP, starting at only $1399. B&H offers free 1-2 day delivery to most US addresses: – 14″ 8... Read more
Department Of Justice Sets Sights On Apple In...
NEWS – The ball has finally dropped on the big Apple. The ball (metaphorically speaking) — an antitrust lawsuit filed in the U.S. on March 21 by the Department of Justice (DOJ) — came down following... Read more
New 13-inch M3 MacBook Air on sale for $999,...
Amazon has Apple’s new 13″ M3 MacBook Air on sale for $100 off MSRP for the first time, now just $999 shipped. Shipping is free: – 13″ MacBook Air (8GB RAM/256GB SSD/Space Gray): $999 $100 off MSRP... Read more
Amazon has Apple’s 9th-generation WiFi iPads...
Amazon has Apple’s 9th generation 10.2″ WiFi iPads on sale for $80-$100 off MSRP, starting only $249. Their prices are the lowest available for new iPads anywhere: – 10″ 64GB WiFi iPad (Space Gray or... Read more
Discounted 14-inch M3 MacBook Pros with 16GB...
Apple retailer Expercom has 14″ MacBook Pros with M3 CPUs and 16GB of standard memory discounted by up to $120 off Apple’s MSRP: – 14″ M3 MacBook Pro (16GB RAM/256GB SSD): $1691.06 $108 off MSRP – 14... Read more
Clearance 15-inch M2 MacBook Airs on sale for...
B&H Photo has Apple’s 15″ MacBook Airs with M2 CPUs (8GB RAM/256GB SSD) in stock today and on clearance sale for $999 in all four colors. Free 1-2 delivery is available to most US addresses.... Read more
Clearance 13-inch M1 MacBook Airs drop to onl...
B&H has Apple’s base 13″ M1 MacBook Air (Space Gray, Silver, & Gold) in stock and on clearance sale today for $300 off MSRP, only $699. Free 1-2 day shipping is available to most addresses in... Read more

Jobs Board

Medical Assistant - Surgical Oncology- *Apple...
Medical Assistant - Surgical Oncology- Apple Hill Location: WellSpan Medical Group, York, PA Schedule: Full Time Sign-On Bonus Eligible Remote/Hybrid Regular Apply Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Business Analyst | *Apple* Pay - Banco Popu...
Business Analyst | Apple PayApply now " Apply now + Apply Now + Start applying with LinkedIn Start + Please wait Date:Mar 19, 2024 Location: San Juan-Cupey, PR Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.