AppleScript Support for Growl
Table of Contents: General AppleScript Support
- About
- Usage
- Checking if Growl is Running
- Basics
- Sample AppleScript Notification
- Notifications Using Images
- Notes on File Paths
Table of Contents: Growl 1.3
Note Growl requires that everything that works with it registers, including AppleScript. Unregistered notifications will not be displayed. See below for an example of registration.
About AppleScript Support
AppleScript support is built into Growl; nothing special needs to be done to enable it.
Usage
Checking if Growl is running
We recommend checking to see if Growl is running. We highly recommend doing this. If you want to distribute your scripts, you should check if Growl is running before sending any events in order to avoid the "Choose Application" dialog.
Here is an example of how to check that Growl is running that will work with both Growl 1.3+, and Growl 1.2.2 and below:
tell application "System Events" set isRunning to ¬ count of (every process whose bundle identifier is "com.Growl.GrowlHelperApp") > 0 end tell
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 "System Events" set isRunning to (count of (every process whose bundle identifier is "com.Growl.GrowlHelperApp")) > 0 end tell if isRunning then tell application id "com.Growl.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 preferences. 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 end if
Once you send the Registration command - your script will appear in the Applications tab of the Growl preferences.
Notifications Using Images
Growl's notify command supports four types of images for notification when using AppleScript:
-
Application Icons
Example:
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.
-
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.
-
Image Files DEPRECATED AS OF Growl 2.0
Supported Types: BMP, GIF, ICNS, ICO, JPEG, JPEG 2000, PNG, PSD, TGA, TIFF
Example:
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"
-
Image Data
Supported Types: TIFF
When you are dealing with raw image data you should use the notify ... Image command.
Example:
For apps tend to return TIFF
on getPhotoFromAddressBookRoutine() tell application "Address Book" set icon_data to image of my card end tell return icon_data end getPhotoFromAddressBookRoutine 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 TIFFdataIf 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:
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"
Changes in 1.3
Growl 1.3 introduces a few changes to AppleScript support. The most notable changes are as follows:
- Any existing AppleScript will need to be changed to account for GrowlHelperApp and Growl, and not just GrowlHelperApp. The best way to do this is documented earlier on this page, in the Checking if Growl is running section.
- PICT image data support has been removed. If you use PICT image data, then you will need to update your AppleScript in order to change this.
- Growl 1.3 adds a control suite. See the Growl Control Suite section for more details.
Changes in 2.0
Growl 2.0 deprecates the AppleScript syntax for supplying an image to growl via path by way of "image from location". This syntax previously failed to function since 1.3. If you attempt to use it you will now get a message logged to console about the deprecated api and your notification will have a generic icon on it. the alternative is to use image data to send your custom art to growl as shown in the image data example.
Growl Control Suite
Introduced in Growl 1.3, the Growl Control Suite section of the Growl AppleScript dictionary allows for controlling Growl in a few different ways. You can perform tasks via AppleScript for the following things:
- Closing and Opening the Rollup window.
- Closing all open notifications.
- Pausing and Resuming Growl.
- Enabling/Disabling Incoming Networking.
- Checking to see if Growl is paused.
- Checking to see if networking is enabled or disabled.
We have a sample script showing how to use each of these controls. This script will step through each of the functions listed in the Growl AppleScript dictionary. Follow these steps to see how the script functions:
- Download the Growl Control Example script.
- Open the script in AppleScript Editor.
- Click on the Events tab at the bottom of AppleScript Editor.
- Click the Run button in the toolbar.
- Watch what the script does as it steps through each example.
