The QSystemTrayIcon class provides an icon for an application in the system tray. More...

#include <qsystemtrayicon.h>

Inheritance diagram for QSystemTrayIcon:

Collaboration diagram for QSystemTrayIcon:

Public Types
enum	ActivationReason { Unknown , Context , DoubleClick , Trigger , MiddleClick }
	This enum describes the reason the system tray was activated. More...

enum	MessageIcon { NoIcon , Information , Warning , Critical }
	This enum describes the icon that is shown when a balloon message is displayed. More...

Public Slots
void	setVisible (bool visible)

void	show ()
	Shows the icon in the system tray.

void	hide ()
	Hides the system tray entry.

void	showMessage (const QString &title, const QString &msg, const QIcon &icon, int msecs=10000)

void	showMessage (const QString &title, const QString &msg, QSystemTrayIcon::MessageIcon icon=QSystemTrayIcon::Information, int msecs=10000)

Public Slots inherited from QObject
void	deleteLater ()
	\threadsafe

Signals
void	activated (QSystemTrayIcon::ActivationReason reason)
	This signal is emitted when the user activates the system tray icon.

void	messageClicked ()
	This signal is emitted when the message displayed using showMessage() was clicked by the user.

Signals inherited from QObject
void	destroyed (QObject *=nullptr)
	This signal is emitted immediately before the object obj is destroyed, after any instances of QPointer have been notified, and cannot be blocked.

void	objectNameChanged (const QString &objectName, QPrivateSignal)
	This signal is emitted after the object's name has been changed.

Public Member Functions
	QSystemTrayIcon (QObject *parent=nullptr)
	Constructs a QSystemTrayIcon object with the given parent.

	QSystemTrayIcon (const QIcon &icon, QObject *parent=nullptr)
	Constructs a QSystemTrayIcon object with the given icon and parent.

	~QSystemTrayIcon ()
	Removes the icon from the system tray and frees all allocated resources.

QIcon	icon () const

void	setIcon (const QIcon &icon)

QString	toolTip () const

void	setToolTip (const QString &tip)

QRect	geometry () const

bool	isVisible () const

Public Member Functions inherited from QObject
Q_INVOKABLE	QObject (QObject *parent=nullptr)
	Constructs an object with parent object parent.

virtual	~QObject ()
	Destroys the object, deleting all its child objects.

virtual bool	eventFilter (QObject watched, QEvent event)
	Filters events if this object has been installed as an event filter for the watched object.

QString	objectName () const

Q_WEAK_OVERLOAD void	setObjectName (const QString &name)
	Sets the object's name to name.

void	setObjectName (QAnyStringView name)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

QBindable< QString >	bindableObjectName ()

bool	isWidgetType () const
	Returns `true` if the object is a widget; otherwise returns `false`.

bool	isWindowType () const
	Returns `true` if the object is a window; otherwise returns `false`.

bool	isQuickItemType () const
	Returns `true` if the object is a QQuickItem; otherwise returns `false`.

bool	signalsBlocked () const noexcept
	Returns `true` if signals are blocked; otherwise returns `false`.

bool	blockSignals (bool b) noexcept
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it).

QThread *	thread () const
	Returns the thread in which the object lives.

bool	moveToThread (QThread *thread QT6_DECL_NEW_OVERLOAD_TAIL)
	Changes the thread affinity for this object and its children and returns `true` on success.

int	startTimer (int interval, Qt::TimerType timerType=Qt::CoarseTimer)
	This is an overloaded function that will start a timer of type timerType and a timeout of interval milliseconds.

int	startTimer (std::chrono::nanoseconds time, Qt::TimerType timerType=Qt::CoarseTimer)

void	killTimer (int id)
	Kills the timer with timer identifier, id.

void	killTimer (Qt::TimerId id)

template<typename T >
T	findChild (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns the child of this object that can be cast into type T and that is called name, or \nullptr if there is no such object.

template<typename T >
QList< T >	findChildren (QAnyStringView aName, Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects.

template<typename T >
T	findChild (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

template<typename T >
QList< T >	findChildren (Qt::FindChildOptions options=Qt::FindChildrenRecursively) const
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

const QObjectList &	children () const
	Returns a list of child objects.

void	setParent (QObject *parent)
	Makes the object a child of parent.

void	installEventFilter (QObject *filterObj)
	Installs an event filter filterObj on this object.

void	removeEventFilter (QObject *obj)
	Removes an event filter object obj from this object.

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const

bool	disconnect (const char signal=nullptr, const QObject receiver=nullptr, const char *member=nullptr) const

bool	disconnect (const QObject receiver, const char member=nullptr) const

void	dumpObjectTree () const
	Dumps a tree of children to the debug output.

void	dumpObjectInfo () const
	Dumps information about signal connections, etc.

bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value.

bool	setProperty (const char *name, QVariant &&value)

QVariant	property (const char *name) const
	Returns the value of the object's name property.

QList< QByteArray >	dynamicPropertyNames () const

QBindingStorage *	bindingStorage ()

const QBindingStorage *	bindingStorage () const

QObject *	parent () const
	Returns a pointer to the parent object.

bool	inherits (const char *classname) const
	Returns `true` if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns `false`.

Static Public Member Functions
static bool	isSystemTrayAvailable ()
	Returns `true` if the system tray is available; otherwise returns `false`.

static bool	supportsMessages ()
	Returns `true` if the system tray supports balloon messages; otherwise returns `false`.

Static Public Member Functions inherited from QObject
static QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char member, Qt::ConnectionType=Qt::AutoConnection)
	\threadsafe

static QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::ContextTypeForFunctor< Func2 >::ContextType context, Func2 &&slot, Qt::ConnectionType type=Qt::AutoConnection)

template<typename Func1 , typename Func2 >
static QMetaObject::Connection	connect (const typename QtPrivate::FunctionPointer< Func1 >::Object *sender, Func1 signal, Func2 &&slot)

static bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char member)
	\threadsafe

static bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &member)

static bool	disconnect (const QMetaObject::Connection &)
	Disconnect a connection.

template<typename Func1 , typename Func2 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const typename QtPrivate::FunctionPointer< Func2 >::Object receiver, Func2 slot)

template<typename Func1 >
static bool	disconnect (const typename QtPrivate::FunctionPointer< Func1 >::Object sender, Func1 signal, const QObject receiver, void **zero)

Protected Member Functions
bool	event (QEvent *event) override
	\reimp

Protected Member Functions inherited from QObject
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns \nullptr.

int	senderSignalIndex () const

int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal.

bool	isSignalConnected (const QMetaMethod &signal) const

virtual void	timerEvent (QTimerEvent *event)
	This event handler can be reimplemented in a subclass to receive timer events for the object.

virtual void	childEvent (QChildEvent *event)
	This event handler can be reimplemented in a subclass to receive child events.

virtual void	customEvent (QEvent *event)
	This event handler can be reimplemented in a subclass to receive custom events.

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	disconnectNotify (const QMetaMethod &signal)

	QObject (QObjectPrivate &dd, QObject *parent=nullptr)

Properties
QString	toolTip
	the tooltip for the system tray entry

QIcon	icon
	the system tray icon

bool	visible
	whether the system tray entry is visible

Properties inherited from QObject
QString	objectName
	the name of this object

Friends
class	QBalloonTip

Additional Inherited Members
Protected Attributes inherited from QObject
QScopedPointer< QObjectData >	d_ptr

Related Symbols inherited from QObject
template< class T > T	qobject_cast (const QObject *object)
	Returns the given object cast to type T if the object is of type T (or of a subclass); otherwise returns \nullptr.

template< typename T > T	qFindChildqFindChildren (const QObject *obj, const QString &name)()

template< typename T > QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()

	QObjectList
	\macro Q_CLASSINFO(Name, Value)

Detailed Description

The QSystemTrayIcon class provides an icon for an application in the system tray.

Since: 4.2

\inmodule QtWidgets

Modern operating systems usually provide a special area on the desktop, called the {system tray} or {notification area}, where long-running applications can display icons and short messages.

The system tray on Windows 10.

The QSystemTrayIcon class can be used on the following platforms:

\list

All supported versions of Windows.
All Linux desktop environments that implement the D-Bus \l{http://www.freedesktop.org/wiki/Specifications/StatusNotifierItem/StatusNotifierItem} {StatusNotifierItem specification}, including KDE, Gnome, Xfce, LXQt, and DDE.
All window managers and independent tray implementations for X11 that implement the \l{http://standards.freedesktop.org/systemtray-spec/systemtray-spec-0.2.html} {freedesktop.org XEmbed system tray specification}.
All supported versions of \macos. \endlist

To check whether a system tray is present on the user's desktop, call the QSystemTrayIcon::isSystemTrayAvailable() static function.

To add a system tray entry, create a QSystemTrayIcon object, call setContextMenu() to provide a context menu for the icon, and call show() to make it visible in the system tray. Status notification messages ("balloon messages") can be displayed at any time using showMessage().

If the system tray is unavailable when a system tray icon is constructed, but becomes available later, QSystemTrayIcon will automatically add an entry for the application in the system tray if the icon is \l visible.

The activated() signal is emitted when the user activates the icon.

Only on X11, when a tooltip is requested, the QSystemTrayIcon receives a QHelpEvent of type QEvent::ToolTip. Additionally, the QSystemTrayIcon receives wheel events of type QEvent::Wheel. These are not supported on any other platform. Note: Since GNOME Shell version 3.26, not all QSystemTrayIcon::ActivationReason are supported by the system without shell extensions installed.

See also: QDesktopServices, {Desktop Integration}, {System Tray Icon Example}

Definition at line 25 of file qsystemtrayicon.h.

Member Enumeration Documentation

◆ ActivationReason

enum QSystemTrayIcon::ActivationReason

This enum describes the reason the system tray was activated.

\value Unknown Unknown reason \value Context The context menu for the system tray entry was requested \value DoubleClick The system tray entry was double clicked.

Note: On macOS, a double click will only be emitted if no context menu is set, since the menu opens on mouse press \value Trigger The system tray entry was clicked \value MiddleClick The system tray entry was clicked with the middle mouse button

See also: activated()

Enumerator
Unknown
Context
DoubleClick
Trigger
MiddleClick

Definition at line 37 of file qsystemtrayicon.h.

◆ MessageIcon

enum QSystemTrayIcon::MessageIcon

This enum describes the icon that is shown when a balloon message is displayed.

\value NoIcon No icon is shown. \value Information An information icon is shown. \value Warning A standard warning icon is shown. \value Critical A critical warning icon is shown.

See also: QMessageBox

Enumerator
NoIcon
Information
Warning
Critical

Definition at line 59 of file qsystemtrayicon.h.

Constructor & Destructor Documentation

◆ QSystemTrayIcon() [1/2]

QSystemTrayIcon::QSystemTrayIcon ( QObject * parent = nullptr )

Constructs a QSystemTrayIcon object with the given parent.

The icon is initially invisible.

See also: visible

Definition at line 122 of file qsystemtrayicon.cpp.

◆ QSystemTrayIcon() [2/2]

QSystemTrayIcon::QSystemTrayIcon	(	const QIcon &	icon,
		QObject *	parent = nullptr )

Constructs a QSystemTrayIcon object with the given icon and parent.

The icon is initially invisible.

See also: visible

Definition at line 134 of file qsystemtrayicon.cpp.

References icon, and setIcon().

Here is the call graph for this function:

◆ ~QSystemTrayIcon()

QSystemTrayIcon::~QSystemTrayIcon ( )

Removes the icon from the system tray and frees all allocated resources.

Definition at line 143 of file qsystemtrayicon.cpp.

References d.

Member Function Documentation

◆ activated

void QSystemTrayIcon::activated ( QSystemTrayIcon::ActivationReason reason )

signal

This signal is emitted when the user activates the system tray icon.

reason specifies the reason for activation. QSystemTrayIcon::ActivationReason enumerates the various reasons.

See also: QSystemTrayIcon::ActivationReason

Referenced by QWidgetPlatformSystemTrayIcon::QWidgetPlatformSystemTrayIcon().

Here is the caller graph for this function:

◆ event()

bool QSystemTrayIcon::event ( QEvent * event )

overrideprotectedvirtual

\reimp

Reimplemented from QObject.

Definition at line 298 of file qsystemtrayicon.cpp.

References QObject::event().

Here is the call graph for this function:

◆ geometry()

QRect QSystemTrayIcon::geometry ( ) const

Since: 4.3 Returns the geometry of the system tray icon in screen coordinates.

See also: visible

Definition at line 260 of file qsystemtrayicon.cpp.

References d.

Referenced by QWidgetPlatformSystemTrayIcon::geometry().

Here is the caller graph for this function:

◆ hide

void QSystemTrayIcon::hide ( )

inlineslot

Hides the system tray entry.

See also: show(), visible

Definition at line 67 of file qsystemtrayicon.h.

Referenced by QWidgetPlatformSystemTrayIcon::cleanup().

Here is the caller graph for this function:

◆ icon()

QIcon QSystemTrayIcon::icon ( ) const

Definition at line 212 of file qsystemtrayicon.cpp.

References d.

◆ isSystemTrayAvailable()

bool QSystemTrayIcon::isSystemTrayAvailable ( )

static

Returns true if the system tray is available; otherwise returns false.

If the system tray is currently unavailable but becomes available later, QSystemTrayIcon will automatically add an entry in the system tray if it is \l visible.

Definition at line 351 of file qsystemtrayicon.cpp.

References QSystemTrayIconPrivate::isSystemTrayAvailable_sys().

Referenced by QWidgetPlatformSystemTrayIcon::isSystemTrayAvailable().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isVisible()

bool QSystemTrayIcon::isVisible ( ) const

Definition at line 289 of file qsystemtrayicon.cpp.

References d.

◆ messageClicked

void QSystemTrayIcon::messageClicked ( )

signal

This signal is emitted when the message displayed using showMessage() was clicked by the user.

Note: We follow Microsoft Windows behavior, so the signal is also emitted when the user clicks on a tray icon with a balloon message displayed.

See also: activated()

Referenced by QWidgetPlatformSystemTrayIcon::QWidgetPlatformSystemTrayIcon(), and QBalloonTip::mousePressEvent().

Here is the caller graph for this function:

◆ setIcon()

void QSystemTrayIcon::setIcon ( const QIcon & icon )

Definition at line 205 of file qsystemtrayicon.cpp.

References d, and icon.

Referenced by QSystemTrayIcon(), and QWidgetPlatformSystemTrayIcon::updateIcon().

Here is the caller graph for this function:

◆ setToolTip()

void QSystemTrayIcon::setToolTip ( const QString & tip )

Definition at line 225 of file qsystemtrayicon.cpp.

References d.

Referenced by QWidgetPlatformSystemTrayIcon::updateToolTip().

Here is the caller graph for this function:

◆ setVisible

void QSystemTrayIcon::setVisible ( bool visible )

slot

Definition at line 275 of file qsystemtrayicon.cpp.

References d, Q_UNLIKELY, qWarning, and visible.

◆ show

void QSystemTrayIcon::show ( )

inlineslot

Shows the icon in the system tray.

See also: hide(), visible

Definition at line 66 of file qsystemtrayicon.h.

Referenced by QWidgetPlatformSystemTrayIcon::init().

Here is the caller graph for this function:

◆ showMessage [1/2]

void QSystemTrayIcon::showMessage	(	const QString &	title,
		const QString &	msg,
		const QIcon &	icon,
		int	msecs = 10000 )

slot

Definition at line 406 of file qsystemtrayicon.cpp.

References d, icon, NoIcon, and title.

Referenced by QWidgetPlatformSystemTrayIcon::showMessage().

Here is the caller graph for this function:

◆ showMessage [2/2]

void QSystemTrayIcon::showMessage	(	const QString &	title,
		const QString &	message,
		QSystemTrayIcon::MessageIcon	icon = QSystemTrayIcon::Information,
		int	millisecondsTimeoutHint = 10000 )

slot

Since: 4.3

Shows a balloon message for the entry with the given title, message and icon for the time specified in millisecondsTimeoutHint. title and message must be plain text strings.

Message can be clicked by the user; the messageClicked() signal will emitted when this occurs.

Note that display of messages are dependent on the system configuration and user preferences, and that messages may not appear at all. Hence, it should not be relied upon as the sole means for providing critical information.

On Windows, the millisecondsTimeoutHint is usually ignored by the system when the application has focus.

Has been turned into a slot in Qt 5.2.

See also: show(), supportsMessages()

Definition at line 388 of file qsystemtrayicon.cpp.

References d, messageIcon2qIcon(), and title.

Here is the call graph for this function:

◆ supportsMessages()

bool QSystemTrayIcon::supportsMessages ( )

static

Returns true if the system tray supports balloon messages; otherwise returns false.

See also: showMessage()

Definition at line 361 of file qsystemtrayicon.cpp.

References QSystemTrayIconPrivate::supportsMessages_sys().

Referenced by QWidgetPlatformSystemTrayIcon::supportsMessages().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ toolTip()

QString QSystemTrayIcon::toolTip ( ) const

Definition at line 232 of file qsystemtrayicon.cpp.

References d.

Friends And Related Symbol Documentation

◆ QBalloonTip

friend class QBalloonTip

friend

Definition at line 86 of file qsystemtrayicon.h.

Property Documentation

◆ icon

QSystemTrayIcon::icon

readwrite

the system tray icon

On Windows, the system tray icon size is 16x16; on X11, the preferred size is 22x22. The icon will be scaled to the appropriate size as necessary.

Definition at line 29 of file qsystemtrayicon.h.

Referenced by QSystemTrayIcon(), setIcon(), and showMessage().

◆ toolTip

QSystemTrayIcon::toolTip

readwrite

the tooltip for the system tray entry

On some systems, the tooltip's length is limited. The tooltip will be truncated if necessary.

Definition at line 28 of file qsystemtrayicon.h.

◆ visible

QSystemTrayIcon::visible

readwrite

whether the system tray entry is visible

Setting this property to true or calling show() makes the system tray icon visible; setting this property to false or calling hide() hides it.

Definition at line 30 of file qsystemtrayicon.h.

Referenced by setVisible().

The documentation for this class was generated from the following files:

qtbase/src/widgets/util/qsystemtrayicon.h (05fc3aef53348fb58be6308076e000825b704e58)
qtbase/src/widgets/util/qsystemtrayicon.cpp (f5d192818dea30f1fbe53adc5211ff44563c16aa)

Public Types

Public Slots

Signals

Public Member Functions

Static Public Member Functions

Protected Member Functions

Properties

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ ActivationReason

◆ MessageIcon

Constructor & Destructor Documentation

◆ QSystemTrayIcon() [1/2]

◆ QSystemTrayIcon() [2/2]

◆ ~QSystemTrayIcon()

Member Function Documentation

◆ activated

◆ event()

◆ geometry()

◆ hide

◆ icon()

◆ isSystemTrayAvailable()

◆ isVisible()

◆ messageClicked

◆ setIcon()

◆ setToolTip()

◆ setVisible

◆ show

◆ showMessage [1/2]

◆ showMessage [2/2]

◆ supportsMessages()

◆ toolTip()

Friends And Related Symbol Documentation

◆ QBalloonTip

Property Documentation

◆ icon

◆ toolTip

◆ visible