Difference between revisions of "How to use a TrayIcon"

From Free Pascal wiki
Jump to navigationJump to search
(30 intermediate revisions by 4 users not shown)
Line 9: Line 9:
  
  
==== Gnome won't display Icon ====
+
=== Linux may not display the Icon ===
  
There are at least two reasons why a Gnome Shell Linux system may fail to display the System Tray Icon, a clash between libappindicator1 and libappindicator3 in Lazarus earlier than 2.0.6. and, secondly, a distribution's adherence to the Gnome hard line about not displaying System Tray Icons. The Gnome Developers have determined that Gnome should not support the System Tray Icon model at all, apparently to avoid screen clutter. If your end users are willing to risk a little screen clutter to achieve a usable desktop, keep reading.
+
Some Linux systems will have trouble displaying the GTK TrayIcon, in general this relates to a move away from the System Tray model that Lazarus TrayIcon is based on. This problem is a particular issue with Gnome but some other Desktops may also suffer. There are now two ways the GTK2 SysTray component tries to show its icon, the traditional System Tray and an AppIndicator library.
  
Most (if not all) Linux Distributions using Gnome Shell will not, out of the box, display the LCL System Tray Icon. Sadly, it fails silently, giving a user no indication of whats happening. Fortunately, there are a number of Gnome Extensions that can restore normal operation but be aware that each new release of Gnome appears (and maybe only 'appears') to take steps to stop even those extension from working. At the time of writing this a model that does work for Fedora 30 and openSUSE 15 is to install the Gnome Extension TopIcons-plus (and possibly a version 3 appindicator library).  
+
Lazarus 2.2 (or fixes, main), now looks for an AppIndicator first and uses that if it it finds one. Only if that fails will it try for a traditional System Tray. This has several consequences -
  
To install a Gnome Extension, you have to install, into (eg) Firefox an extension that allows you to control your collection of Gnome Extensions. Start your browser and search for "Gnome Extensions", read the instructions, maybe install and then use the same website to activate the extension. Awkward process but OK if you want to play with the wide range of extensions available. An alternative approach that works at present is to download the extension from github and install it, maybe not a good long term suggestion (?) -
+
* The AppIndicator is intentionally a much simpler user interface. One click and it shows up a Popup Menu. '''No double click, no drag, no right click, no hint.'''  If your app depends on one of those secondary responses, and you don't have a Gnome Desktop, you may try to force Lazarus to use the traditional SysTray, see below.
  
As root -
+
* An AppIndicator library must be installed, until recently, that was libappindicator3 but now many distros are moving to libayatana. A number of prominent distributions appear to be pre installing a AppIndicator but you cannot assume.
<syntaxhighlight lang="bash">dnf install make libappindicator-gtk3 gnome-tweak-tool</syntaxhighlight>
 
  
As yourself -
+
* On Gnome desktops, an additional item is needed, gnome-shell-extension-appindicator must be installed and '''enabled'''. See below.
<syntaxhighlight lang="bash">git clone https://github.com/phocean/TopIcons-plus.git
+
 
cd TopIcons-plus
+
* Developers of new (Linux) applications are advised to design their program around TrayIcon using only a popUpMenu !
make install
+
 
</syntaxhighlight>
+
Mageia Enlightenment also requires an AppIndicator library and enabling System Tray in Settings->Modules and then adding that System Tray to a Shelf (all terms familiar to Enlightenment users). Unfortunately, even that gets 'an' icon, not the one you carefully select for your application.
 +
 
 +
==== Force traditional SysTray ====
 +
This is a purely GTK2 behavior, not for GTK3, QT5 nor any non Linux widget set.
 +
 
 +
As some systems do still have a functional traditional SysTray and it does offer a richer interface, you may wish to still use it. As of Lazarus 2.0.6, GTK2 LCL apps will look at an environment variable, LAZUSEAPPIND before deciding to use the AppIndicator, if its set to NO then the traditional SysTray will be used but no error is reported (or even detectable) if its not available. If set to INFO (or anything else than NO) it will report, to the console, what it is trying to do. (The YES option became irrelevant with Lazarus 2.2.)
 +
 
 +
<syntaxhighlight lang="bash">LAZUSEAPPIND=NO myapp <enter></syntaxhighlight>
 +
 
 +
 
 +
==== AppIndicator Libraries ====
 +
There are currently two possible AppIndicator libraries, Canonical's LibAppIndicator3-1 or libayatana-appindicator3-1, some systems have both, Bullseye has only the Ayatana one. Lazarus trunk supports Ayatana after 22 May 2021, r65122 and in 2.2.0.  See External Links, below about the shift to Ayatana.
 +
 
 +
One or the other library can generally be installed from your distribution's normal package library. However, it is packaged with a number of different names. Sigh ...
 +
* libappindicator3 - Slackware, NetBSD
 +
* libappindicator3-1 - openSUSE and earlier Debian [-based]
 +
* libappindicator-gtk3 - Arch, ALT, CentOS and Fedora, RedHat
 +
* libappindicator3_1 - all Mandrake/Mandriva derivatives -- Mageia,  OpenMandriva, PCLinuxOS, Rosa
 +
* libayatana-appindicator3-1 - Debian Bullseye and most other Linuxs that offer Ayatana.
 +
 
 +
==== gnome-shell-extension-appindicator ====
 +
This plugin is necessary for all current Gnome based systems. It is pre installed on some Gnome Desktops and only works with the an AppIndicator (not traditional SysTray). It is KNSI inspired so no fancy right clicks allowed, just assign it a menu.
 +
 
 +
On Fedora, you can do this (note you don't need gnome-tweaks on Fedora 34) -
 +
<syntaxhighlight lang="bash">sudo dnf install libappindicator-gtk3  gnome-shell-extension-appindicator gnome-tweaks [enter]</syntaxhighlight>
 +
Once installed, you need to restart the Desktop, just logout and back in. Then you must 'enable' the new plugin. On Fedora 33 thats easy, use the gnome-tweaks command, Extensions, enable "Kstatusnotifieritem/appindicator support". On Fedora 34, they have made it a bit harder by removing the Extensions section from Gnome Tweaks (too many happy users I expect). So, with Fedora 34, use the gnome-extensions command, it does not have a gui so issue the following command -
 +
<syntaxhighlight lang="bash"> gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com [enter]</syntaxhighlight>
 +
Replace 'enable' with 'info' to get some diagnostic information.
 +
 
 +
Note, three steps, install, restart desktop, enable plugin !
 +
 
 +
'''Debian Bullseye''' appears to arrive with the Ayatana library pre installed but the Gnome version still requires gnome-shell-extension-appindicator, install as above.
 +
 
 +
Your application can enable the extension (after a desktop restart), if you are feeling brave see https://github.com/tomboy-notes/tomboy-ng/blob/master/source/mainunit.pas
 +
 
 +
'''Note :''' ''Adding the plugin as a dependency of your application might seem attractive but do not do so !  On desktops other than Gnome, it will pull in, as dependencies, the full Gnome desktop. Your end users will not thank you.''
 +
 
 +
==== TopIconsPlus ====
 +
Sadly, the coming of Wayland seems to have killed TopIconsPlus. This section may be removed before long.
 +
 
 +
==== Checking before invoking TrayIcon ====
 +
Because your app may show the user only its TrayIcon and if that's not visible the user cannot interact, you may like to test to see if its going to work. Sadly a test previously recommend here has now proved to be unreliable (in Ubuntu 21.10) and its been removed from Lazarus.
 +
 
 +
https://github.com/tomboy-notes/tomboy-ng/blob/master/source/mainunit.pas function TMainForm.CheckGnomeExtras() has code that asks the Gnome plugin manager if if the plugin is installed and enabled. And it enables it if necessary. And we really should not have to do things like that !
  
Logout and back in again.
+
==== On GTK3 ====
<syntaxhighlight lang="bash">gnome-tweaks</syntaxhighlight>
+
Trunk from October 2019 has a working GTK3 TrayIcon based, again, on the AppIndicator. The advice above relating to installing LibAppindicator3 applies to GTK3 as well. As the only way you can get a TrayIcon under GTK3 is the an AppIndicator, you can only use it to display a popup menu, don't expect to get a working OnClick event.
In the app thats runs, click Extensions, turn TopIcons-plus ON and click close
 
  
Note that for OpenSUSE the appindicator library is called libappindicator3-1, its likely other distributions may call it the same thing. Distributions based on Ubuntu will have it installed already.
+
====QT5 on Linux====
 +
Some linux systems that won't display the GTK Tray Icon will display the Qt5 version, but only if they use XOrg. Any system using wayland apparently has other has issues with Qt5. Most Gnome desktops and some others use wayland by default but users can choose to use XOrg instead at logon time.
  
=== Issue On the Mac, OSX ===
+
=== Issue On the macOS 32 bit Carbon ===
In October, 2017 it was noted that on the Mac, Sierra, Carbon, Lazarus 1.8rc4 a small problem existed. Attempts to updates to the caption of a menu item in a popup menu associated with a TrayIcon do not happen as expected. Its not uncommon to want to update the menu text at run time, for example, to display a list of recently opened files. This problem has been logged,  https://bugs.freepascal.org/view.php?id=32516 . A workaround that appears reliable is to call TrayIcon1.InternalUpdate; after making changes to the captions.  
+
In October 2017 it was noted that a small problem existed on Sierra 10.12 when using the [[Carbon Interface|Carbon]] widget set. Attempts to update the caption of a menu item in a popup menu associated with a TrayIcon do not happen as expected. It is not uncommon to want to update the menu text at run time, for example, to display a list of recently opened files. This problem has been logged,  https://bugs.freepascal.org/view.php?id=32516 . A workaround that appears reliable is to call <syntaxhighlight inline lang="pascal">TrayIcon1.InternalUpdate;</syntaxhighlight> after making changes to the captions.  
  
This problem does not exist on Linux, Windows or OSX using Cocoa Widget Set.
+
This problem does not exist on Linux, Windows or on macOS when using the 64 bit [[Cocoa Interface|Cocoa]] widget set.
  
Note that TrayIcon on the Mac, Carbon (ie 32bit) has a memory leak.
+
{{Warning|TrayIcon on macOS, using the 32 bit [[Carbon Interface|Carbon]] widget set has a memory leak.}}
  
 
=== Documentation ===
 
=== Documentation ===
Line 85: Line 127:
  
 
{{Note| Does not work on win32.}}
 
{{Note| Does not work on win32.}}
 +
 +
{{Note| Following events not available on Linux if using the LibAppIndicator3 model, its menu only.}}
  
 
<span style="color: teal">'''OnClick'''</span>
 
<span style="color: teal">'''OnClick'''</span>
Line 126: Line 170:
 
As of Lazarus 0.9.26 TIcon has been fully implemented and it is no longer necessary to load the icon from a resource file on Windows. The icon can be loaded in the IDE or with usual code.
 
As of Lazarus 0.9.26 TIcon has been fully implemented and it is no longer necessary to load the icon from a resource file on Windows. The icon can be loaded in the IDE or with usual code.
  
Go to the Additional tab of components, and add a TTrayIcon to your form. Then change it's '''Name''' property to SystrayIcon
+
Go to the Additional tab of components, and add a TTrayIcon to your form. Then change its '''Name''' property to SystrayIcon
  
 
Next add a button to the form. Double click the button and add this code to it:
 
Next add a button to the form. Double click the button and add this code to it:
Line 144: Line 188:
  
 
=== Example 2 - Creating the icon with TLazIntfImage ===
 
=== Example 2 - Creating the icon with TLazIntfImage ===
You can use TLazIntfImage to draw quickly your icon, as in the example code below:
+
You can use TLazIntfImage to draw your icon quickly, as in the example code below:
  
 
<syntaxhighlight lang="pascal">
 
<syntaxhighlight lang="pascal">
Line 187: Line 231:
 
Please, post Bug Reports and Feature Requests on the [http://bugs.freepascal.org/main_page.php Lazarus Bugtracker].
 
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 mailing list or on the Lazarus [http://www.lazarus.freepascal.org/modules.php?op=modload&name=PNphpBB2&file=index Forum].
  
 
=== Change Log ===
 
=== Change Log ===
Line 193: Line 237:
 
# 24/01/2006 - Stable under win32, gnome and gtk1, but still waiting for gtk2 support. Lazarus 0.9.12 was release with this version.
 
# 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.
 
# 17/02/2006 - Added support for gtk2 on subversion.
# July 2008 - Implments support for Qt 4
+
# July 2008 - Implements support for Qt 4
 
# July 2008 - Implements support for Carbon through [[PasCocoa]]
 
# July 2008 - Implements support for Carbon through [[PasCocoa]]
  
Line 203: Line 247:
 
{{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.}}
 
{{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 (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. Note that this does not apply to TrayIcons that are using the OS's AppIndicator interface. Certainly not Gnome, maybe not of desktops as time goes by.
  
 
'''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: [http://icculus.org/openbox/2/docker/ Docker] and [http://freshmeat.net/projects/wmsystray/ WMSystray]
 
'''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: [http://icculus.org/openbox/2/docker/ Docker] and [http://freshmeat.net/projects/wmsystray/ WMSystray]
  
'''Mac OS X''' - TTrayIcon support is implemented using the menu bar extras. Unfortunatelly the API to use menu bar extras is only available in Cocoa and not in Carbon, so we use the stable PasCocoa bindings in the Carbon interface to support menu bar extras even in older FPC compilers and in the Cocoa interface we will use the more modern Objective Pascal syntax.
+
'''macOS''' - TTrayIcon support is implemented using the menu bar extras. Unfortunately the API to use menu bar extras is only available in Cocoa and not in Carbon, so we use the stable PasCocoa bindings in the Carbon interface to support menu bar extras even in older FPC compilers and in the Cocoa interface we will use the more modern Objective Pascal syntax.
  
 
[[Image:Mn_menubaritems.jpg]]
 
[[Image:Mn_menubaritems.jpg]]
  
 
To read more about menu bar extras:
 
To read more about menu bar extras:
# http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/XHIGMenus/chapter_16_section_6.html
+
 
# http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/AppleHIGuidelines/XHIGMenus/XHIGMenus.html
+
# https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/StatusBar/StatusBar.html
 +
# https://developer.apple.com/design/human-interface-guidelines/macos/extensions/menu-bar-extras/
 +
# https://developer.apple.com/design/human-interface-guidelines/macos/menus/dock-menus/
 +
# https://developer.apple.com/design/human-interface-guidelines/macos/system-capabilities/dock/
 +
# https://developer.apple.com/design/human-interface-guidelines/macos/menus/menu-anatomy/
 
# http://en.wikipedia.org/wiki/Menu_extra
 
# http://en.wikipedia.org/wiki/Menu_extra
 +
 
With this in mind an approach which supports all Platforms was created:
 
With this in mind an approach which supports all Platforms was created:
 +
 
* Painting is done via a TIcon object. (Required by Windows)
 
* 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.
 
The following extra features are already available or will be, but they won´t work on all platforms.
 
* OnPaint event and Canvas property to draw the icon freely. Won´t work on Windows.
 
* OnPaint event and Canvas property to draw the icon freely. Won´t work on Windows.
 
  
 
=== External Links ===
 
=== External Links ===
Line 225: Line 275:
 
* http://cvs.gnome.org/viewcvs/gtk%2B/gtk/gtkstatusicon.c?rev=1.23&view=markup - Gtk2 code that implements gtkstatusicon
 
* http://cvs.gnome.org/viewcvs/gtk%2B/gtk/gtkstatusicon.c?rev=1.23&view=markup - Gtk2 code that implements gtkstatusicon
 
* http://pasmontray.sourceforge.net - Open source program that uses TrayIcon to display CPU and memory utilisation in the system tray.
 
* http://pasmontray.sourceforge.net - Open source program that uses TrayIcon to display CPU and memory utilisation in the system tray.
 +
* [https://lists.debian.org/debian-devel/2018/03/msg00506.html Background to Debian's switch from libappindicator to Ayatana]
 +
* [https://github.com/AyatanaIndicators/libayatana-appindicator Ayatana App Indicator]
  
 
[[Category:Tutorials]]
 
[[Category:Tutorials]]

Revision as of 13:33, 16 May 2022

English (en)

About

TTrayIcon is a multiplatform System Tray component. You can find TrayIcon on the Additional tab of the Component Palette (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.


Linux may not display the Icon

Some Linux systems will have trouble displaying the GTK TrayIcon, in general this relates to a move away from the System Tray model that Lazarus TrayIcon is based on. This problem is a particular issue with Gnome but some other Desktops may also suffer. There are now two ways the GTK2 SysTray component tries to show its icon, the traditional System Tray and an AppIndicator library.

Lazarus 2.2 (or fixes, main), now looks for an AppIndicator first and uses that if it it finds one. Only if that fails will it try for a traditional System Tray. This has several consequences -

  • The AppIndicator is intentionally a much simpler user interface. One click and it shows up a Popup Menu. No double click, no drag, no right click, no hint. If your app depends on one of those secondary responses, and you don't have a Gnome Desktop, you may try to force Lazarus to use the traditional SysTray, see below.
  • An AppIndicator library must be installed, until recently, that was libappindicator3 but now many distros are moving to libayatana. A number of prominent distributions appear to be pre installing a AppIndicator but you cannot assume.
  • On Gnome desktops, an additional item is needed, gnome-shell-extension-appindicator must be installed and enabled. See below.
  • Developers of new (Linux) applications are advised to design their program around TrayIcon using only a popUpMenu !

Mageia Enlightenment also requires an AppIndicator library and enabling System Tray in Settings->Modules and then adding that System Tray to a Shelf (all terms familiar to Enlightenment users). Unfortunately, even that gets 'an' icon, not the one you carefully select for your application.

Force traditional SysTray

This is a purely GTK2 behavior, not for GTK3, QT5 nor any non Linux widget set.

As some systems do still have a functional traditional SysTray and it does offer a richer interface, you may wish to still use it. As of Lazarus 2.0.6, GTK2 LCL apps will look at an environment variable, LAZUSEAPPIND before deciding to use the AppIndicator, if its set to NO then the traditional SysTray will be used but no error is reported (or even detectable) if its not available. If set to INFO (or anything else than NO) it will report, to the console, what it is trying to do. (The YES option became irrelevant with Lazarus 2.2.)

LAZUSEAPPIND=NO myapp <enter>


AppIndicator Libraries

There are currently two possible AppIndicator libraries, Canonical's LibAppIndicator3-1 or libayatana-appindicator3-1, some systems have both, Bullseye has only the Ayatana one. Lazarus trunk supports Ayatana after 22 May 2021, r65122 and in 2.2.0. See External Links, below about the shift to Ayatana.

One or the other library can generally be installed from your distribution's normal package library. However, it is packaged with a number of different names. Sigh ...

  • libappindicator3 - Slackware, NetBSD
  • libappindicator3-1 - openSUSE and earlier Debian [-based]
  • libappindicator-gtk3 - Arch, ALT, CentOS and Fedora, RedHat
  • libappindicator3_1 - all Mandrake/Mandriva derivatives -- Mageia, OpenMandriva, PCLinuxOS, Rosa
  • libayatana-appindicator3-1 - Debian Bullseye and most other Linuxs that offer Ayatana.

gnome-shell-extension-appindicator

This plugin is necessary for all current Gnome based systems. It is pre installed on some Gnome Desktops and only works with the an AppIndicator (not traditional SysTray). It is KNSI inspired so no fancy right clicks allowed, just assign it a menu.

On Fedora, you can do this (note you don't need gnome-tweaks on Fedora 34) -

sudo dnf install libappindicator-gtk3  gnome-shell-extension-appindicator gnome-tweaks [enter]

Once installed, you need to restart the Desktop, just logout and back in. Then you must 'enable' the new plugin. On Fedora 33 thats easy, use the gnome-tweaks command, Extensions, enable "Kstatusnotifieritem/appindicator support". On Fedora 34, they have made it a bit harder by removing the Extensions section from Gnome Tweaks (too many happy users I expect). So, with Fedora 34, use the gnome-extensions command, it does not have a gui so issue the following command -

 gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com [enter]

Replace 'enable' with 'info' to get some diagnostic information.

Note, three steps, install, restart desktop, enable plugin !

Debian Bullseye appears to arrive with the Ayatana library pre installed but the Gnome version still requires gnome-shell-extension-appindicator, install as above.

Your application can enable the extension (after a desktop restart), if you are feeling brave see https://github.com/tomboy-notes/tomboy-ng/blob/master/source/mainunit.pas

Note : Adding the plugin as a dependency of your application might seem attractive but do not do so ! On desktops other than Gnome, it will pull in, as dependencies, the full Gnome desktop. Your end users will not thank you.

TopIconsPlus

Sadly, the coming of Wayland seems to have killed TopIconsPlus. This section may be removed before long.

Checking before invoking TrayIcon

Because your app may show the user only its TrayIcon and if that's not visible the user cannot interact, you may like to test to see if its going to work. Sadly a test previously recommend here has now proved to be unreliable (in Ubuntu 21.10) and its been removed from Lazarus.

https://github.com/tomboy-notes/tomboy-ng/blob/master/source/mainunit.pas function TMainForm.CheckGnomeExtras() has code that asks the Gnome plugin manager if if the plugin is installed and enabled. And it enables it if necessary. And we really should not have to do things like that !

On GTK3

Trunk from October 2019 has a working GTK3 TrayIcon based, again, on the AppIndicator. The advice above relating to installing LibAppindicator3 applies to GTK3 as well. As the only way you can get a TrayIcon under GTK3 is the an AppIndicator, you can only use it to display a popup menu, don't expect to get a working OnClick event.

QT5 on Linux

Some linux systems that won't display the GTK Tray Icon will display the Qt5 version, but only if they use XOrg. Any system using wayland apparently has other has issues with Qt5. Most Gnome desktops and some others use wayland by default but users can choose to use XOrg instead at logon time.

Issue On the macOS 32 bit Carbon

In October 2017 it was noted that a small problem existed on Sierra 10.12 when using the Carbon widget set. Attempts to update the caption of a menu item in a popup menu associated with a TrayIcon do not happen as expected. It is not uncommon to want to update the menu text at run time, for example, to display a list of recently opened files. This problem has been logged, https://bugs.freepascal.org/view.php?id=32516 . A workaround that appears reliable is to call TrayIcon1.InternalUpdate; after making changes to the captions.

This problem does not exist on Linux, Windows or on macOS when using the 64 bit Cocoa widget set.

Warning-icon.png

Warning: TrayIcon on macOS, using the 32 bit Carbon widget set has a memory leak.

Documentation

Below 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.

Light bulb  Note: Does not work on win32.
Light bulb  Note: Following events not available on Linux if using the LibAppIndicator3 model, its menu only.

OnClick

property OnClick: TNotifyEvent;

OnDblClick

property OnDblClick: TNotifyEvent;

OnMouseDown

property OnMouseDown: TMouseEvent;


OnMouseUp

property OnMouseUp: TMouseEvent;

OnMouseMove

property OnMouseMove: TMouseMoveEvent;

Authors

Light bulb  Note: Windows: 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 Lazarus 0.9.23 or superior it is automatically installed with LCL

Example 1 - Using TIcon

As of Lazarus 0.9.26 TIcon has been fully implemented and it is no longer necessary to load the icon from a resource file on Windows. The icon can be loaded in the IDE or with usual code.

Go to the Additional tab of components, and add a TTrayIcon to your form. Then change its 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);
begin
  SystrayIcon.Icon.LoadFromFile('/path_to_icon/icon.ico');
  SystrayIcon.ShowHint := True;
  SystrayIcon.Hint := 'my tool tip';

  SystrayIcon.PopUpMenu := MyPopUpMenu;

  SystrayIcon.Show;
end;

Example 2 - Creating the icon with TLazIntfImage

You can use TLazIntfImage to draw your icon quickly, as in the example code below:

procedure TForm1.DrawIcon;
var
  TempIntfImg: TLazIntfImage;
  ImgHandle, ImgMaskHandle: HBitmap;
  px, py: Integer;
  TempBitmap: TBitmap;
begin
  try
    TempIntfImg := TLazIntfImage.Create(16, 16);
    TempBitmap := TBitmap.Create;
    TempBitmap.Width := 16;
    TempBitmap.Height := 16;
    TempIntfImg.LoadFromBitmap(TempBitmap.Handle, TempBitmap.MaskHandle);

    // Set the pixels red
    for py := 0 to TempIntfImg.Height - 1 do
      for px := 0 to TempIntfImg.Width - 1 do
        TempIntfImg.Colors[px, py] := colRed;

    // Copy it to a TBitmap
    TempIntfImg.CreateBitmaps(ImgHandle,ImgMaskHandle, False);
    TempBitmap.Handle := ImgHandle;
    TempBitmap.MaskHandle := ImgMaskHandle;

    // And copy the TBitmap to your Icon
    SystrayIcon.Icon.Assign(TempBitmap);
    SystrayIcon.Show;
 
  finally
    TempIntfImg.Free;
    TempBitmap.Free;
  end;
end;

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 mailing list or on the Lazarus Forum.

Change Log

  1. 17/01/2006 - Available as a preview on the Lazarus subversion. Still under heavy construction, however.
  2. 24/01/2006 - Stable under win32, gnome and gtk1, but still waiting for gtk2 support. Lazarus 0.9.12 was release with this version.
  3. 17/02/2006 - Added support for gtk2 on subversion.
  4. July 2008 - Implements support for Qt 4
  5. July 2008 - Implements support for Carbon through PasCocoa

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.

Light bulb  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. Note that this does not apply to TrayIcons that are using the OS's AppIndicator interface. Certainly not Gnome, maybe not of desktops as time goes by.

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

macOS - TTrayIcon support is implemented using the menu bar extras. Unfortunately the API to use menu bar extras is only available in Cocoa and not in Carbon, so we use the stable PasCocoa bindings in the Carbon interface to support menu bar extras even in older FPC compilers and in the Cocoa interface we will use the more modern Objective Pascal syntax.

Mn menubaritems.jpg

To read more about menu bar extras:

  1. https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/StatusBar/StatusBar.html
  2. https://developer.apple.com/design/human-interface-guidelines/macos/extensions/menu-bar-extras/
  3. https://developer.apple.com/design/human-interface-guidelines/macos/menus/dock-menus/
  4. https://developer.apple.com/design/human-interface-guidelines/macos/system-capabilities/dock/
  5. https://developer.apple.com/design/human-interface-guidelines/macos/menus/menu-anatomy/
  6. http://en.wikipedia.org/wiki/Menu_extra

With this in mind an approach which supports all Platforms was created:

  • 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.

  • OnPaint event and Canvas property to draw the icon freely. Won´t work on Windows.

External Links