# Growl Documentation

Growl

# Growl Documentation

Ingmar
Stein
Growl User's Guide version 0.7
2005
2004
2005
The Growl Project

## Getting Started

### Installing Growl from Disk Image/Package

#### Getting and installing Growl

Download the package from the downloads page. Open the disk image, and double click the package inside.

#### Starting Growl

Open the System Preferences and click on the Growl Preference pane.

System Preference

Click on the Start Growl button. Optionally check the Start on Login checkbox. If this is not checked, you will need to manually start Growl before you can see notifications.

### You have Growl, now what?

#### How does registration work?

##### Why is the Applications tab empty?

You have just downloaded and installed Growl. You have opened up System Preferences, clicked on the Applications tab, and it is empty?! What in the world?

That is the reaction we get from a lot of people new to Growl. Growl is what we like to refer to as a tool for other applications. Now, we don't want to include a list of all of the possible applications in the default installation, because you probably will not be using them all. We also don't know if you would want to even use the applications we have made as examples. So with the default installation of Growl, the applications tab is meant to be empty.

Have no fear. Soon it should fill up with whatever Growl enabled applications that you may have. When a Growl enabled application tries to talk to Growl, it does something called `Registration`. It registers with Growl so that Growl knows what notifications it may send out (so that Growl can list them in its preferences). This is true for scripts as well, anything from AppleScript to Tcl will register.

For the most part, all you will have to do is just launch the application. There are some exceptions. Some applications use filters or rules or whatever was chosen to allow their users control over the whole process within their application as well. If the application you want to use with Growl does not show up in the Applications tab after launching it, look in preferences. If you still don't see it, you can email us at discuss AT growl.info and we can look into the problem.

##### So what now?

Once the application has a registration in the Applications tab, you can control it. You can control all Growl based notifications through this one central location. You can also choose how each notification will appear. One notification can use the Bubbles display, another can use the Music Video display, and a third can use the Bezel display. You can also choose which applications will stay on the screen until clicked, and which ones will not.

### How does Growl work?

Well when a man and woman get together...er wrong discussion. Growl. Right.

#### Displaying notifications

When an application (or script) wants to display a notification to the user (that's you), it sends the information to a background application running on your Mac called GrowlHelperApp. GrowlHelperApp will then, depending on your preferences, show the notification using one of the display plug-ins.

flow of data

An example of the 'Bubble' display.

The actual display of the notifications is handled by GrowlHelperApp. But the preferences for the display types are in the preference pane.

#### The Growl Preference Pane

The Growl preference pane has three tabs:

##### General

General Tab

The General Tab holds preferences that refer to Growl as a whole. The default display is set here.

##### Applications

Applications Tab

You have complete control over which notifications are displayed on your computer - In the 'Applications' tab you can configure which notifications are active - and which display they use.

###### Priority

You can set differing priorities to different notification types. This may affect the way in which your notifications are presented to you, depending on the chosen display.

###### Sticky Notifications

Sticky notifications will stay on screen until clicked.

The 'Sticky' checkbox allows you to decide which notification types are allowed to become sticky, or even force them to be sticky. The checkbox has three states: 'On', 'Off', and 'Mixed'.

'Off' means that those types of notifications can never become sticky, even if an application requests them to be. 'On' forces them to be sticky. 'Mixed' (looks like a bar - see the screenshot above) is the default setting; it means that the application that issues the notification is allowed to decide whether or not notifications of that type should be sticky.

##### Display Options

Display Options is where you can configure what you are shown when Growl notifies you.

Display Options Tab

First you select which display you would like to configure. Then you can change settings on each display however you wish. Some displays have priority settings, some provide preference on the transparency, etc.

### Removing Growl, if you need to

When you install Growl from the .pkg installer, it installs the following files in these locations:

- GrowlAppBridge.framework: /Library/Frameworks/

- Growl.prefpane: /Library/PreferencePanes/

The first time you run Growl, it will also create a folder in your Library/Application Support/ directory called Growl. This folder contains some data that Growl uses, as well as a folder called Plugins.

Growl Application Support Directory

If you trash all of these, log out, and then log back in, Growl will be uninstalled. You can now empty your trash.

One note, if you are uninstalling Growl for a reason that the developers might want to know about, please email us at discuss AT growl.info and we can look into fixing those problems.

## Extras

### GrowlTunes

#### Requirements

- Mac OS X 10.3 or higher

- iTunes

- Growl

#### Installing GrowlTunes

GrowlTunes

Place GrowlTunes in your Applications folder by dragging and dropping it from the GrowlTunes disk image.

#### Using GrowlTunes

GrowlTunes MenuBar Icon

Once you have installed GrowlTunes, double click it. This will put the headphones shown here in the menubar at the top of your screen. From here you can control GrowlTunes.

For users of iTunes 4.7 and later, that is all you have to do to get GrowlTunes working. Note: GrowlTunes does not poll for its information with iTunes 4.7 and later.

For iTunes 4.6 and below, the most important part of using GrowlTunes is the polling button at the bottom of the menu. This allows you to turn on and off polling of iTunes (asking it what song is currently being played).

Once you get GrowlTunes to start polling, you should see a bubble like the image below. You will see one of these each time the track changes in iTunes.

Growl bubble

#### Artwork

Starting with Growl 0.6, GrowlTunes can get artwork from Amazon.com. (Growl 0.5 came with a version that did not have this capability.) If GrowlTunes does not see artwork in the current track playing, and it also does not see that the album artwork was previously downloaded, it will download the track. GrowlTunes does not write this information to the track, but instead to files on disk. GrowlTunes will place the downloaded artwork in your home directory, in Library/Images/Music.

### GrowlMail

#### About GrowlMail

GrowlMail is a plug-in for Apple Mail that posts a Growl notification every time new mail arrives containing the text of the message.

#### Installing GrowlMail

Move the GrowlMail.mailbundle package into `~/Library/Mail/Bundles/`, quit Mail.app, and run the following 2 commands in the terminal:

    defaults write com.apple.mail EnableBundles -bool True
    defaults write com.apple.mail BundleCompatibilityVersion 1

Now relaunch Mail.app. Whenever new mail arrives, Growl will display a notification.

#### Compiling GrowlMail yourself

If you're happy with the pre-built GrowlMail available at the Downloads page, you don't need to read this section.

GrowlMail relies on having Growl compiled and installed, and Growl.framework compiled (the framework does not need to be installed anywhere). Once these tasks are complete, compiling GrowlMail is easy.

GrowlMail lives in the `Extras/GrowlMail/` directory. Simply open GrowlMail.xcode, select the build style you wish to use, and build. The finished product will be called `GrowlMail.mailbundle` and will be in the `build` directory.

### GrowlSafari

#### Requirements

- OS X 10.3 or higher

- Safari 1.1 or higher

- Growl

#### About

GrowlSafari is a plug-in to Safari to make it post Growl notifications on download-related events.

#### Installing GrowlSafari

GrowlSafari requires SIMBL. If you have PithHelmet installed, then you already have SIMBL.

Once SIMBL is installed, put GrowlSafari.bundle into /Library/Application Support/SIMBL/Plugins

Then restart Safari.

You should now receive Growl notifications when downloads complete.

#### Notification Types

Currently, GrowlSafari posts notifications for these events:

- Decompression started

- Copying disk image

- Download complete

- Mounting disk image

#### Compatibility

GrowlSafari works in all versions of Safari (except 1.0) on Mac OS X 10.3 or later.

### GrowlDict

#### Requirements

- OS X 10.3 or higher

- Growl

#### Installing GrowlDict

GrowlDict Icon

In order to install GrowlDict, you will need to place it into the Library/Services folder, located in your home directory. Once GrowlDict is placed there, you will need to log out of your computer, and then log back in.

#### Using GrowlDict

Once you have logged back in, you will be able to use GrowlDict. Using GrowlDict is a 3 step process:

1. Select the text you would like to look up. Text on which the service will be invoked.

2. Select the GrowlDict service in the Services menu for the application with the word you want to look up. GrowlDict Service Selection

3. The definition will appear in a Growl notification. GrowlDict Notification

### growlnotify

growlnotify

#### About

`growlnotify` is a command-line tool to post Growl notifications. You can control all aspects of the notification (within any boundaries set up in the Growl pane of System Preferences). It can be very useful in shell scripts.

#### Installing

In your shell, cd to the directory on the Growl disk image containing `growlnotify`, and type `./install.sh`. That script will install `growlnotify` to `/usr/local/bin` and the manpage to `/usr/local/man`.

#### Building from sources

Running '`make`' will build `growlnotify` into your build folder if you want to test it before installation.

Running '`make install`' will install `growlnotify` into `/usr/local/bin` and install the manpage into `/usr/local/man`. It will also do a build first if necessary.

The Makefile uses `xcodebuild` internally, with the Deployment buildstyle.

#### Usage

    Usage: growlnotify [-hs] [-i ext] [-I filepath] [--image filepath]
    [-p priority] [title]
    Options:
        -h,--help     Display this help
        -n,--name     Set the name of the application that sends the notification
                      [Default: growlnotify]
        -s            Make the notification sticky
        -a,--appIcon  Specify an application name  to take the icon from
        -i,--icon     Specify a file type or extension to look up for
        the notification icon
        -I,--iconpath Specify a file whose icon will be the notification icon
        --image       Specify an image file to be used for the notification icon
        -p,--priority Specify an int or named key (default is 0)

    Display a notification using the title given on the command-line and the
    message given in the standard input.

    Priority can be one of the following named keys: Very Low, Moderate,
    Normal, High,
    Emergency. It can also be an int between -2 and 2.

    To be compatible with gNotify the following switches are accepted:
        -t,--title    Does nothing. Any text following will be treated as the
                      title because that's the default argument behaviour
        -m,--message  Sets the message to the following instead of using stdin

The manpage provides more information on the usage of `growlnotify`. Just type '`man 1 growlnotify`' after installing `growlnotify`.

### MacYac

MacYac

#### About

A client for the Yac Caller-ID application.

Author: Andrew Wellington (proton)

License: BSD

#### Download

The MacYac source is available from the Downloads page.

## Other

### Catalog of applications

There is a catalog of applications that have Growl support built in.

### AppleScript Support for Growl

Script Editor

#### About AppleScript Support

AppleScript support is built into Growl; nothing special needs to be done to enable it.

##### A Note on AppleScript changes in Growl 0.6

You must update your existing AppleScripts for Growl 0.6. In Growl 0.6 AppleScripts must register their notifications every time the script is run — unregistered notifications will not be displayed. See below for an example of registration.

#### Usage

##### Basics

To send a Growl notification via AppleScript, you talk to GrowlHelperApp using two commands: register and notify. A script, like an application, must register itself (once, though multiple times is harmless) with Growl before sending any notifications. The full syntax of the `register` and `notify` commands can be viewed by opening Script Editor, choosing File → Open Dictionary, and selecting GrowlHelperApp from the list.

###### Sample AppleScript Notification

    tell application "GrowlHelperApp"
     -- Make a list of all the notification types
     -- that this script will ever send:
     set the allNotificationsList to ¬
      {"Test Notification" , "Another Test Notification"}

     -- Make a list of the notifications
     -- that will be enabled by default.
     -- Those not enabled by default can be enabled later
     -- in the 'Applications' tab of the growl prefpane.
     set the enabledNotificationsList to ¬
      {"Test Notification"}

     -- Register our script with growl.
     -- You can optionally (as here) set a default icon
     -- for this script's notifications.
     register as application "Growl AppleScript Sample" ¬
       all notifications allNotificationsList ¬
       default notifications enabledNotificationsList ¬
       icon of application "Script Editor"

     --	Send a Notification...
     notify with name "Test Notification" ¬
       title "Test Notification" ¬
       description "This is a test AppleScript notification." ¬
       application name "Growl AppleScript Sample"

     notify with name "Another Test Notification" ¬
       title "Another Test Notification :) " ¬
       description "Alas — you won't see me until you enable me..." ¬
       application name "Growl AppleScript Sample"

    end tell

Once you send the Registration command - your script will appear in the 'applications' tab of the Growl prefpane.

AppleScript Registration

Download Sample Script

##### Notifications Using Images

Growl's notify command supports four types of images for notification when using AppleScript:

###### Application Icons

    notify with ¬
      name "Some Notification"  ¬
      title "This is a Notification with an App Icon"  ¬
      description "We are using an Application Icon..."  ¬
      application name "Growl AppleScript Sample" ¬
      icon of application "Script Editor.app"

Note that the ".app" at the end is optional.

ImageFile

###### File Icons

    notify with ¬
      name "Some Notification"  ¬
      title "This is a Notification with an File Icon"  ¬
      description "We are using a File's Icon..."  ¬
      application name "Growl AppleScript Sample" ¬
      icon of file "file:///Users/someone/Growl"

See Notes on File Paths for details on how to specify the path to a file icon.

ImageFile

###### Image Files

    notify with ¬
      name "Some Notification"  ¬
      title "This is a Notification with an Image File"  ¬
      description "We are using an Image File..." ¬
      application name  "Growl AppleScript Sample" ¬
      image from location ¬
        "file:///Users/someone/pictures/stopWatch.png"

Supported Types: BMP, GIF, ICNS, ICO, JPEG, JPEG 2000, PNG, PSD, TGA, TIFF

ImageFile

###### Image Data

    set the PICTdata to my getArtworkFromiTunesRoutine()

    notify with ¬
      name "Some Notification"  ¬
      title "This is a Notification with PICT Image Data"  ¬
      description "We are using PICT data..." ¬
      application name  "Growl AppleScript Sample" ¬
      PICTimage the PICTdata

Supported Types: PICT, TIFF

Carbon apps tend to return PICT

When you are dealing with raw image data you should use the notify ... Image or notify ... pictImage commands.

Cocoa apps tend to return TIFF

###### TIFF Image Data

    set the TIFFdata to my getPhotoFromAddressBookRoutine()

    notify with ¬
      name "Some Notification"  ¬
      title "This is a Notification with TIFF Image Data"  ¬
      description "We are using TIFF data..." ¬
      application name  "Growl AppleScript Sample" ¬
      image the TIFFdata

If you're not sure which type you are dealing with then you can look in Script Editor's Event Log. The first four chars of the data will show the type:

PICT data returned by iTunes

##### Notes on File Paths

For the "notify ... image from location" and "notify ... icon of file" commands Growl accepts any of the following types as 'locations':

- Aliases - the default file reference type in AppleScript.

- Local file:// URLs (as text) - e.g. "file:///Applications/" — n.b. you must have three slashes after the colon — the third represents the root of the filesystem.

- Paths - e.g. "~/Pictures"

#### Authors

v0.6 (update) — Diggory Laycock — www.monkeyfood.com

v0.5 — Adam Nolley — nanovivid.com

### Folder Actions

#### About the Folder Actions Script

For the Folder Notification scripts to work, they have to be placed in "Scripts/Folder Action Scripts" ... either in /Library or ~/Library. If this neither the 'scripts' nor the 'Folder Action Scripts' folders exist, create them yourself.

Folder Action Scripts Directory

After placing them there, right-click on the folder for which you want notifications and choose "Attach a Folder Action."

Folder Attach

You will then be presented with a file browser pointing at your Folder Action Scripts directory - choose the appropriate script.

### GrowliChat

#### About

GrowliChat is an AppleScript that runs as an application.

#### Installation

To use the app you will need to do the following:

1. Open the script in Script Editor

2. Save the script as an application.

   GrowliChat Save Dialogue

3. Remember to check the "Stays Open" option when saving.

4. Launch the new application and enjoy.

#### Usage

While it is running It will periodically check your contacts, and notify you of changes in their statuses.

### Growl and Quicksilver

#### About

QuickSilver supports Growl via a plug-in.

#### Installing The QS Growl Plug-in

In QuickSilver's Application menu, select the "Get More Plug-ins..." item.

Get More Plug-ins

You can install from the web using the plus icon - or download (and double-click) the plug-in using the arrow icon.

QuickSilver Plug-ins Page

QuickSilver will use Growl to notify you that the plug-in has been installed.

Installation Notification

Other notifications that the QuickSilver plug-in sends are iTunes track changes and when you use QuickSilver to switch network locations.

### Get today's iCal events

#### Installation

Place the scripts in your 'Scripts' folder of your Library

If the scripts folder does not exist then create it yourself.

This will give you quick access to the Script via the Script Menu (/Applications/AppleScript/Script/Install Script Menu)

Scripts Folder

#### Usage

The script is very simple - and requires iCal to be running.

When the script is run it notifies once for every event it finds for today.

### iPod Checker

#### About

This script will sync your ipod with iTunes.

#### Installation

Place the scripts in your 'Scripts' folder of your Library

If the scripts folder does not exist then create it yourself.

This will give you quick access to the Script via the Script Menu (/Applications/AppleScript/Script/Install Script Menu)

Scripts Folder

#### Modifying the Script

You will need to change a few properties in the script:

>     set theiPod to "foo.Propaganda"

Change "foo.propaganda" to the name of your iPod. You will also need to change two Image references - see the in-script comments for more details.

### irssi

In order to install and run this irssi plugin, you must have 3 things preinstalled:

1. irssi with perl support.

   To get perl support in irssi, do one of the following:

   When configuring irssi, do this:

   `./configure --with-perl=yes`

   or, if you have a install of darwinports, do this:

   `sudo port install irssi +perl`

2. A working Growl install.

3. Mac::Growl installed.

   Available as part of the 'bindings' package http://growl.info/downloads_developers.php

   Once you have these three, move growl.pl to ~/.irssi/scripts/ and then run this command in irssi:

   `/script load growl.pl`

   You should get a visual notification that growl installed.

   If you desire growl to automatically start every time you begin irssi put it in ~/.irssi/scripts/autorun/. If you ever need to load it manually you'll need to run this command in irssi:

   `/script load autorun/growl.pl`

### GrowlCalling for Salling Clicker

The Script comes in two forms

- The .cgz archive. This is the form that Clicker is expecting.

- The source .scpt. This is the applescript source of the archive.

#### Installation

1. Open the Salling Clicker Preference Pane.

2. Switch to the 'Phone Events' tab.

3. Drop the archive into the list.

Clicker Tab

#### Usage

The script will notify via growl when clicker receives call notifications from your mobile device.

#### Modifying the script

To edit the script use the gear below the list.

### Snak and Growl

Place the script in the 'Scripts' folder of your 'Snak' folder:

Snak

Then - once Snak is running type "/load Growl.scpt" into the chat box:

Snak Script Loading

### Developers

If you're interested in supporting Growl in your application or working on Growl itself, check out the developer docs.