Difference between revisions of "How to use a TrayIcon"
Line 183: | Line 183: | ||
=== Help, Bug Reporting and Feature Request === | === Help, Bug Reporting and Feature Request === | ||
− | Please, post Bug Reports and Feature Requests on the [http:// | + | Please, post Bug Reports and Feature Requests on the [http://bugs.freepascal.org/main_page.php Lazarus Bugtracker]. |
Help requests can be posted on the Lazarus mailling list or on the Lazarus [http://www.lazarus.freepascal.org/modules.php?op=modload&name=PNphpBB2&file=index Forum]. | Help requests can be posted on the Lazarus mailling list or on the Lazarus [http://www.lazarus.freepascal.org/modules.php?op=modload&name=PNphpBB2&file=index Forum]. |
Revision as of 19:47, 3 January 2008
│
English (en) │
About
TrayIcon is a multiplatform System Tray component. You can find TrayIcon on the Addition tab of components on recent versions of Lazarus (0.9.23+).
TrayIcon used to be an optional component, but is part of LCL since Lazarus 0.9.23
To start quickly, please read 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.
GetPosition
function GetPosition: TPoint;
Returns the position of the tray icon on the display. This function is utilized to show message boxes near the icon. Currently it´s only a stub, no implementations are available and TPoint(0, 0) is returned.
Properties
Hint
property Hint: string;
A Hint will be shown the string isn't empty
PopUpMenu
property PopUpMenu: TPopUpMenu;
A PopUp menu that appears when the user right-clicks the tray icon.
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
- Windows Notes: Ozz Nixon
License
Modified LGPL.
Download
Status: Stable
Can be located at Lazarus 0.9.22 or inferior at the directory: lazarus/components/trayicon
And on Lazaurs 0.9.23 or superior it is automatically installed with LCL
Installation
Gtk2 workaround for old version of TTrayIcon There is a problem with Trayicon on Linux with GTK2 and FPC 2.1.x or newer. The problem is that TrayIcon includes a unit called gdk2x.pp (actually the unit is located inside the opengl component but TrayIcon compiles it into itself). This unit has been added to FPC as of version 2.1.x but it still in the lazarus sources as well, because it doesn't exist on the latest stable FPC (2.0.4). This means that when you install TrayIcon Lazarus will refuse to build the GTK2 LCL complaining that it cannot find unit GTKint. If you look at the messages however you will see the true error: the checksum for gdk2x has changed (this is the result of the duplication). To overcome this, you need to remove either the gdk2x.pp file from the lazarus tree, or the gdk2x.o and gdk2x.ppu file from your FPC units directory. This will be fixed once fpc 2.2.0 is released, at which time gdk2x.pp will be removed from lazarus, so consider this a temporary work-around.
New versions of TTrayIcon will not work with gtk2 unless the compiler is of version 2.2 or superior.
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}
Go to the Additional tab of components, and add a TTrayIcon to your form. Then change it's Name property to SystrayIcon
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)); //7 march 2006 - Loading from icon file (see next line) seems buggy on win32 at this time {$else} SystrayIcon.Icon.LoadFromFile('/path_to_icon/icon.ico'); //7 march 2006 - You may experience problems with rendering using .ico files (buggy display), // if then try using xpm (resolved the problem on fedora core 4 / Gnome) {$endif} SystrayIcon.ShowHint := True; SystrayIcon.Hint := 'my tool tip'; SystrayIcon.PopUpMenu := MyPopUpMenu; SystrayIcon.Show; end;
- NOTE * Win32 Developers Add:
uses jwawinuser; // contains LOADICON
to your implementation code. And even though you can place an icon in the icon property, the current code only works if you "LoadIcon" from the resource. Also, for some odd reason the environment by default does not support WM_USER+ messages, you will need to add "-dPassWin32MessagesToLCL" (without quotations) to support the messaging code. The steps are, click Tools -> Configure "Build Lazarus"..., and add that compiler option to "Options". If you have any existing options, they are "space" delimited.
Subversion
Located under components/trayicon/ on the latest subversion Lazarus.
Help, Bug Reporting and Feature Request
Please, post Bug Reports and Feature Requests on the Lazarus Bugtracker.
Help requests can be posted on the Lazarus mailling list or on the Lazarus Forum.
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.
Technical Details
A difficulty on the development of this component was the many differences on the system tray implementation on various OSes and even Window Managers on Linux. To solve this, the component tries to implement the minimal set of features common to all target platforms. Below 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 altered 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.
- NOTE * for some odd reason the environment by default does not support WM_USER+ messages, you will need to add "-dPassWin32MessagesToLCL" (without quotations) to support the messaging code. The steps are, click Tools -> Configure "Build Lazarus"..., and add that compiler option to "Options". If you have any existing options, they are "space" delimited.
Linux (Gnome, KDE, IceWM, etc) - Multiple system tray icons per application are supported. The image of the icon is actually a very small Window, and can be painted and receive events just like any other TForm descendant.
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 does not 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.
External Links
- http://www.codeproject.com/shell/ctrayiconposition.asp - Code and theory to find the tray icon position under Windows
- http://cvs.gnome.org/viewcvs/gtk%2B/gtk/gtkstatusicon.c?rev=1.23&view=markup - Gtk2 code that implements gtkstatusicon