TTrayIcon class

In unit ExtCtrls

Implements a multi-platform system tray component.

Declaration

pascal

TTrayIcon = class(TCustomTrayIcon)

Inheritance

Description

TTrayIcon is a TCustomTrayIcon descendant which implements a multi-platform System Tray component. It allows an icon to be displayed in the system tray when the Application or Form is active. TTrayIcon provides properties, methods, and events used to configure, display, and control the tray icon. It sets the visibility for properties from ancestor classes. The component is supported on multiple platforms, but its implementation is platform-specific.

On the Windows platform, the system tray is usually located on the bottom-right corner of the screen, but it can be located on other edges for the physical screen. For other platforms, the position and other features varies according to the window or display manager in use.

On the GTK2 platform, there are two competing models used in the widgetset implementation for the tray icon class: the traditional system tray icon and the AppIndicator library. Starting with Lazarus version 3.0, the GlobalUseAppInd variable in unitywsctrls,pas can be used at run-time to enable, disable, or auto-detect use of the AppIndicator library. You MUST use the UnityWSCtrls unit and set the value in GlobalUseAppIndBEFORE the tray icon is created, so setting the value in the project .LPR file is recommended. Or, create your TrayIcon later in the startup process. The fallback is to use the standard system tray icon model in GTK2. This feature applies to the GTK2 platform only, and any related code should be wrapped with {$ifdef gtk2}.

For an in-depth exploration of using TTrayIcon on GTK2, see the wiki page at:

How to use a TrayIcon

Use Icon to set the icon image type displayed for the control. Use Icons to assign a list of images displayed as the animated icon for the control when the Show method is called.

Use BalloonFlags, BalloonHint, BalloonTimeout and BalloonTitle to format and display balloon hints for the tray icon. If balloon hints are not supported for the platform, an internal TPopupNotifier is used to display the Hint for the control.

Use PopUpMenu to set the menu displayed when the icon is right clicked with the mouse.

Assign routines to the event handlers to perform actions needed when the icon is clicked - or when mouse move, up, or down messages are received.

TCustomTrayIcon / TTrayIcon are partially compatible with the Delphi VCL component. It adds an OnPaint event handler which does not exist in Delphi. It omits properties like IconIndex and OnBalloonClick.

Properties

`BalloonFlags`	published	Defines the balloon flag displayed for the tray icon balloon hint.
`BalloonHint`	published	The text displayed in the balloon hint window.
`BalloonTimeout`	published	The interval after which the balloon hint disappears.
`BalloonTitle`	published	Title used for the balloon hint window.
`PopUpMenu`	published	Pop-up menu displayed when right mouse button is clicked over the icon for the control.
`Icon`	published	The Icon or picture that displayed on the tray icon.
`Hint`	published	Hint text displayed when the mouse is hovered over the tray icon.
`Visible`	published	Indicates if the tray icon is displayed in the system tray.

Events

`OnClick`	published	Event handler signalled when a mouse button is single-clicked on the tray icon.
`OnDblClick`	published	Event handler signalled when a mouse button is double-clicked on the tray icon.
`OnMouseDown`	published	Event handler signalled when a mouse button down event is detected for the tray icon.
`OnMouseMove`	published	Event handler signalled when a WM_MOUSEMOVE message is handled for the tray icon.
`OnMouseUp`	published	Event handler signalled when a mouse button up event is detected for the tray icon.
`OnPaint`	published	Event handler signalled to implement custom drawing for the tray icon.