NAME

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

SYNOPSIS

  use Mac::Growl ':all';

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

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

DESCRIPTION

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.

CAVEATS

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.

Advanced Method Selection

You can specify which method 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.

EXPORT

None by default.

SEE ALSO

http://growl.info

#growl on irc.freenode.net

AUTHORS

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

COPYRIGHT AND LICENSE

Copyright (C) 2004-2005 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.