The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
win32-snarl-1.01
River stage zero No dependents
++
/ Win32::Snarl

NAME

Win32::Snarl - Perl extension for Snarl notifications

SYNOPSIS

  use Win32::Snarl;

  Win32::Snarl::ShowMessage('Perl', 'Perl is awesome, so is Snarl.');

  my $msg_id = Win32::Snarl::ShowMessage('Time', 'The time is now ' . (scalar localtime));
  while (Win32::Snarl::IsMessageVisible($msg_id)) {
    sleep 1;
    Win32::Snarl::UpdateMessage($msg_id, 'Time', 'The time is now ' . (scalar localtime));
  }

DESCRIPTION

Snarl <http://www.fullphat.net/> is a notification system inspired by Growl <http://growl.info/> for Macintosh that lets applications display nice alpha-blended messages on the screen.

Win32::Snarl is the perl interface to Snarl.

NORMAL METHOD INTERFACE

GetSnarlWindow()

Returns a handle to the current Snarl Dispatcher window, or zero if it wasn't found. This is the recommended way to test if Snarl is running or not.

GetVersionEx()

Returns the Snarl system version number. This is an integer value which represents the system build number and can be used to identify the specific version of Snarl running. Of course, as this function is only available as of Snarl V37, if calling it returns zero (or an M_RESULT value) you should use GetVersion to determine which pre-V37 version of Snarl is installed.

HideMessage($id)

Hides the notification specified by $id. $id is the value returned by ShowMessage or ShowMessageEx when the notification was initially created. This function returns True if the notification was successfully hidden or False otherwise (for example, the notification may no longer exist).

IsMessageVisible($id)

Returns True if the notification specified by $id is still visible, or False if not. $id is the value returned by c<ShowMessage> or c<ShowMessageEx> when the notification was initially created.

RegisterAlert($application, $class)

Registers an alert of $class for application $application which must have previously been registered with either RegisterConfig or RegisterConfig2. $class is displayed in the Snarl Preferences panel so it should be people friendly ("My cool alert" as opposed to "my_cool_alert").

If $application isn't registered you'll get M_NOT_FOUND returned. Other possible return values are M_FAILED if Snarl isn't running, M_TIMED_OUT if Snarl couldn't process the request quickly enough, or M_ALREADY_EXISTS if the alert has already been registered. If all went well, M_OK is returned.

RegisterConfig($hwnd, $application, $reply)

Registers an application's configuration interface with Snarl. $application is the text that's displayed in the Applications list so it should be people friendly ("My cool app" rather than "my_cool_app"). Also, it really should match the name of the application as when a user runs an application called "MyCoolApp.exe" they'd expect to see that appear in the Applications list and not "Titanics Cruncher 1.1".

As of V37, if the user double-clicks the application's entry in the Preferences panel, one of two things can happen: if the window specified in $hwnd has a title then it is simply displayed by Snarl - this is to maintain backwards compatability with previous releases of Snarl. If, however, the window has no title and $reply is non-zero then Snarl sends $reply to the window specified in $hwnd with SNARL_SHOW_APP_UI in wParam.

Be sure to call RevokeConfig when your application exits. If you fail to do this, your application will remain orphaned in Snarl's Preferences panel until the user quits Snarl.

RegisterConfig2($hwnd, $application, $reply, $icon)

Registers an application's configuration interface with Snarl. This function is identical to RegisterConfig except that $icon can be used to specify a PNG image which will be displayed against the application's entry in Snarl's Preferences panel.

Be sure to call RevokeConfig when your application exits. If you fail to do this, your application will remain orphaned in Snarl's Preferences panel until the user quits Snarl.

RevokeConfig($hwnd)

Removes the application previously registered using RegisterConfig or RegisterConfig2. $hwnd should be the same as that used during registration. Typically this is done as part of an application's shutdown procedure.

This function returns M_OK on success. Other possible return values are M_FAILED if Snarl isn't running, M_TIMED_OUT if Snarl couldn't process the request quickly enough or M_NOT_FOUND if the application wasn't already registered.

ShowMessage($title, $text, $timeout, $icon, $hwnd, $reply)

Displays a message with $title and $text. $timeout controls how long the message is displayed for (in seconds) (omitting this value means the message is displayed indefinately). $icon specifies the location of a PNG image which will be displayed alongside the message text.

$hwnd and $reply identify the handle of a window and a Windows message respectively. If both are provided then $reply will be sent to $hwnd if the user right- or left-clicks the message, or the message times out. In each instance the wParam value of the message will be set to one of the following values:

  Right Click         SNARL_NOTIFICATION_CLICKED
  Left Click          SNARL_NOTIFICATION_ACK
  Interval Expires    SNARL_NOTIFICATION_TIMED_OUT

If all goes well this function returns a value which uniquely identifies the new notification. Other possible return values are M_FAILED if Snarl isn't running, or M_TIMED_OUT if Snarl couldn't process the request quickly enough.

ShowMessageEx($class, $title, $text, $timeout, $icon, $hwnd, $reply, $sound)

Displays a notification. This function is identical to ShowMessage except that $class specifies an alert previously registered with RegisterAlert and $sound can optionally specify a WAV sound to play when the notification is displayed on screen.

$sound can either be a filename to a specific sound to play, or it can represent a system sound. To play a system sound, prefix the name of the sound with a '+' symbol. For example, to play the default 'Mail Received' system sound, you would specify "+MailBeep" in SoundFile. System sounds are listed under HKEY_CURRENT_USER\AppEvents\EventLabels in the Registry. Note that if an existing sound is being played, the requested sound may not be played, although the notification will still be displayed.

If all goes well this function returns a value which uniquely identifies the new notification. Other possible return values are M_FAILED if Snarl isn't running, M_TIMED_OUT if Snarl couldn't process the request quickly enough, M_BAD_HANDLE or M_NOT_FOUND if the application isn't registered with Snarl or M_ACCESS_DENIED if the user has blocked the notification class within Snarl's preferences.

UpdateMessage($id, $title, $text, $icon)

Changes the title and text in the message specified by $id to the values specified by $title and $text respectively. $id is the value returned by ShowMessage or ShowMessageEx when the notification was originally created. To change the timeout parameter of a notification, use SetTimeout

If all goes well this function returns M_OK. Other possible return values are M_FAILED if Snarl isn't running, M_TIMED_OUT if Snarl couldn't process the request quickly enough or M_NOT_FOUND if the specified notification wasn't found.

OBJECT INTERFACE

There is also an object interface to this module but it is a work in progress.

KNOWN ISSUES

Currently, the ShowMessageEx function gets a M_BAD_POINTER response and does not function. This makes RegisterConfig, RegisterConfig2, and RegisterAlert pretty useless.

SEE ALSO

Win32::GUI For Windows API Calls

Snarl Documentation <http://www.fullphat.net/dev/>

AUTHOR

Alan Berndt, <alan@eatabrick.org>

COPYRIGHT AND LICENSE

Copyright (C) 2010 by Alan Berndt

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.