How to use a TrayIcon: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		### About
2	2
3	3		[[TTrayIcon]] is a multiplatform System Tray component. You can find TrayIcon on the [[Additional tab]] of the [[Component Palette]] (0.9.23+).
4	4
5	5		It works reliably on Windows, MacOS and Linux (and similar) with all desktops except the Gnome Desktop. It can be made work with Gnome but perhaps that's despite the Gnome Developers efforts.
6	6
7	7		In use, drag the TrayIcon onto your form, assign an icon to it, assign a popup menu (with at least one menu item) to it and call its Show method
8	8
9	9		To start quickly, please read [[TrayIcon\|the demonstration program]].
10	10
11	11		### Linux may not display the Icon
12	12
13	13		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.
14	14
15	15		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 -
16	16
17	17		- 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.
18	18
19	19		- 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.
20	20
21	21		- On Gnome desktops, an additional item is needed, gnome-shell-extension-appindicator must be installed and enabled. See below.
22	22
23	23		- Developers of new (Linux) applications are advised to design their program around TrayIcon using only a popUpMenu !
24	24
25	25		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.
26	26
27	27		#### Force traditional SysTray GTK2 ONLY
28	28
29	29		This is a purely GTK2 behavior, not for GTK3, QT5 nor any non Linux widget set.
30	30
31	31		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.)
32	32
33	33		``` bash
34	34		LAZUSEAPPIND=NO myapp <enter>
35	35		```
36	36
37	37		#### UnityWSCtrls.GlobalUseAppInd GTK2 ONLY
38	38
39	39		Lazarus version 3.0 and later have an additional way to predetermine which of the two TrayIcon models will be used. This has been made necessary because of the growing inconsistency of TrayIcon models in Linux Distributions. For example, at present, apparently, no 32bit Linux will work with AppIndicator model and any Gnome based distro will only work with the AppIndicator. You can set UnityWSCtrls.GlobalUseAppInd depending on some checks about the system or config file setting in the startup code of your app.
40	40
41	41		To use UnityWSCtrls.GlobalUseAppInd you must include 'UnityCtrls' in the uses section of a unit, it can be set to one of the UnityWSCtrls.TUseAppIndInstruction values, (UseAppIndYes, UseAppIndNo, UseAppIndAuto). It MUST be set before your TrayIcon is created, so, put your code in the project's LPR file ahead of Application.CreateForm(TMainForm, MainForm) line, or, if you prefer, manually create your TrayIcon later in the startup process.
42	42
43	43		For example, this might appear in your LPR file -
44	44
45	45		``` pascal
46	46		uses
47	47		.....
48	48		{$ifdef LCLGTK2}
49	49		, unitywsctrls
50	50		{$endif};
51	51
52	52		{$R *.res}
53	53
54	54		// ----------------------------------------------------------------------------
55	55		// This about reading the command line and env for instructions re TrayIcon
56	56		// It applies to ONLY gtk2 and Lazarus >= 3.0.0 !
57	57		// ----------------------------------------------------------------------------
58	58		{$ifdef LCLGTK2}
59	59		function GetUseAppInd() : UnityWSCtrls.TUseAppIndInstruction;
60	60		var
61	61		EnvVar : string;
62	62		begin
63	63		Result := UnityWSCtrls.GlobalUseAppInd;
64	64		if Application.HasOption('useappind') then begin // Command line
65	65		if Application.GetOptionValue('useappind') = 'yes' then // if not set, leave it alone.
66	66		Result := UseAppIndYes
67	67		else if Application.GetOptionValue('useappind') = 'no' then
68	68		Result := UseAppIndNo; // Anything other than yes or no is ignored
69	69		end else begin
70	70		EnvVar := Application.EnvironmentVariable['LAZUSEAPPIND']; // EnvironmentVariable
71	71		if EnvVar = 'YES' then
72	72		Result := UseAppIndYes
73	73		else if EnvVar = 'NO' then
74	74		Result := UseAppIndNo;
75	75		end;
76	76		end;
77	77		{$endif}
78	78
79	79		begin
80	80		Application.Scaled := True;
81	81		Application.Title := 'tomboy-ng';
82	82		RequireDerivedFormResource:=True;
83	83		Application.Initialize;
84	84		{$ifdef LCLGTK2 }
85	85		{$ifdef CPUi386} // Note: unless Ayatana fix their problem, no option for Gnome users
86	86		// https://github.com/AyatanaIndicators/libayatana-appindicator/issues/76
87	87		UnityWSCtrls.GlobalUseAppInd := UnityWSCtrls.UseAppIndNo; // 32bit must be a 'no'.
88	88		{$endif}
89	89		UnityWSCtrls.GlobalUseAppInd := GetUseAppInd(); // Set before creating TrayIcon
90	90		{$endif}
91	91		Application.CreateForm(TMainForm, MainForm);
92	92		....
93	93		```
94	94
95	95		You most certainly do not have to set UnityWSCtrls.GlobalUseAppInd, in many case, its default settings will work. But it may not work for everyone, it does give you, the programmer, some control over the situation.
96	96
97	97		> Note: At present, late 2023, every 32bit Linux I tested would generate an Access Violation when calling a GTK2 TrayIcon.Show setup to use the AppIndicator. So, better wrap it with a Try .. Except on E: EAccessViolation do...
98	98
99	99		#### AppIndicator Libraries
100	100
101	101		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.
102	102
103	103		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 ...
104	104
105	105		- libappindicator3 - Slackware, NetBSD
106	106		- libappindicator3-1 - openSUSE and earlier Debian \[-based\]
107	107		- libappindicator-gtk3 - Arch, ALT, CentOS and Fedora, RedHat
108	108		- libappindicator3_1 - all Mandrake/Mandriva derivatives -- Mageia, OpenMandriva, PCLinuxOS, Rosa
109	109		- libayatana-appindicator3-1 - Debian Bullseye and most other Linuxs that offer Ayatana.
110	110
111	111		#### gnome-shell-extension-appindicator
112	112
113	113		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.
114	114
115	115		On Fedora, you can do this (note you don't need gnome-tweaks on Fedora 34) -
116	116
117	117		``` bash
118	118		sudo dnf install libappindicator-gtk3 gnome-shell-extension-appindicator gnome-tweaks [enter]
119	119		```
120	120
121	121		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 -
122	122
123	123		``` bash
124	124		gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com [enter]
125	125		```
126	126
127	127		Replace 'enable' with 'info' to get some diagnostic information.
128	128
129	129		Note, three steps, install, restart desktop, enable plugin !
130	130
131	131		Debian Bullseye appears to arrive with the Ayatana library pre installed but the Gnome version still requires gnome-shell-extension-appindicator, install as above.
132	132
133	133		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>
134	134
135	135		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.
136	136
137	137		#### Checking before invoking TrayIcon
138	138
139	139		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.
140	140
141	141		<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 !
142	142
143	143		#### On GTK3
144	144
145	145		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.
146	146
147	147		#### QT5 on Linux
148	148
149	149		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.
150	150
151	151		#### Showing the Icon before establishing its Menu
152	152
153	153		It has long been known that the System Tray Icon, on Linux at least, will not show if its .show function is called before it's popup menu has been assigned. No error shown, just no Icon to be seen.
154	154
155	155		However, in 2023 with the release of Ubuntu using Gnome Desktop 44.0, a new aspect appeared. If the popup menu assigned has, itself, no menu items when .show is called, the menu is never shown even after menu items are added. In the case of gtk2, we do get an error message (complete with spelling mistake) but we see no menu. With Qt5, no error message, we get a menu but in the wrong part of the screen, and, after a being displayed a few times, we loose even that. We do not see this issue on any other OS or even any other Linux Desktop. How very Gnome-ish !
156	156
157	157		So, in summary, if you are managing menu items dynamically, make sure you have at least one menu item added to the popup menu and that popup menu assigned to the TrayIcon BEFORE calling TrayIcon.show.
158	158
159	159		note: chapter about 32bit carbon removed as irreverent.
160	160
161	161		### Documentation
162	162
163	163		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.
164	164
165	165		A function works on all target platforms unless written otherwise.
166	166
167	167		#### Methods
168	168
169		-	~~<span style="color: teal">Show</span>~~
	169	+	Show
170	170
171	171		procedure Show;
172	172
173	173		Shows the icon on the system tray.
174	174
175		-	~~<span style="color: teal">Hide</span>~~
	175	+	Hide
176	176
177	177		procedure Hide;
178	178
179	179		Removes the icon from the system tray.
180	180
181		-	~~<span style="color: teal">GetPosition</span>~~
	181	+	GetPosition
182	182
183	183		function GetPosition: TPoint;
184	184
185	185		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.
186	186
187	187		#### Properties
188	188
189		-	~~<span style="color: teal">Hint</span>~~
	189	+	Hint
190	190
191	191		property Hint: string;
192	192
193	193		A Hint will be shown the string isn't empty
194	194
195		-	~~<span style="color: teal">PopUpMenu</span>~~
	195	+	PopUpMenu
196	196
197	197		property PopUpMenu: TPopUpMenu;
198	198
199	199		A PopUp menu that appears when the user right-clicks the tray icon.
200	200
201	201		#### Events
202	202
203		-	~~<span style="color: teal">OnPaint</span>~~
	203	+	OnPaint
204	204
205	205		property OnPaint: TNotifyEvent;
206	206
207	207		Use this to implement custom drawing to the icon. Draw using the canvas property of the icon.
208	208
209	209		> Note: Does not work on win32.
210	210
211	211		> Note: Following events not available on Linux if using the LibAppIndicator3 model, its menu only.
212	212
213		-	~~<span style="color: teal">OnClick</span>~~
	213	+	OnClick
214	214
215	215		property OnClick: TNotifyEvent;
216	216
217		-	~~<span style="color: teal">OnDblClick</span>~~
	217	+	OnDblClick
218	218
219	219		property OnDblClick: TNotifyEvent;
220	220
221		-	~~<span style="color: teal">OnMouseDown</span>~~
	221	+	OnMouseDown
222	222
223	223		property OnMouseDown: TMouseEvent;
224	224
225		-	~~<span style="color: teal">OnMouseUp</span>~~
	225	+	OnMouseUp
226	226
227	227		property OnMouseUp: TMouseEvent;
228	228
229		-	~~<span style="color: teal">OnMouseMove</span>~~
	229	+	OnMouseMove
230	230
231	231		property OnMouseMove: TMouseMoveEvent;
232	232
233	233		### Authors
234	234
235	235		- Felipe Monteiro de Carvalho
236	236		- Andrew Haines
237	237
238	238		> Note: Windows: Ozz Nixon
239	239
240	240		### License
241	241
242	242		Modified LGPL.
243	243
244	244		### Download
245	245
246	246		Status: Stable
247	247
248	248		Can be located at Lazarus 0.9.22 or inferior at the directory: lazarus/components/trayicon
249	249
250	250		And on Lazarus 0.9.23 or superior it is automatically installed with LCL
251	251
252	252		### Example 1 - Using TIcon
253	253
254	254		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.
255	255
256	256		Go to the Additional tab of components, and add a TTrayIcon to your form. Then change its Name property to SystrayIcon
257	257
258	258		Next add a button to the form. Double click the button and add this code to it:
259	259
260	260		``` pascal
261	261		procedure MyForm.Button1Click(Sender: TObject);
262	262		begin
263	263		SystrayIcon.Icon.LoadFromFile('/path_to_icon/icon.ico');
264	264		SystrayIcon.ShowHint := True;
265	265		SystrayIcon.Hint := 'my tool tip';
266	266
267	267		SystrayIcon.PopUpMenu := MyPopUpMenu;
268	268
269	269		SystrayIcon.Show;
270	270		end;
271	271		```
272	272
273	273		### Example 2 - Creating the icon with TLazIntfImage
274	274
275	275		You can use TLazIntfImage to draw your icon quickly, as in the example code below:
276	276
277	277		``` pascal
278	278		procedure TForm1.DrawIcon;
279	279		var
280	280		TempIntfImg: TLazIntfImage;
281	281		ImgHandle, ImgMaskHandle: HBitmap;
282	282		px, py: Integer;
283	283		TempBitmap: TBitmap;
284	284		begin
285	285		try
286	286		TempIntfImg := TLazIntfImage.Create(16, 16);
287	287		TempBitmap := TBitmap.Create;
288	288		TempBitmap.Width := 16;
289	289		TempBitmap.Height := 16;
290	290		TempIntfImg.LoadFromBitmap(TempBitmap.Handle, TempBitmap.MaskHandle);
291	291
292	292		// Set the pixels red
293	293		for py := 0 to TempIntfImg.Height - 1 do
294	294		for px := 0 to TempIntfImg.Width - 1 do
295	295		TempIntfImg.Colors[px, py] := colRed;
296	296
297	297		// Copy it to a TBitmap
298	298		TempIntfImg.CreateBitmaps(ImgHandle,ImgMaskHandle, False);
299	299		TempBitmap.Handle := ImgHandle;
300	300		TempBitmap.MaskHandle := ImgMaskHandle;
301	301
302	302		// And copy the TBitmap to your Icon
303	303		SystrayIcon.Icon.Assign(TempBitmap);
304	304		SystrayIcon.Show;
305	305
306	306		finally
307	307		TempIntfImg.Free;
308	308		TempBitmap.Free;
309	309		end;
310	310		end;
311	311		```
312	312
313	313		### Subversion
314	314
315	315		Located under components/trayicon/ on the latest subversion Lazarus.
316	316
317	317		### Help, Bug Reporting and Feature Request
318	318
319	319		Please, post Bug Reports and Feature Requests on the [Lazarus Bugtracker](http://bugs.freepascal.org/main_page.php).
320	320
321	321		Help requests can be posted on the Lazarus mailing list or on the Lazarus [Forum](http://www.lazarus.freepascal.org/modules.php?op=modload&name=PNphpBB2&file=index).
322	322
323	323		### Change Log
324	324
325	325		1. 17/01/2006 - Available as a preview on the Lazarus subversion. Still under heavy construction, however.
326	326		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.
327	327		3. 17/02/2006 - Added support for gtk2 on subversion.
328	328		4. July 2008 - Implements support for Qt 4
329	329		5. July 2008 - Implements support for Carbon through [[PasCocoa]]
330	330
331	331		### Technical Details
332	332
333	333		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:
334	334
335	335		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.
336	336
337	337		> 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.
338	338
339	339		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.
340	340
341	341		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](http://icculus.org/openbox/2/docker/) and [WMSystray](http://freshmeat.net/projects/wmsystray/)
342	342
343	343		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.
344	344
345		-	~~<figure>~~
346		-	~~<img src="Mn_menubaritems.jpg" title="Mn_menubaritems.jpg" />~~
347		-	~~<figcaption>Mn_menubaritems.jpg</figcaption>~~
348		-	~~</figure>~~
	345	+	![](/wiki-images/9/97/Mn_menubaritems.jpg)
349	346
350	347		To read more about menu bar extras:
351	348
352	349		1. <https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/StatusBar/StatusBar.html>
353	350		2. <https://developer.apple.com/design/human-interface-guidelines/macos/extensions/menu-bar-extras/>
354	351		3. <https://developer.apple.com/design/human-interface-guidelines/macos/menus/dock-menus/>
355	352		4. <https://developer.apple.com/design/human-interface-guidelines/macos/system-capabilities/dock/>
356	353		5. <https://developer.apple.com/design/human-interface-guidelines/macos/menus/menu-anatomy/>
357	354		6. <http://en.wikipedia.org/wiki/Menu_extra>
358	355
359	356		With this in mind an approach which supports all Platforms was created:
360	357
361	358		- Painting is done via a TIcon object. (Required by Windows)
362	359
363	360		The following extra features are already available or will be, but they won´t work on all platforms.
364	361
365	362		- OnPaint event and Canvas property to draw the icon freely. Won´t work on Windows.
366	363
367	364		### External Links
368	365
369	366		- <http://www.codeproject.com/shell/ctrayiconposition.asp> - Code and theory to find the tray icon position under Windows
370	367		- <http://cvs.gnome.org/viewcvs/gtk%2B/gtk/gtkstatusicon.c?rev=1.23&view=markup> - Gtk2 code that implements gtkstatusicon
371	368		- <http://pasmontray.sourceforge.net> - Open source program that uses TrayIcon to display CPU and memory utilisation in the system tray.
372	369		- [Background to Debian's switch from libappindicator to Ayatana](https://lists.debian.org/debian-devel/2018/03/msg00506.html)
373	370		- [Ayatana App Indicator](https://github.com/AyatanaIndicators/libayatana-appindicator)
374	371
375	372		---
376	373		From the Free Pascal wiki, page "How to use a TrayIcon", as it stood on 2023-12-09 after a change by Dbannon, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
377	374		Category: Tutorials

Back to history