Mac::Growl - Perl module for registering and sending Growl Notifications on Mac OS X

  use Mac::Growl ':all';

  RegisterNotifications("MyPerlApp", \@allNotifications,
    \@defaultNotifications[, $iconOfApp]);

  PostNotification("MyPerlApp", $notificationName, $notificationTitle,
    $notificationDescription[, $sticky, $priority, $image_path]);

Mac::Growl provides a simple notification for perl apps to register themselves with and send notifications to the Mac OS X notification application Growl.

Mac::Growl defines two methods:

RegisterNotifications(appname, allNotifications, defaultNotifications[, iconOfApp]);

RegisterNotifications takes the name of the application sending notifications, as well as a reference to a list of all notifications the app sends out, and a reference to an array of all the notifications to be enabled by default. Also, optionally accepts the name of an application whose icon to use by default.

PostNotification(appname, name, title, description[, sticky, priority, image_path]);

PostNotification takes the name of the sending application (normally the same as passed to the Register call), the name of the notification (should be one of the allNotification list passed to Register), and a title and description to be displayed by Growl. Also, optionally accepts a "sticky" flag, which, if true, will cause the notification to remain until dismissed, instead of timing out normally; a "priority" value (range from -2 for low to 2 for high); and an image path, a path to a file containing the image for the notification.

For more information, see http://growl.info/documentation/applescript-support.php, which details how this all fits together. It is specific to AppleScript, but the concepts apply to this module as well, except that file paths for images are Unix paths, not URLs.

Mac::Growl expects strings to be passed as UTF-8, if they have high-bit characters. You must take responsibility to encode the characters properly yourself. This can usually be accomplished with utf8 or Encode, such as:

	use utf8;
	utf8::encode($string);

or:

	require Encode;
	$string = Encode::encode('utf8', $string);

If you have a string that is not in some representation other than "Perl's internal representation" -- for example, maybe you have been passed a MacRoman string from another source -- you can use Encode:

	require Encode;
	Encode::from_to($string, 'MacRoman', 'utf8');

This module is designed to use Foundation, a perl module included with Mac OS X that is probably only available if you are using the default system perl. If Foundation is not available (such as if you built your own version of perl), this module will attempt to talk to Growl using Apple events instead of the Cocoa API.

It tries various perl modules to accomplish this, in descending order of preference: Mac::Glue, Mac::OSA::Simple, MacPerl (which defines DoAppleScript), and Mac::AppleScript. As a last resort, it will use osascript(1), a command line program that should be available on all Mac OS X machines.

The methods should all function the same way, except that the various AppleScript methods (all except for Foundation and Mac::Glue) convert text to MacRoman instead of passing in UTF-8, and the Foundation method will send notifications to all logged-in users instead of just the current user.

You can specify which architecture is used, by defining $Mac::Growl::base before loading the module, e.g.:

	BEGIN { $Mac::Growl::base = 'Mac::Glue' }
	use Mac::Growl;

Possible values for this var are, as described above: Foundation, Mac::Glue, Mac::OSA::Simple, MacPerl, Mac::AppleScript, and osascript. Note: You normally do not want to do this. The default is sensible in almost all cases. The only case I've found where I need to use this is in X-Chat, where X-Chat dies when Foundation is loaded.

None by default.

http://growl.info

#growl on irc.freenode.net

Nelson Elhage <nelhage@gmail.com>, Chris Nandor <projects@pudge.net>

Copyright (C) 2004-2006 The Growl Project. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1) Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2) Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.