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 easiest way is to write a registration dictionary file and have it in your application bundle's Resources folder; Growl will detect it when your application launches. Full information on what this file must contain is in the Implementing Growl Support in your Cocoa Application document.

To provide more sophisticated support for Growl, such as the ability to respond to clicks on notifications, you must implement a Growl Delegate. The Growl Delegate can register and re-register manually, though this is usually not necessary.

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 a Cocoa API in the form of the GrowlApplicationBridge class. A quick reference to working with GAB:

Set the delegate
+[GrowlApplicationBridge setGrowlDelegate:]

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

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

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

For more detailed documentation, see Implementing Growl Support in your Cocoa Application and the Growl framework headers.

For other languages, there are a number of bindings:

Network Redux