Rick's World

I've been learning Cocoa on OS X lately. One of the things I've been experimenting with is document based applications. I've been working on an application that processes Par and Par2 files. So, in the process of developing this application, I needed to write a document based application to view the contents of the files. The problem is, XCode doesn't prompt you for the name of the document class when you tell it to generate a new Document based application. Instead, it generates a document class called 'MyDocument'. This is obviously not a very useful class name. When XCode generates this MyDocument class, it also generates the MyDocument.nib file and connects everything together for you. The problem is, if you try to rename the document, all those connections break and the document and NIB stop working together. Plus, if you want to generate a second document/NIB, you are on your own. I wanted to document how to manually rename a Document class/NIB so that the connections between them continue to work. For this example, I'll use the example of renaming 'MyDocument' to 'ParDocument' (which is what I did in my application). If you want to use a different class name, just substitute your class name for everywhere that I mention 'ParDocument'.

Generate the new Document class

1. In the File menu, select 'New File'.
2. In the Assistant dialog, choose the 'Objective-C NSDocument subclass' item under 'Cocoa'.
3. Give the new class the filename 'ParDocument.m'. Make sure that the 'Also create "ParDocument.h" is checked.
4. If you view the contents of the ParDocument.m file and look at the 'windowNibName' function, you will see that it returns @"ParDocument". This string returned MUST match the filename of the NIB file that goes with this document. In other words, it will try to load 'ParDocument.nib', since you listed 'ParDocument' as the Nib file name. If you rename the class in the future, you also need to change this string to point to the new Nib file. Since we generated the class, this string is already set correctly.

Generate the new NIB file

1. Open Interface Builder by double clicking on the MyDocument.nib file.
2. In Interface Builder's File menu, choose 'New'.
3. In the 'Starting Point' Dialog, choose 'Window' under the 'Cocoa' item.
4. In Interface Builder's File menu, choose Save As.
5. Make sure that you choose the right directory here! Save it to the 'English.lproj' directory underneath your main application directory.
6. If you save it to this directory, it will then prompt you to add the new NIB file to your project. Tell it to add it to your project.
7. From Interface Builder's Classes menu, choose 'Read Files'
8. Select the 'ParDocument.h' file. This is necessary to tell IB about your Document class.
9. In IB, click on the 'File Owner' icon.
10. In the Tools menu, pick Show Inspector.
11. Choose 'Custom Class' from the Inspector's top drop down list. Select ParDocument as the class.
12. In IB, Control-Drag from the 'Files Owner' icon to the 'Window' icon. Set the 'window' connection to this Window.
13. In IB, Control-Drag from the 'Window' icon to the 'File's Owner' icon. Set the 'delegate' connection to ParDocument.
14. Save and exit IB

Set the Document Class for the Document

1. In XCode, right click on the Target and select Get Info
2. Set the 'Class' column of the list on the bottom to 'ParDocument'

hat's it! Now that everything is connected for your new ParDocument class, you can go ahead and delete MyDocument.h, MyDocument.m and MyDocument.nib from the project.

It's a long, involved, and very confusing process to do this. Hopefully this has helped you.