Difference between revisions of "How to use a TrayIcon"

From Lazarus wiki
Jump to navigationJump to search
Line 163: Line 163:
 
=== Subversion ===
 
=== Subversion ===
  
Zu finden uter components/trayicon/ im aktuellen Subversion-Verzeichnis
+
Zu finden unter components/trayicon/ im aktuellen Subversion-Verzeichnis
  
 
=== Help, Bug Reporting and Feature Request ===
 
=== Help, Bug Reporting and Feature Request ===

Revision as of 20:26, 7 February 2007

About

TrayIcon is a multiplatform System Tray component. It currently works on the following widgetsets: win32, Gtk1, Gnome, Gtk2. In the future it will also work for Carbon ( Mac OS X ) and Qt 4.

Two interfaces are supplied, a visual component and a non-visual object. The non-visual object is called SystrayIcon and it is compatible with Delphi. The visual component is called TTrayIcon and works only on Lazarus.

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;


ShowHint

property ShowHint: Boolean;


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

Felipe Monteiro de Carvalho

Andrew Haines

License

Modifyed LGPL.

Download

Status: Stable

Can be located at any recent Lazarus install at the directory: lazarus/components/trayicon

Installation

Demonstartionsprogram

Dieses Program läd ein Icon aus einer internen Ressource (unter Windows) bzw. aus einer externen datei (unter anderen Plattformen als Windows).

Um die Ressource mit dem Icon unter Windows zu erstellen und einzubinden ist folgendes nötig:

1. Erstellen sie ein Ressourcenskript traytest.rc wie dieses:

101               ICON                    "icon1.ico"

2. Compilieren sie das Ressourcenskript mittels windres.exe in eine *.res Datei. (Windres ist im Lazarusverzeichnis zu finden) Der Befehl lautet: windres -i traytest.rc -o traytest.res

Nu können sie ihr testprogramm schreiben. Erstellen sie eine neue Anwendung mit einem Formular und fügen sie in die entsprechende Unit folgendes in den Interface-Abschnitt ein:

{$ifdef win32}
  {$R traytest.res}
{$endif}

Als nächste benötigen sie noch einen Button. Schreiben sie folgendes in das OnClick-Event des Buttons:

procedure MyForm.Button1Click(Sender: TObject);
const
  IDI_ICON1         = 101;
begin
{$ifdef win32}
  SystrayIcon.Icon.Handle := LoadIcon(hInstance, MAKEINTRESOURCE(IDI_ICON1));
  //7. März 2006 - Das laden einer .ico-Datei unter Windows funktioniert nicht
{$else}
  SystrayIcon.Icon.LoadFromFile('/path_to_icon/icon.ico');
  //7. März 2006 - Es kann zu Problemen mit der Darstellung von .ico-Dateien kommen.
  //Ist dies der Fall, probieren sie xpm (dies löst das Problem unter FedoraCore 4 / Gnome)
{$endif}

  SystrayIcon.ShowHint := True;
  SystrayIcon.Hint := 'Mein Tooltip';

  SystrayIcon.PopUpMenu := MyPopUpMenu;

  SystrayIcon.Show;
end;

Subversion

Zu finden unter components/trayicon/ im aktuellen Subversion-Verzeichnis

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.

Technical Details

A difficulty on the development of this component was the many differences on the system tray implementation on varios OSes and even Window Managers on Linux. To solve this, the component tryes to implement the minimal set of features common to all target platforms. Bellow 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 alterred 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.

Linux (Gnome, KDE, IceWM, etc) - Multiple system tray icons per application are supported. The image of the icon is acctually a very small Window, and can be painted and receive events just like any other TForm descendent.

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 doesn´t 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