Please join me at my new location

Saturday, February 6, 2010

Integrating Growl - A Quick Start Guide

As promised, here is a quick start guide to integrating Growl support into a Cocoa application. The documentation expects that you've worked with Xcode before and are familiar with creating new build phases and writing Objective-C code. For the impatient and those that just want to play around I've created a gist with the project. You'll probably want to clone the project instead of looking at it online because it contains some binaries..

git clone git:// gist-297221

The first thing you'll need to get started is a copy of Growl.framework. As of this writing the latest is version 1.2. Once you have a copy of the framework you'll need to link your application against it. To do so, simply drag and drop the framework onto the Linked Frameworks item in your Xcode project. Since the framework will need to be shipped along with your application you'll also need to ensure that it gets copied into your application's bundle. Create a new Copy Files build phase for your application's target, make sure that you set the Destination to Frameworks. Drag and drop Growl.framework from Linked Frameworks to the newly created build phase. At this point your application will compile against the framework and include it when building.

The next thing you'll need to do is create a plist file called Growl Registration Ticket.growlRegDict containing the registration information that will be required by the framework. Below is an example of such a file. You'll need to make sure that this file makes it into the application, this can be done by ensuring that its in the Copy Bundle Resources build phase.

In order for Growl to allow your application to send notifications you'll need to register the notifications that your application will be sending with the framework. To do this you'll need to create and implement a bare-bones delegate. All that's required is that you implement the (NSDictionary*) registrationDictionaryForGrowl method. The implementation of this method will simply need to return a dictionary whose contents come from the plist file created previously. The body of this method can be as simple as:

- (NSDictionary*) registrationDictionaryForGrowl {
   NSString* path = [[NSBundle mainBundle] pathForResource: @"Growl Registration Ticket" ofType: @"growlRegDict"];
   NSDictionary* dictionary = [NSDictionary dictionaryWithContentsOfFile: file];
  return dictionary;

Once this method is implemented, and an instance of the class is set as Growl's delegate by calling [GrowlApplicationBridge setGrowlDelegate: X] you'll be able to send messages to Growl using [GrowlApplicationBridge notifyWithTitle:description:notificationName:iconData:priority:isSticky]

That's about all there is to it. It's a fairly simple framework to integrate with, but the documentation neglects the fact that you have to implement (NSDictionary*) registrationDictionaryForGrowl

An example project exists as a gist on github.

git clone git:// gist-297221