Difference between revisions of "How to use a TrayIcon"

From Lazarus wiki
Line 2: Line 2:
  
 
=== About ===
 
=== About ===
 
+
'''[[TTrayIcon]]''' is a multiplatform System Tray component. You can find TrayIcon on the [[Additional tab]] of the [[Component Palette]] (0.9.23+).
'''TrayIcon''' is a multiplatform System Tray component. You can find TrayIcon on the Additional 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
 
TrayIcon used to be an optional component, but is part of LCL since Lazarus 0.9.23
Line 10: Line 9:
  
 
=== Documentation ===
 
=== 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.
 
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.
  
Line 16: Line 14:
  
 
==== Methods ====
 
==== Methods ====
 
 
<span style="color: teal">'''Show'''</span>
 
<span style="color: teal">'''Show'''</span>
  
Line 22: Line 19:
  
 
Shows the icon on the system tray.
 
Shows the icon on the system tray.
 
  
 
<span style="color: teal">'''Hide'''</span>
 
<span style="color: teal">'''Hide'''</span>
Line 29: Line 25:
  
 
Removes the icon from the system tray.
 
Removes the icon from the system tray.
 
  
 
<span style="color: teal">'''GetPosition'''</span>
 
<span style="color: teal">'''GetPosition'''</span>
Line 46: Line 41:
  
 
<span style="color: teal">'''PopUpMenu'''</span>
 
<span style="color: teal">'''PopUpMenu'''</span>
 
  
 
'''property''' PopUpMenu: TPopUpMenu;
 
'''property''' PopUpMenu: TPopUpMenu;
Line 53: Line 47:
  
 
==== Events ====
 
==== Events ====
 
 
<span style="color: teal">'''OnPaint'''</span>
 
<span style="color: teal">'''OnPaint'''</span>
  
Line 61: Line 54:
  
 
{{Note| Does not work on win32.}}
 
{{Note| Does not work on win32.}}
 
  
 
<span style="color: teal">'''OnClick'''</span>
 
<span style="color: teal">'''OnClick'''</span>
  
 
'''property''' OnClick: TNotifyEvent;
 
'''property''' OnClick: TNotifyEvent;
 
  
 
<span style="color: teal">'''OnDblClick'''</span>
 
<span style="color: teal">'''OnDblClick'''</span>
  
 
'''property''' OnDblClick: TNotifyEvent;
 
'''property''' OnDblClick: TNotifyEvent;
 
  
 
<span style="color: teal">'''OnMouseDown'''</span>
 
<span style="color: teal">'''OnMouseDown'''</span>
Line 81: Line 71:
  
 
'''property''' OnMouseUp: TMouseEvent;
 
'''property''' OnMouseUp: TMouseEvent;
 
  
 
<span style="color: teal">'''OnMouseMove'''</span>
 
<span style="color: teal">'''OnMouseMove'''</span>
  
 
'''property''' OnMouseMove: TMouseMoveEvent;
 
'''property''' OnMouseMove: TMouseMoveEvent;
 
=== Screenshot ===
 
 
  
 
=== Authors ===
 
=== Authors ===
 
+
* [[User:Sekelsenmat|Felipe Monteiro de Carvalho]]
[[User:Sekelsenmat|Felipe Monteiro de Carvalho]]
+
* [[User:AndrewH|Andrew Haines]]
 
 
[[User:AndrewH|Andrew Haines]]
 
  
 
{{Note| Windows: [[User:Ozznixon|Ozz Nixon]]}}
 
{{Note| Windows: [[User:Ozznixon|Ozz Nixon]]}}
  
 
=== License ===
 
=== License ===
 
 
Modified LGPL.
 
Modified LGPL.
  
 
=== Download ===
 
=== Download ===
 
 
Status: Stable
 
Status: Stable
  
Line 109: Line 91:
  
 
And on Lazaurs 0.9.23 or superior it is automatically installed with LCL
 
And on Lazaurs 0.9.23 or superior it is automatically installed with LCL
 
 
  
 
=== Example 1 - Using TIcon ===
 
=== 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.
 
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.
  
Line 132: Line 111:
  
 
=== 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 quickly your icon, as in the example code below:
  
Line 170: Line 148:
  
 
=== Subversion ===
 
=== Subversion ===
 
 
Located under components/trayicon/ on the latest subversion Lazarus.
 
Located under components/trayicon/ on the latest subversion Lazarus.
  
 
=== Help, Bug Reporting and Feature Request ===
 
=== Help, Bug Reporting and Feature Request ===
 
 
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].
  
Line 180: Line 156:
  
 
=== Change Log ===
 
=== Change Log ===
 
 
# 17/01/2006 - Available as a preview on the Lazarus subversion. Still under heavy construction, however.
 
# 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.
 
# 24/01/2006 - Stable under win32, gnome and gtk1, but still waiting for gtk2 support. Lazarus 0.9.12 was release with this version.
Line 188: Line 163:
  
 
=== Technical Details ===
 
=== 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:
 
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:
  
Line 204: Line 178:
  
 
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/documentation/UserExperience/Conceptual/OSXHIGuidelines/XHIGMenus/chapter_16_section_6.html
 
# http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/AppleHIGuidelines/XHIGMenus/XHIGMenus.html
 
# http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/AppleHIGuidelines/XHIGMenus/XHIGMenus.html
 
# 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 ===
 
 
* http://www.codeproject.com/shell/ctrayiconposition.asp - Code and theory to find the tray icon position under Windows
 
* 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
 
* 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.
  
 
[[Category:Tutorials]]
 
[[Category:Tutorials]]

Revision as of 01:46, 22 July 2016

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.

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.

Note-icon.png

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;

Authors

Note-icon.png

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 Lazaurs 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);
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 quickly your icon, 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 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-icon.png

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:

  1. http://developer.apple.com/documentation/UserExperience/Conceptual/OSXHIGuidelines/XHIGMenus/chapter_16_section_6.html
  2. http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/AppleHIGuidelines/XHIGMenus/XHIGMenus.html
  3. 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