Growl Application Bridge Documentation


The Growl Application Bridge (GAB for short) is the central class of Growl.framework. The entire Growl API for Cocoa applications as of the 1.2 series is in this class.


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).