How to use a TrayIcon

From Lazarus wiki
Revision as of 11:29, 15 October 2019 by Dbannon (talk | contribs) (Linux may not display the Icon)

English (en)


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 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 workarounds that involve using another library, LibAppIndicator3 and in some cases other extra packages and specific configuration steps. Its important to note, and to advise your end users, that the problem is with the Linux Distribution and its Desktop. You, as the application's programer cannot directly solve the problem.

At the time of writing, October 2019, Gnome desktop versions of Fedora, Red Hat, Suse amd Mageia and Debian all require the library LibAppIndicator3 be installed and the Gnome Shell Extension, Top Icons Plus be installed.

Mageia Enlightenment also requires LibAppIndicator3 and enabling System Tray in Settings->Modules and the 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.

As of Lazarus 2.0.6, LCL will attempt to 'guess' the correct model to display a Tray Icon. However as distributions change over time, or with more obscure distributions you may need to override these guesses. By setting an enviourment variable, LAZUSEAPPIND you can force an app to try to use LibAppIndicator3, prevent it from trying or just tell us which way it has guessed using YES, NO or INFO. eg

LAZUSEAPPIND=YES project1 <enter>

Will force project1 to try to use LibAppindicator3. Obviously, it may not be available or it may not be suitable for the desktop in use but it will try. A line or two of text will be printed on stdout if the var is defined and not blank. Many systems will display the TrayIcon without using this environment variable. If the desktop you are running does require LibAppIndicator3, then you must accept all it can ever do is trigger a menu, no OnClick event.

Why two models ?

LibAppIndicator3 does not do as much as the older System Tray model. LibAppIndicator3 is an outgrowth of Unity's definition of a 'simpler' interface, it will display only a menu, it does not pass an event, OnClick, back to your app. Indeed, if you have not assigned a popup menu and LibAppIndicator3 is in use your Icon will not show up at all. So, applications that depend on getting a OnClick event will not work with LibAppIndicator3.

Developers of new applications may well be advised to design their program around TrayIcon using only a popUpMenu !


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 Debian [-based]
  • libappindicator-gtk3 - Arch, ALT, CentOS and Fedora, RedHat
  • libappindicator3_1 - all Mandrake/Mandriva derivatives -- Mageia, OpenMandriva, PCLinuxOS, Rosa


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 (?) -

As root -

dnf install make libappindicator-gtk3 gnome-tweak-tool

As yourself -

git clone
cd TopIcons-plus
make install

Logout and back in again.


In the app thats runs, click Extensions, turn TopIcons-plus ON and click close

Remember - LibAppIndicator3 and possibly TopIconsPlus may be needed on your end users machine !

Issue On the Mac, OSX

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, . 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 OSX using Cocoa Widget Set.

Note that TrayIcon on the Mac, Carbon (ie 32bit) has a memory leak.


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.



procedure Show;

Shows the icon on the system tray.


procedure Hide;

Removes the icon from the system tray.


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.



property Hint: string;

A Hint will be shown the string isn't empty


property PopUpMenu: TPopUpMenu;

A PopUp menu that appears when the user right-clicks the tray icon.



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.


property OnClick: TNotifyEvent;


property OnDblClick: TNotifyEvent;


property OnMouseDown: TMouseEvent;


property OnMouseUp: TMouseEvent;


property OnMouseMove: TMouseMoveEvent;



Note: Windows: Ozz Nixon


Modified LGPL.


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 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);
  SystrayIcon.ShowHint := True;
  SystrayIcon.Hint := 'my tool tip';

  SystrayIcon.PopUpMenu := MyPopUpMenu;


Example 2 - Creating the icon with TLazIntfImage

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

procedure TForm1.DrawIcon;
  TempIntfImg: TLazIntfImage;
  ImgHandle, ImgMaskHandle: HBitmap;
  px, py: Integer;
  TempBitmap: TBitmap;
    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


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

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


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

Mn menubaritems.jpg

To read more about menu bar extras:


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