SYSTRAY - set/get system-tray icons on your computer's desktop

SYSTRAY sets icons in the system-tray of your computer's desktop, if available. SYSTRAY enables setting several sys-tray icon properties and returns the system tray handle(s), if available.

Syntax: handles = systray(varargin);

handles = SYSTRAY retrieves the array of handles for the system-tray icons that were set in Matlab. If no icon is currently displayed in the sys-tray, then the returned array will be empty. If system-tray functionality is unsupported on your platform, then SYSTRAY throws a deliberate error.

handle = SYSTRAY(ICONIMAGE) sets an icon based on the requested icon image and returns its handle. The icon is automatically resized to the sys-tray's default icon size (e.g., 16x16). If ICONIMAGE was already created then it will not be recreated, only its handle will be returned. Note that ICONIMAGE may be an image filename, or any image format accepted by Matlab's im2java function. ICONIMAGE may also be a two-arg pair [X,Map] (indexed image & color map).

handle = SYSTRAY(ICON, param1,value1, param2,value2, ...) sets ICON with initial properties in the familiar format of property name/value pairs. ICON may be either an existing systray icon handle, an array of existing icon handles, or an iconImage as explained above. Property order does not matter and the property names are case-insensitive.

Icon properties can also be read/modified after creation, using get() & set() on the icon handle, or via the dot-notation (hIcon.Tag='iconTag').

The supported properties (gettable and settable) are:

- 'IconImage' - updates the icon image [filename or Matlab image]
- 'ImageAutoSize' - auto-resizes icon to tray size (default='on'/true)
- 'Tooltip' - sets the icon hover tooltip
- 'UIContextMenu' - sets the right-click context-menu (like uicontrols). Provide a uicontextmenu handle or java.awt.PopupMenu object
- 'MarkForDeletion' - set to any value to remove the icon from the systray
- 'Tag' - same as uicontrol
- 'UserData' - same as uicontrol
- 'Message' - text of an informational popup msg next to the icon should be a cell array of {titleText,msgText,severity} where severity = 'none','error','info' or: 'warn' (default: 'info'). Title may be empty, but then no severity icon will show

...and also some gettable-only (i.e., read-only) properties:
- 'Size' - icon size [width,height] - a java.awt.Dimension object
- 'IconWidth' - icon width in [pixels] - numeric value
- 'IconHeight' - icon height in [pixels] - numeric value
- 'Type' - icon type [class name = 'java.awt.TrayIcon']
- 'JavaObject' - reference to the TrayIcon Java object
- 'Class' - class of the Java object

...and also a bunch of callback properties that can be set in any of Matlab's callback formats: 'callback string', @callbackFunc or: {@callbackFunc,params,...}:

- 'MouseClickedCallback' - called when icon is mouse-clicked (pressed & released)
- 'MousePressedCallback' - called when icon is mouse-clicked (before release)
- 'MouseReleasedCallback' - called when icon is mouse-clicked (after release)
- 'MouseEnteredCallback' - called when mouse is moved to within icon bounds
- 'MouseExitedCallback' - called when mouse is moved outside the icon bounds
- 'MouseMovedCallback' - called when mouse is moved over the icon
- 'MouseDraggedCallback' - called when mouse drags the icon
- 'ActionPerformedCallback' - called when icon is double-clicked

Examples:
hIcons = systray; % returns list of existing icon handles
hIcon = systray('icon.png'); % display a simple icon
hIcon = systray('icon.png','Tooltip','right-click me!','UIContextmenu',cm);
systray(hIcon,'Message',{'title','informational message','warn'});
userdata = get(hIcon,'UserData');
set(hIcon,'userdata',magic(5)); % case insensitive prop names
set(hIcon,'markForDeletion',1); % remove icon from sys tray

Warning:
This code requires Java 1.6, available since Matlab 7.5. (R2007b). This code also uses some undocumented Matlab features.

Technical details:
The details are explained in http://undocumentedmatlab.com/blog/setting-system-tray-icons/ and http://undocumentedmatlab.com/blog/setting-system-tray-popup-messages/

Limitations:
Due to the undocumented nature of some features, I have still not been able to bypass a few limitations in functionality - see the help section for details.

Bugs and suggestions:
Please send to Yair Altman (altmany at gmail dot com)