How to use a TrayIcon
About
TrayIcon is a multiplatform System Tray component. It currently works on the following widgetsets: win32, Gtk1, Gnome, Gtk2. In the future it will also work for Carbon ( Mac OS X ) and Qt 4.
Two interfaces are supplied, a visual component and a non-visual object. The object is compatible with Delphi, while the visual component isn´t. They have exactly the same features.
The non-visual object is called SystrayIcon, and the visual component is TTrayIcon.
To start quickly, please read [TrayIcon#Demonstration_program_1 the demonstration program].
Documentation
Bellow is a list of all methods, properties and events of the component. They have the same names and work the same way on the visual component and on the non-visual object.
A function works on all target platforms unless written otherwise.
Methods
Show
procedure Show;
Shows the icon on the system tray.
Hide
procedure Hide;
Removes the icon from the system tray.
Properties
Hint
property Hint: string;
Now multiplatform!
ShowHint
property ShowHint: Boolean;
Now multiplatform!
PopUpMenu
property PopUpMenu: TPopUpMenu;
Events
OnPaint
property OnPaint: TNotifyEvent;
Use this to implement custom drawing to the icon. Draw using the canvas property of the icon.
Note: Does not work on win32.
OnClick
property OnClick: TNotifyEvent;
OnDblClick
property OnDblClick: TNotifyEvent;
OnMouseDown
property OnMouseDown: TMouseEvent;
OnMouseUp
property OnMouseUp: TMouseEvent;
OnMouseMove
property OnMouseMove: TMouseMoveEvent;
Screenshot
Authors
License
Modifyed LGPL.
Download
Status: Beta
Can be located at the latest subversion Lazarus under: components/trayicon
Installation
Demonstration program 1
This program will load a icon from a internal resource on Windows or from an external file on other platforms.
To create and link the icon resource to your Windows software you must:
1. Create a traytest.rc resource script, like this:
101 ICON "icon1.ico"
2. Compile the resource script into a .res file with windres. Windres is supplied with Lazarus.
windres -i traytest.rc -o traytest.res
Now you can write the test program. Create a new program with 1 form. Go to your source file and add this on the interface section:
{$ifdef win32} {$R traytest.res} {$endif}
Next add a button to the form. Double click the button and add this code to it:
procedure MyForm.Button1Click(Sender: TObject); const IDI_ICON1 = 101; begin {$ifdef win32} SystrayIcon.Icon.Handle := LoadIcon(hInstance, MAKEINTRESOURCE(IDI_ICON1)); {$else} SystrayIcon.Icon.LoadFromFile('/path_to_icon/icon.ico'); {$endif} SystrayIcon.ShowHint := True; SystrayIcon.Hint := 'my tool tip'; SystrayIcon.PopUpMenu := MyPopUpMenu; SystrayIcon.Show; end;
Subversion
Located under components/trayicon/ on the latest subversion Lazarus.
Bug Reporting/Feature Request
Tests are necessary to verify if the component works on all Window Managers.
You can post Bug Reports / Feature Requests here:
Change Log
- 17/01/2006 - Available as a preview on the Lazarus subversion. Still under heavy construction, however.
- 24/01/2006 - Stable under win32, gnome and gtk1, but still waiting for gtk2 support. Lazarus 0.9.12 was release with this version.
- 17/02/2006 - Added support for gtk2 on subversion.
Help
Help requests can be posted on the Lazarus mailling list or on the Lazarus Forum.
Technical Details
A difficulty on the development of this component was the many differences on the system tray implementation on varios OSes and even Window Managers on Linux. To solve this, the component tryes to implement the minimal set of features common to all target platforms. Bellow is a list of the features implemented on each platform:
Windows - Multiple system tray icons per application are supported. The image of the icon can be alterred using a HICON handle. Events to the icon are sent via a special message on the user reserved space of messages (>= WM_USER) to the Window which owns the Icon. No paint events are sent to the Window.
Linux (Gnome, KDE, IceWM, etc) - Multiple system tray icons per application are supported. The image of the icon is acctually a very small Window, and can be painted and receive events just like any other TForm descendent.
Linux (WindowMaker, Openbox, etc) - Does not support system tray icons out-of-the-box. However, There are at least two softwares that provides support for it: Docker and WMSystray
Mac OS X - This system doesn´t really have System Tray icons in the way Linux and Windows have them. This component attempts to use tray-like features of Mac OS X to implement a tray icon. Every application on Mac OS X has a Dock icon. The software can assign a popup menu for this Dock, and this is probably how TrayIcon for Mac OS will work in the future. One compatibility problem is that only one Dock per application can exist.
You can see here is how it will look like: http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/XHIGMenus/chapter_16_section_6.html
With this in mind a approach which supports all Platforms was created:
- Only one Systray Icon is supported per application, and all applications that use the component have it initialized on the startup of the program. This way you will use the SystrayIcon object, and not it´s class. (Required by Mac OS X)
- Painting is done via a TIcon object. (Required by Windows)
The following extra features are already available or will be, but they won´t work on all platforms.
- Multiple Systray Icons. Won´t work on Mac OS X.
- OnPaint event and Canvas property to draw the icon freely. Won´t work on Windows.