Growl Application Bridge Documentation

The Growl delegate

GAB works with an object called the Growl delegate, which your application creates and sets up before passing it to GAB. The delegate provides your app's registration dictionary to GAB, as well as optionally its name and icon.

Registering with Growl happens when you set the delegate. When you register, Growl creates a 'ticket' for your application containing its name, icon, and registration dictionary. You can also reregister manually, if the need arises (e.g. if you change your list of notifications or your list of default notifications).

The registration dictionary

The registration dictionary contains an array of the names of all the notifications your app can post, as well as a subset of the array containing the names or indices of the notifications that should be enabled by default. For example, when the all-notifications array lists these names:

• "Download began"
• "Download finished"
• "Download failed"

these two default-notifications arrays are equivalent:

• "Download finished", "Download failed"
• 1, 2

This means that by default, "Download finished" and "Download failed" will be enabled, while "Download began" (which has index 0) will be disabled. You can always post a notification regardless of whether it is enabled (or even listed); if it is not enabled, it will simply be ignored.

The application name and icon

The application name identifies your app to Growl, besides being displayed to the user. We provide the ability for your app to declare its own name so that you can use a uniform name for multiple versions of your app — for example, if you publish SurfWriter Express and SurfWriter Pro, it would make sense to use a single ticket for both, putting it under the common name SurfWriter.

The application icon is usually displayed in notifications when you don't provide a notification icon. Even when you do, the display may badge the notification icon with the application icon. See Icon under Notifications below for more information.

Both the application name and the application icon are looked up by GAB automagically if you don't supply them.

Callbacks

GAB will call either of three functions you supply, if you supply them. These are called callbacks (because the Growl framework is calling back to your application).

The Growl Is Ready callback is called when Growl is successfully launched. It is not sent when you set the delegate while Growl is already running.

The click callback is called when the user clicks on a notification for which you provided a click context (see Click context under Notifications below).

The timed out callback is called when a notification for which you provided a click context times out (see Click context under Notifications below).

Installer strings

The Growl framework comes in two flavours: one with an installer, and one without. The with-installer version includes the Growl prefpane in its Resources folder. When you use the with-installer framework and you set the Growl delegate, GAB checks the current version of Growl and, if appropriate, asks whether the user would like to install it (if it was not already installed) or update it (if an older version was installed). All of this is done for you, and any notifications you post while this is happening are enqueued for delivery as soon as Growl is installed.

Your Growl delegate can supply any of four strings which the with- installer framework will insert into its dialog panels. If you use the without-installer framework, you can still supply any of those four strings, but they will be ignored. ☺