TCustomTrayIcon class

In unit ExtCtrls

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

Declaration

pascal

TCustomTrayIcon = class(TLCLComponent)

Inheritance

Descends from it: TTrayIcon

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 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

`Animate`	public	Indicates if animations are displayed on the tray icon.
`AnimateInterval`	public	Defines the time interval between updates to the image for the tray icon.
`BalloonFlags`	public	Defines the balloon flag displayed for the tray icon balloon hint.
`BalloonHint`	public	The text displayed in the balloon hint window.
`BalloonTimeout`	public	The interval after which the balloon hint disappears.
`BalloonTitle`	public	Title used for the balloon hint window.
`Canvas`	public	Canvas for the class instance.
`PopUpMenu`	public	Pop-up menu displayed when right mouse button is clicked over the icon for the control.
`Icon`	public	The Icon or picture that displayed on the tray icon.
`Icons`	public	Image list with the bitmaps used for an animated icon.
`Hint`	public	Hint text displayed when the mouse is hovered over the tray icon.
`ShowIcon`	public	Indicates whether the Icon is drawn by the control (in its widgetset class).
`Visible`	public	Indicates if the tray icon is displayed in the system tray.

Methods

`WSRegisterClass`	protected	Registers this component class with the current WidgetSet.
`Notification`	protected	Performs action when a component is added to or removed from the class instance at run-time.
`Loaded`	protected	Performs actions needed when the component has finished loading from the LCL streaming mechanism.
`Create`	public	Constructor for the class instance.
`Destroy`	public	Destructor for the class instance.
`Hide`	public	Removes the icon from the System Tray.
`Show`	public	Displays the icon in the System Tray.
`InternalUpdate`	public	Updates the control for any pending changes.
`ShowBalloonHint`	public	Displays a balloon hint window near the tray icon.
`GetPosition`	public	Gets the position for the tray icon on the display.

Events

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