[Overview][Types][Classes][Procedures and functions][Index] | Reference for unit 'ExtCtrls' (#lcl)

# TCustomTrayIcon

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

Defines the base class for a multi-platform system tray icon component.

## Declaration

Source position: extctrls.pp line 1408

`type TCustomTrayIcon = class(TLCLComponent)`
`protected`
`class procedure WSRegisterClass; override;` |  | Registers this component class with the current WidgetSet.
`procedure Notification(); override;` |  | Performs action when a component is added to or removed from the class instance at run-time.
`procedure Loaded; override;` |  | Performs actions needed when the component has finished loading from the LCL streaming mechanism.
`public`
`Handle: HWND;` |  | Operating system Handle for the Tray Icon.
`constructor Create(); override;` |  | Constructor for the class instance.
`destructor Destroy; override;` |  | Destructor for the class instance.
`function Hide;` |  | Removes the icon from the System Tray.
`function Show;` |  | Displays the icon in the System Tray.
`procedure InternalUpdate;` |  | Updates the control for any pending changes.
`procedure ShowBalloonHint;` |  | Displays a balloon hint window near the tray icon.
`function GetPosition;` |  | Gets the position for the tray icon on the display.
`property Animate: Boolean; [rw]` |  | Indicates if animations are displayed on the tray icon.
`property AnimateInterval: Cardinal; [rw]` |  | Defines the time interval between updates to the image for the tray icon.
`property BalloonFlags: TBalloonFlags; [rw]` |  | Defines the balloon flag displayed for the tray icon balloon hint.
`property BalloonHint: string; [rw]` |  | The text displayed in the balloon hint window.
`property BalloonTimeout: Integer; [rw]` |  | The interval after which the balloon hint disappears.
`property BalloonTitle: string; [rw]` |  | Title used for the balloon hint window.
`property Canvas: TCanvas; [r]` |  | Canvas for the class instance.
`property PopUpMenu: TPopupMenu; [rw]` |  | Pop-up menu displayed when right mouse button is clicked over the icon for the control.
`property Icon: TIcon; [rw]` |  | The Icon or picture that displayed on the tray icon.
`property Icons: TCustomImageList; [rw]` |  | Image list with the bitmaps used for an animated icon.
`property Hint: string; [rw]` |  | Hint text displayed when the mouse is hovered over the tray icon.
`property ShowIcon: Boolean; [rw]` |  | Indicates whether the Icon is drawn by the control (in its widgetset class).
`property Visible: Boolean; [rw]` |  | Indicates if the tray icon is displayed in the system tray.
`property OnClick: TNotifyEvent; [rw]` |  | Event handler signalled when a mouse button is single-clicked on the tray icon.
`property OnDblClick: TNotifyEvent; [rw]` |  | Event handler signalled when a mouse button is double-clicked on the tray icon.
`property OnMouseDown: TMouseEvent; [rw]` |  | Event handler signalled when a mouse button down event is detected for the tray icon.
`property OnMouseUp: TMouseEvent; [rw]` |  | Event handler signalled when a mouse button up event is detected for the tray icon.
`property OnMouseMove: TMouseMoveEvent; [rw]` |  | Event handler signalled when a WM_MOUSEMOVE message is handled for the tray icon.
`property OnPaint: TNotifyEvent; [rw]` |  | Event handler signalled to implement custom drawing for the tray icon.
`end;`

## Inheritance

`TCustomTrayIcon` |  | Defines the base class for a multi-platform system tray icon component.
`TLCLComponent` |  | The base class for LCL components which have an associated widget.
`TComponent`
?
`TObject`

## Description

TCustomTrayIcon is the base class for TTrayIcon, a multi-platform system tray icon component. It allows an icon to be displayed in the system tray when the Application or Form is active. TCustomTrayIcon provides properties, methods, and events used to configure, display, and control the tray icon. 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 GlobalUseAppInd BEFORE 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.

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

## See also

TTrayIcon |  | Implements a multi-platform system tray component.