Growl

Introduction to Growl

Growl developer documentation

What is Growl?

Growl is a system for posting notifications to users. Mac OS X offers two built-in ways to do this:

Dialog boxes

The problem with dialog boxes is threefold:

  • They are intrusive; a dialog box must be clicked on before it goes away.
  • If the application is in the background, the dialog box appears in the background.
  • If the application is in the background, it demands the user's attention by beeping and bouncing a Dock tile.

But what if you just want to quickly alert the user of something non-essential, that users may not necessarily need to react to? For this, there's Growl.

Bezels

Bezels are mostly only used by Apple applications, and for good reason — there is no supported public API for using them. They also cannot be made sticky so that they act like dialog boxes.

A better way: Growl

Growl offers a uniform way for you to display notifications, and allows the user to influence the notifications in various ways.

  • Notifications are non-intrusive; they usually disappear after a few seconds (unless you set them as sticky and the user does not overrule you).
  • Notifications always appear in the foreground, so they do not require user intervention to be shown.
  • Growl provides clear and supported public APIs for your application to use.

Using Growl

In order to use Growl, your app must first register (the process for this is described under the Growl Delegate). You provide Growl with your application's name and icon, the list of notifications it can post, and the list of notifications (which must be a subset of the all-notifications list) which are enabled by default.

If your lists of notifications never change, you only need to register once. However, registering multiple times is harmless, so it is faster to simply register without checking for an existing ticket.

Growl uses a simple, though perhaps non-obvious, system for interacting with applications and letting applications interact with it. This system has two components:

  • Growl Application Bridge (provided by the Growl framework).
  • The Growl delegate (provided by your application).

Notifications

Each notification has several attributes; some required, others optional.

Name

Identifies the 'class' of notification; for example, "Download started" and "Download finished" are good notification names. Names should be human-readable, as they are listed in the Growl preference pane in your application's ticket.

Title

Displayed to the user when you post the notification. Can be different from the name; nonetheless, a good notification name is also often a good notification title.

Description

Also displayed to the user when you post the notification, the description expands upon the title. A "Download finished" notification, for example, might list the file or files that were downloaded. Other examples:

  • GrowlMail posts a notification for each new message received. The description is the message's text.
  • GrowlTunes posts a notification when the current track in iTunes changes. The title is the name of the track; the description contains the artist who performed it, the album it's on, and its time and rating.
  • GrowlDict posts a notification after looking up a word, and uses the definition of the word as the description.
Icon

A notification can have its own icon — for example, if you've just downloaded a file, you might use the icon of the file. It can also have an application icon that overrides the one provided by the delegate or looked up by GAB (growlnotify uses this).

All of the graphical displays included with 0.6 look for the notification icon and then the notification app icon, using whichever is found first. If neither one is found, your application's icon is used. Other displays (such as those created by users, or by the Growl team for future versions of Growl) may place the application icon over the notification icon as a badge.

Priority

Every notification has a priority. The priorities are:

-2
Very low
-1
Moderate
0
Normal
+1
High
+2
Emergency

Priorities are clamped to this range. For most notifications, Normal is reasonable.

Not all displays use priority. In those that do, priority may affect font, color, or size, or some combination of these. It may also cause a sound (or a different sound) to be played when the notification is displayed. All of this is up to the display designer.

The user can override priority for each notification name.

Stickiness

Non-sticky notifications generally disappear after a short time. Sticky notifications don't — they wait for the user to click on them before they disappear. Your application will still get a click callback if it requested it.

Not all notifications support sticky. It is generally only supported in graphical displays (those which create a window on the screen).

The user can override stickiness for each notification name.

Some developers have objected to the timing-out behaviour of notifications. We ask that you leave notifications non-sticky unless you have a specific reason for them to be sticky, and let the user decide for himself whether he wants the notification to be sticky.

Click context

When you supply a non-NULL click context for a notification, and a click callback in the delegate, GAB calls back to your application when the notification is clicked or times out.

Not all displays support click feedback.

Platforms

Growl applications can be written in many languages using many different libraries. The Growl framework provides two APIs: a Cocoa API in the form of the GrowlApplicationBridge class, and a Carbon procedural API. The two APIs are nearly identical, and all of the above information applies equally to them. A quick reference to working with GAB:

Task
Cocoa procedure
Carbon procedure
Set the delegate
+[GrowlApplicationBridge setGrowlDelegate:]

Takes a pointer (an id) to an object conforming to the GrowlApplicationBridgeDelegate protocol.

Growl_SetDelegate

Takes a pointer to a struct Growl_Delegate, which must have already been filled out (you can use InitGrowlDelegate to set reasonable defaults, including the size of the structure).

Get the delegate
+[GrowlApplicationBridge growlDelegate]
Growl_GetDelegate
Reregister
+[GrowlApplicationBridge reregisterGrowlNotifications]
Growl_Reregister
Post a notification from parameter data
+[GrowlApplicationBridge notifyWithTitle:
description:
notificationName:
iconData:
priority:
isSticky:
clickContext:]
Growl_NotifyWithTitleDescriptionNameIconPriorityStickyClickContext
Post a notification from a dictionary (keys are listed in GrowlDefines.h)
+[GrowlApplicationBridge notifyWithDictionary:]
Growl_PostNotificationWithDictionary
Post a notification from a notification object
There is not currently such a procedure for Cocoa.
Growl_PostNotification

Takes a pointer to a struct Growl_Notification, which must have already been filled out (you can use InitGrowlNotification to set reasonable defaults, including the size of the structure).

Note that the GrowlApplicationBridge class is not a factory class: there is no such thing as a GrowlApplicationBridge instance.

For more detailed documentation of these APIs see:

and their respective headers.

For other languages, there are a number of bindings:

Website hosted by James Cox