AppleScript Support for Growl

Table of Contents: General AppleScript Support

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.

Download Sample Script

Notifications Using Images


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


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':

Changes in 1.3

Growl 1.3 introduces a few changes to AppleScript support. The most notable changes are as follows:

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:

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:

  1. Download the Growl Control Example script.
  2. Open the script in AppleScript Editor.
  3. Click on the Events tab at the bottom of AppleScript Editor.
  4. Click the Run button in the toolbar.
  5. Watch what the script does as it steps through each example.