Rick's World

I have officially started my first open source project. It is a program called Par Explorer. What is Par Explorer? The purpose of it is to allow you to open a PAR or PAR2 file and view all the packets stored in it and the contents of each one. All it does is let you view the data. You can't change it or create it.

I wrote this program more as a testbed for learning how to read PAR/PAR2 files. I'm working on a separate application (not open sourced yet), that will do some more processing of PAR files. The purpose of this application is mostly to develop and test the code to read and process PAR files. It also gives me a chance to learn how to write document based Cocoa apps. PAR files make use of some interesting concepts such as MD5 hashes, CRC32 checksums and Reed-Solomon codes. I'd never done any work with these concepts, so this is something else I'm learning during the development of this program. You can freely view the source for the app over in the Subversion repository on the SourceForge project page, so if you are interested in any of these concepts, take a look. MD5, CRC32 and a large amount of PAR2 code is already there, if you need that. Have fun!

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.

Ok, this truly sucks.

Last night, I was playing with Objective C. I had written an O-C class and tried to include a C++ class as a member variable of the O-C class. Now, you would think this would be possible, since you can create Objective-C++ classes that take advantage of certain C++ features. Apparently, this support of C++ in Objective-C is incomplete at best. I discovered that when I added that C++ class as a member variable, it compiled, but it gave me a warning telling me that the constructor and destructor of that member class would not be called! If the constructor and destructor don't get called, C++ classes are basically useless! What else won't get called on the C++ class in this case? This really sucks. This means that I had to basically rewrite that C++ class as a full Objective-C class in order to use it properly.

This, in my opinion is a glaring hole in the current implementation of Objective-C. It seems inconceivable to me that you can easily include any C code you want, but only certain parts of C++ work in Objective-C. I really hope they fix this in Objective-C 2.0, that is coming Real Soon Now, in Leopard!

A delegate is a kind of 'helper class' in Cocoa. Very often in Cocoa, you won't subclass a class, instead you'll just use the base class and register yourself as a delegate. This means that whenever interesting events happen in the base class, it calls a method on the delegate. The return value of this delegate function allows you to notify the calling class to stop or continue various operations.

Of course, you can create your own classes in Cocoa. This means that there needs to be a way to add support for delegate processing in your custom class. Here are the steps necessary to make this work.

1. Declare the delegate variable and accessor methods in your class' header file. Note that these accessor methods should follow the standard Cocoa Key Value Coding scheme.

   @interface ClassName : NSObject 
   {
       id delegate;
   }
   
   - (void)setDelegate:(id)val;
   - (id)delegate;
   
   @end
   

2. Define the accessor functions in your implementation file.

   @implementation ClassName
   
   - (void)setDelegate:(id)val
   {
       delegate = val;
   }
   
   - (id)delegate
   {
       return delegate;
   }
   
   @end
   

3. Create an informal protocol that contains all the delegate functions that your class will call in the delegate object. This informal protocol is implemented as a Category on the NSObject class. Note that the delegate will work without this step, but if you leave this out, XCode will generate a lot of "warning: no '-XXX' method found" warning messages. Also, your class that acts as the delegate of this class does not have to implement all these delegate functions. It only has to implement the methods that it is interested in. The rest will simply be ignored.

   @interface NSObject (ClassName)
   
   - (void)delegateFunction1;
   - (void)delegateFunction2;
   // etc...
   
   @end
   

4. Before calling a delegate method, make sure the delegate supports that method by using the respondsToSelector: message.

   - (void)someMethod 
   {
       if ( [delegate respondsToSelector:@selector(delegateFunction1:)] ) 
       {
           [delegate delegateFunction1];
       }
   }
   

Here's how to do exceptions in Cocoa... It's nearly identical to C++ exceptions:

@try
{
    // Do some code here that might throw an exception.
}
@catch( NSException* e )
{
    // Log the exception. 
    NSLog( @"Exception: %@, %@", [e name], [e reason] );
}

One important thing to remember when doing these types of exceptions is that it will only work for apps written for OS X 10.3 (Panther) or later. This shouldn't be a problem, though.

Also, in order to get these to work, you need to turn on Objective-C exceptions in the XCode Build settings. The easiest way to do this is to bring up the Project Info dialog box, click on the 'Build' tab, then use the search box in the upper right to search for 'exception'. The last one should say 'Enable Objective-C Exceptions'. Click that item to put a check box in the box, rebuild and you are done.

In the XCode editor, if you hold down the Option key (which is the Alt key on PC keyboards) and double click a class name or method, it will look up that word in the API documentation. This is great way to look up the info on a class method.

Here's how to do a mutex when writing a multithreaded Cocoa app. Use the NSLock class...

// In your class' header. (ClassName.h)
@interface ClassName: NSObject
{
    NSLock*     mutex;
}

// In your class' source. (ClassName.m)
@implementation ClassName

- (id)init
{
    if ( (self = [super init] ) ) 
    {
        mutex = [[NSLock alloc] init];
        
        // Other initialization stuff here..
    }
    return self;
}

- (void)dealloc
{
    if ( mutex )
    {
        [mutex release];
        mutex = NULL;
    }

    // Other cleanup code here...
	
    [super dealloc];
}


- (void)someFunction
{
    [mutex lock];

    // Do some stuff.

    [mutex unlock];
}

Ok, so I've been learning Mac programming using Objective-C. I'm still a horrible rank amateur at this stuff, but here's one thing I've learned. Here is an example of how to display a modal File Open dialog box...

int i; // Loop counter.

// Create the File Open Dialog class.
NSOpenPanel* openDlg = [NSOpenPanel openPanel];

// Enable the selection of files in the dialog.
[openDlg setCanChooseFiles:YES];

// Enable the selection of directories in the dialog.
[openDlg setCanChooseDirectories:YES];

// Display the dialog.  If the OK button was pressed,
// process the files.
if ( [openDlg runModalForDirectory:nil file:nil] == NSOKButton )
{
    // Get an array containing the full filenames of all
    // files and directories selected.
    NSArray* files = [openDlg filenames];

    // Loop through all the files and process them.
    for( i = 0; i < [files count]; i++ )
    {
        NSString* fileName = [files objectAtIndex:i];

        // Do something with the filename.
    }
}

I've been interested in programming on the Mac for a while - nearly since the day I bought my first Mac last year. Well after a year of off-again, on-again reading up on it, I've finally started working on my first small Mac application. As a programmer, you can read books all day, but you'll never really understand a programming language unless you use it to write a program with. It is then that everything you read finally starts to sink in. My application is very simple - it's only around 100 lines of actual code so far, but it's taken me quite a while to even get that far. I'm struggling with it, because I know next to nothing about programming on the Mac. I'm having to relearn even the most basic of operations. That means lots of trial and error and lots of hunting in the documentation to relearn how to do things I've been doing for many years. It's a bit frustrating. I'm making good progress though. I've already learned how to do drag & drop, how to do various file operations, how to make a custom drawn window, various string operations, etc. It's been a great learning project. I still have lots of other things to add to it, such as multithreading and displaying custom dialog boxes. Yes, you could argue that I'm making a very simple application harder than it needs to be, but the point here is to learn how to do these things. It's amazing to see just how simple the Mac makes it to do such complicated tasks as drag & drop.

Now, with the info Apple is releasing about the new development tools in their upcoming Leopard OS, I'm getting even more excited about the prospect of programming on the Mac. It has been a long time since I found Windows programming exciting. (and that's what I do for a living!)

In my previous blog, I covered how C# handles memory management. In this one, I'll explain how Cocoa handles memory management and why I feel it is a better way to do things than the C# way.

In C#, you allocate objects on the heap using the 'new' operator. This creates an object on the heap and returns a 'handle' to the object. This 'handle' to the object is really just a disguised pointer. The C# runtime is still using pointers, just like C++ does. The only difference is that C# 'hides' the fact that it's a pointer from the user. This is one of the reasons I emphasized so strongly in my previous blog about what makes a good programmer, the importance of understanding pointers. C# users are using pointers, they just don't realize it! Pointers are still relevant in C#, even though they don't appear to be there. They actually are. This pointer to the newly allocated object is then passed around (with it's true pointer nature hidden from the programmer) and the programmer uses the object however he wants. Then when the programmer is done with this pointer he simply stops using it somewhere. The C# runtime is responsible for figuring out when the object is not being used anymore. Once it figures out that the object is no longer used, it addes that pointer to a list of memory blocks that can be deleted. Eventually that memory block gets deleted during idle processing. (which can be a long time off in a cpu intensive application). Essentially, the C# runtime uses an internal reference counting system to keep track of the lifetime of the pointer. Whenever another copy of that pointer is used, the reference count is increased. Whenever the copy of that pointer is no longer used, the reference count is decreased. When the reference count reaches 0, the object is no longer being used and it gets put in the list of memory blocks to eventually be freed.

Cocoa does this differently. Cocoa's way is sort of a 'middle ground' between the very low level C++ way of memory management (do everything yourself) and the C# way of memory management (the runtime does everything). In Cocoa, all objects are reference counted as well, but the difference is that YOU are responsible for the reference counting. If you need to save a copy of the pointer, you increase it's reference count by calling the 'retain' method on that object. When you are done with the pointer, you call the 'release' method on that object. Whenever 'release' is called, if the reference count hits 0, the object is deleted immediately. You still create the object using the 'new' method, but you 'delete' it using the 'release' method. Essentially, the reference counting takes care of some of the lifetime issues involved in managing pointers, but ultimately, YOU control when an object is deleted. This makes for a much more efficient program when it comes to memory usage. Yes, the Cocoa way is a bit more work, but I feel it is a small price to pay for efficiency.