NAME
    Cocoa::Growl - Yet another growl module using Growl.framework

SYNOPSIS
        use Cocoa::Growl ':all';
    
        my $installed = growl_installed(); # true if Growl is installed.
        my $running   = growl_running();   # true if Growl is running.
    
        # register application
        growl_register(
            app           => 'My growl script',
            icon          => '/path/to/icon.png', # or 'http://url/to/icon'
            notifications => [qw(Notification1 Notification2)],
        );
    
        # show growl notification
        growl_notify(
            name        => 'Notification1',
            title       => 'Hello!',
            description => 'Growl world!',
        );

DESCRIPTION
FUNCTIONS
    No function is exported by default, but all functions is exportable. And
    ':all' tag export all functions.

  growl_installed
        my $installed = growl_installed();

    Return true value if growl is installed.

  growl_running
        my $running = growl_running();

    Return true value if growl is running.

  growl_register(%parameters)
    Register application to growl.

        growl_register(
            app           => 'My growl script',
            icon          => '/path/to/icon.png', # or 'http://url/to/icon'
            notifications => [qw(Notification1 Notification2)],
        );

    Available parameters are:

    *   app => 'Str' (Required)

        The name of the application. This is listed in Growl preference
        panel.

    *   icon => 'Str'

        Application icon image path or URL. This image is showed in Growl
        preference panel, and used notification default image.

    *   notifications => 'ArrayRef' (Required)

        List of notification names. These names will be displayed in Growl
        preference pane to let users customize options for each
        notification.

    *   defaults => 'ArrayRef'

        List of notification names to enable by default. If this parameter
        is not set, all notifications is to become default.

  growl_notify(%parameters)
    Show growl notify.

        growl_notify(
            name        => 'Notification1',
            title       => 'Hello!',
            description => 'Growl world!',
        );

    Available options are:

    *   name => 'Str' (Required)

        The internal name of the notification. Should be human-readable, as
        it will be displayed in the Growl preference pane. And this value is
        required to be registered by "growl_register" before calling this
        function.

    *   title => 'Str'

        The title of the notification displayed to the user.

    *   description => 'Str'

        The full description of the notification displayed to the user.

    *   icon => 'Str'

        Image file path or URL to show with the notification as its icon. If
        this value is not set, the application's icon will be used instead.

    *   sticky => 'Bool'

        If true value is set, the notification will remain on screen until
        clicked. Not all Growl displays support sticky notifications.

    *   priority => 'Int'

        The priority of the notification. The default value is 0; positive
        values are higher priority and negative values are lower priority.
        Not all Growl displays support priority.

    *   on_click => 'CodeRef',

        This callback is called when notification is clicked. See also
        CALLBACK NOTICE below.

    *   on_timeout => 'CodeRef',

        This callback is called when notification is timeout. (also called
        notification closed by close button)

   CALLBACK NOTICE
    You should run Cocoa's event loop NSRunLoop to be enable callbacks.
    Simplest way to do that is use this module with Cocoa::EventLoop.

        use Cocoa::EventLoop;
        use Cocoa::Growl ':all';
    
        growl_register(
            name          => 'test script',
            notifications => ['test notification'],
        );
    
        my $wait = 1;
        growl_notify(
            name        => 'test notification',
            title       => 'Hello',
            description => 'Growl World!',
            onClick => sub {
                warn 'click';
                $wait = 0;
            },
            onTimeout => sub {
                warn 'timeout';
                $want = 0;
            },
        );
    
        Cocoa::EventLoop->run_while(0.1) while unless $wait;

    If you want to write more complicated script, use AnyEvent and
    AnyEvent::Impl::NSRunLoop. AnyEvent::Impl::NSRunLoop is a wrapper for
    AnyEvent and Cocoa::EventLoop and by using this module, you can use
    cocoa's event loop transparently in your AnyEvent application.

    This is little example:

        use AnyEvent;
        use AnyEvent::Impl::NSRunLoop;
    
        use Cocoa::Growl ':all';;
    
        my $cv = AnyEvent->condvar;
    
        growl_register(
            name          => 'test script',
            notifications => ['test notification'],
        );
    
        growl_notify(
            name        => 'test notification',
            title       => 'Hello',
            description => 'Growl World!',
            onClick => sub {
                warn 'click';
                $cv->send;
            },
            onTimeout => sub {
                warn 'timeout';
                $cv->send;
            },
        );
    
        $cv->recv;

    This script show one notification and wait until notification closed.

USE YOUR OWN Growl.framework
    Although this module bundle Growl.framework and load it by default, you
    can load your own Growl.framework. To do that, save your Growl.framework
    to "/Library/Frameworks/Growl.framework/", and add
    "USE_LOCAL_GROWL_FRAMEWORK=1" option when run Makefile.PL

        perl Makefile.PL USE_LOCAL_GROWL_FRAMEWORK=1

AUTHOR
    Daisuke Murase <typester@cpan.org>

COPYRIGHT AND LICENSE
    Copyright (c) 2010 by KAYAC Inc.

    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

