/ 
SysTray-0.13
River stage zero No dependents
/ SysTray

NAME

SysTray - Perl extension for cross-platform systray support

SYNOPSIS

  use SysTray;
  
  SysTray::create("my_callback", "/path/to/icon", "tooltip");
  
  while (1) {
    SysTray::do_events();  # non-blocking
    
    # do somthing else or sleep for a little while
  }
  
  # callback sub for receiving systray events
  sub my_callback {
    my $events = shift;

    if ($events & SysTray::MB_LEFT_CLICK) {
      # do something on left click
    }
  }

DESCRIPTION

This package provides cross-platform systray functionality. It works with Windows (98 or later), Linux (you must have KDE 3.2/Qt 3.3 or later installed) and Mac (OSX 10.3.9 or later)

EXPORT

None. At this moment you'll have to use fully qualified names.

FUNCTIONS

create ($callback, $icon_path, $tooltip)

Creates a new systray icon.

Parameters: * $callback - sub name that will receive the systray icon events * $icon_path - path to the icon to be dysplayed (must be absolute on Linux, can be relative on Windows/Mac) * $tooltip - text to be displayed when mouse hovers over the icon

Return value: 1 if the icon was successfully created, 0 otherwise

destroy ()

Deletes the systray icon and frees the allocated resources.

do_events ()

Non-blocking processing and dispatching of the system messages for the systray icon. If events occurred the callback provided in the create call will be executed.

change_icon ($icon_path)

Changes the systray icon with the one specified in $icon_path. The same rules apply here as for the create call.

set_tooltip ($tooltip)

Changes the tooltip associated with the systray icon.

clear_tooltip ()

Clear the tooltip associated with the systray icon (if any).

release ()

Releases all GUI allocated resources.

events_callback ($events) [you'll have to provide this]

Sub that must be implemented for receiving events from the Systray icon. The $events parameter is a bit combination of the constants defined in the next section.

CONSTANTS

Mouse Events:

  • MB_LEFT_CLICK - left mouse button was clicked on the systray icon

  • MB_RIGHT_CLICK - right mouse button was clicked on the systray icon

  • MB_MIDDLE_CLICK - middle mouse button was clicked on the systray icon

  • MB_DOUBLE_CLICK - a mouse button was double-clicked. In order to find out which button was double-clicked you'll have to test the $events parameter received by the callback against the above three constants. Before receiving a double-click event you'll always receive a single-click event, so you'll have to decide which one your application will use. Providing functionality for left mouse click and left mouse double-click can be confusing

Key events:

  • KEY_CONTROL - The CONTROL key was pressed along with a mouse button

  • KEY_ALT/KEY_COMMAND - The ALT key (Windows/Linux) or the COMMAND key (Mac) was pressed along with a mouse button

  • KEY_SHIFT - The SHIFT key was pressed along with a mouse button

  • KEY_WIN/KEY_FUNCTION - The WINDOWS key (Windows) or the FUNCTION key (Mac) was pressed along with a mouse button

System events:

  • MSG_LOGOFF/MSG_SHUTDOWN - Log-off or shut-down operation in progress. When this event is received you'll have to prepare your application to exit

BUILD PREREQUESITES

  • Linux - C++ compiler and KDE 3.2/Qt 3.3 development packages installed

  • Windows - Visual Studio 6.0 or later

  • Mac - C/C++ compiler and the Cocoa framework

SEE ALSO

The test_tray.pl script shipped with this distribution.

AUTHOR

Copyright (C) 2009 by Chris Drake. Contact details on www.vradd.com

COPYRIGHT AND LICENSE

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.