QSystemTrayIcon Class Reference

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

#include <qsystemtrayicon.h>

Inheritance 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	hide ()
	Hides the system tray entry. More...
void	setVisible (bool visible)
void	show ()
	Shows the icon in the system tray. More...
Public Slots inherited from QObject
void	deleteLater ()
	Schedules this object for deletion. More...

Signals
void	activated (QSystemTrayIcon::ActivationReason reason)
	This signal is emitted when the user activates the system tray icon. More...
void	messageClicked ()
	This signal is emitted when the message displayed using showMessage() was clicked by the user. More...
Signals inherited from QObject
void	destroyed (QObject *=0)
	This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...

Public Functions
QMenu *	contextMenu () const
	Returns the current context menu for the system tray entry. More...
QRect	geometry () const
	Returns the geometry of the system tray icon in screen coordinates. More...
QIcon	icon () const
bool	isVisible () const
	QSystemTrayIcon (QObject *parent=0)
	Constructs a QSystemTrayIcon object with the given parent. More...
	QSystemTrayIcon (const QIcon &icon, QObject *parent=0)
	Constructs a QSystemTrayIcon object with the given icon and parent. More...
void	setContextMenu (QMenu *menu)
	Sets the specified menu to be the context menu for the system tray icon. More...
void	setIcon (const QIcon &icon)
void	setToolTip (const QString &tip)
void	showMessage (const QString &title, const QString &msg, MessageIcon icon=Information, int msecs=10000)
	Shows a balloon message for the entry with the given title, message and icon for the time specified in millisecondsTimeoutHint. More...
QString	toolTip () const
	~QSystemTrayIcon ()
	Removes the icon from the system tray and frees all allocated resources. More...
Public Functions inherited from QObject
bool	blockSignals (bool b)
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...
const QObjectList &	children () const
	Returns a list of child objects. More...
bool	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=0, const QObject *receiver=0, const char *member=0)
bool	disconnect (const QObject *receiver, const char *member=0)
void	dumpObjectInfo ()
	Dumps information about signal connections, etc. More...
void	dumpObjectTree ()
	Dumps a tree of children to the debug output. More...
QList< QByteArray >	dynamicPropertyNames () const
	Returns the names of all properties that were dynamically added to the object using setProperty(). More...
virtual bool	eventFilter (QObject *, QEvent *)
	Filters events if this object has been installed as an event filter for the watched object. More...
template<typename T >
T	findChild (const QString &aName=QString()) const
	Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...
template<typename T >
QList< T >	findChildren (const QString &aName=QString()) 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. More...
template<typename T >
QList< T >	findChildren (const QRegExp &re) const
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. More...
void	installEventFilter (QObject *)
	Installs an event filter filterObj on this object. More...
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false. More...
void	killTimer (int id)
	Kills the timer with timer identifier, id. More...
virtual const QMetaObject *	metaObject () const
	Returns a pointer to the meta-object of this object. More...
void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children. More...
QString	objectName () const
QObject *	parent () const
	Returns a pointer to the parent object. More...
QVariant	property (const char *name) const
	Returns the value of the object's name property. More...
Q_INVOKABLE	QObject (QObject *parent=0)
	Constructs an object with parent object parent. More...
void	removeEventFilter (QObject *)
	Removes an event filter object obj from this object. More...
void	setObjectName (const QString &name)
void	setParent (QObject *)
	Makes the object a child of parent. More...
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value. More...
void	setUserData (uint id, QObjectUserData *data)
bool	signalsBlocked () const
	Returns true if signals are blocked; otherwise returns false. More...
int	startTimer (int interval)
	Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...
QThread *	thread () const
	Returns the thread in which the object lives. More...
QObjectUserData *	userData (uint id) const
virtual	~QObject ()
	Destroys the object, deleting all its child objects. More...

Static Public Functions
static bool	isSystemTrayAvailable ()
	Returns true if the system tray is available; otherwise returns false. More...
static bool	supportsMessages ()
	Returns true if the system tray supports balloon messages; otherwise returns false. More...
Static Public Functions inherited from QObject
static bool	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...
static bool	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	Disconnects signal in object sender from method in object receiver. More...
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static uint	registerUserData ()
static QString	tr (const char *sourceText, const char *comment=0, int n=-1)
static QString	trUtf8 (const char *sourceText, const char *comment=0, int n=-1)

Protected Functions
bool	event (QEvent *event)
	Reimplemented Function More...
Protected Functions inherited from QObject
virtual void	childEvent (QChildEvent *)
	This event handler can be reimplemented in a subclass to receive child events. More...
virtual void	connectNotify (const char *signal)
	This virtual function is called when something has been connected to signal in this object. More...
virtual void	customEvent (QEvent *)
	This event handler can be reimplemented in a subclass to receive custom events. More...
virtual void	disconnectNotify (const char *signal)
	This virtual function is called when something has been disconnected from signal in this object. More...
	QObject (QObjectPrivate &dd, QObject *parent=0)
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal. More...
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 0. More...
int	senderSignalIndex () const
virtual void	timerEvent (QTimerEvent *)
	This event handler can be reimplemented in a subclass to receive timer events for the object. More...

Properties
QIcon	icon
	the system tray icon More...
QString	toolTip
	the tooltip for the system tray entry More...
bool	visible
	whether the system tray entry is visible More...

Friends
class	QBalloonTip
class	QSystemTrayIconSys
void	qtsystray_sendActivated (QSystemTrayIcon *, int)

Additional Inherited Members
Static Public Variables inherited from QObject
static const QMetaObject	staticMetaObject
	This variable stores the meta-object for the class. More...
Protected Variables inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Static Protected Variables inherited from QObject
static const QMetaObject	staticQtMetaObject
Related Functions inherited from QObject
T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QRegExp &regExp)()
T *	qobject_cast (QObject *object)
	QObjectList
void *	qt_find_obj_child (QObject *parent, const char *type, const QString &name)
	Returns a pointer to the object named name that inherits type and with a given parent. More...

Detailed Description

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

Since

4.2

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

The QSystemTrayIcon class can be used on the following platforms:

• All supported versions of Windows.
• All window managers for X11 that implement the freedesktop.org system tray specification, including recent versions of KDE and GNOME.
• All supported versions of Mac OS X. Note that the Growl notification system must be installed for QSystemTrayIcon::showMessage() to display messages.

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

See also

QDesktopServices, QDesktopWidget, {Desktop Integration}, {System Tray Icon Example}

Definition at line 65 of file qsystemtrayicon.h.

Enumerations

ActivationReason

enum QSystemTrayIcon::ActivationReason

This enum describes the reason the system tray was activated.

• Unknown Unknown reason
• Context The context menu for the system tray entry was requested
• DoubleClick The system tray entry was double clicked
• Trigger The system tray entry was clicked
• MiddleClick The system tray entry was clicked with the middle mouse button

See also

activated()

Enumerator
Unknown
Context
DoubleClick
Trigger
MiddleClick

Definition at line 77 of file qsystemtrayicon.h.

                          {
        Unknown,
        Context,
        DoubleClick,
        Trigger,
        MiddleClick
    };

MessageIcon

enum QSystemTrayIcon::MessageIcon

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

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

See also

QMessageBox

Enumerator
NoIcon
Information
Warning
Critical

Definition at line 99 of file qsystemtrayicon.h.

{ NoIcon, Information, Warning, Critical };

Constructors and Destructors

QSystemTrayIcon() [1/2]

QSystemTrayIcon::QSystemTrayIcon

(

QObject *

parent = 0

)

Constructs a QSystemTrayIcon object with the given parent.

The icon is initially invisible.

See also

visible

Definition at line 134 of file qsystemtrayicon.cpp.

: QObject(*new QSystemTrayIconPrivate(), parent)
{
}

QSystemTrayIcon() [2/2]

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

Constructs a QSystemTrayIcon object with the given icon and parent.

The icon is initially invisible.

See also

visible

Definition at line 146 of file qsystemtrayicon.cpp.

: QObject(*new QSystemTrayIconPrivate(), parent)
{
    setIcon(icon);
}

~QSystemTrayIcon()

QSystemTrayIcon::~QSystemTrayIcon

(

)

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

Definition at line 155 of file qsystemtrayicon.cpp.

{
    Q_D(QSystemTrayIcon);
    d->remove_sys();
}

Functions

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 QSystemTrayIconSys::mouseDoubleClickEvent(), QSystemTrayIconSys::mousePressEvent(), qtsystray_sendActivated(), and QSystemTrayIconSys::winEvent().

contextMenu()

QMenu * QSystemTrayIcon::contextMenu

(

)

const

Returns the current context menu for the system tray entry.

Definition at line 186 of file qsystemtrayicon.cpp.

Referenced by QSystemTrayIconSys::mousePressEvent(), and QSystemTrayIconSys::winEvent().

{
    Q_D(const QSystemTrayIcon);
    return d->menu;
}

event()

bool QSystemTrayIcon::event ( QEvent *  event )

protectedvirtual

Reimplemented Function

Reimplemented from QObject.

Definition at line 312 of file qsystemtrayicon.cpp.

{
#if defined(Q_WS_X11)
    if (e->type() == QEvent::ToolTip) {
        Q_D(QSystemTrayIcon);
        return d->sys->deliverToolTipEvent(e);
    }
#endif
    return QObject::event(e);
}

geometry()

QRect QSystemTrayIcon::geometry

(

)

const

Returns the geometry of the system tray icon in screen coordinates.

Since

4.3

See also

visible

Definition at line 271 of file qsystemtrayicon.cpp.

{
    Q_D(const QSystemTrayIcon);
    if (!d->visible)
        return QRect();
    return d->geometry_sys();
}

hide

void QSystemTrayIcon::hide ( )

inlineslot

Hides the system tray entry.

See also

show(), visible

Definition at line 109 of file qsystemtrayicon.h.

{ setVisible(false); }

icon()

QIcon QSystemTrayIcon::icon

(

)

const

Referenced by setIcon().

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

Definition at line 380 of file qsystemtrayicon.cpp.

{
    return QSystemTrayIconPrivate::isSystemTrayAvailable_sys();
}

isVisible()

bool QSystemTrayIcon::isVisible

(

)

const

Definition at line 303 of file qsystemtrayicon.cpp.

{
    Q_D(const QSystemTrayIcon);
    return d->visible;
}

messageClicked

void QSystemTrayIcon::messageClicked ( )

signal

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

Currently this signal is not sent on Mac OS X.

Note

We follow Microsoft Windows XP/Vista 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 QBalloonTip::mousePressEvent(), QSystemTrayIconSys::mousePressEvent(), and QSystemTrayIconSys::winEvent().

setContextMenu()

void QSystemTrayIcon::setContextMenu

(

QMenu *

menu

)

Sets the specified menu to be the context menu for the system tray icon.

The menu will pop up when the user requests the context menu for the system tray icon by clicking the mouse button.

On Mac OS X, this is currenly converted to a NSMenu, so the aboutToHide() signal is not emitted.

Note

The system tray icon does not take ownership of the menu. You must ensure that it is deleted at the appropriate time by, for example, creating the menu with a suitable parent object.

Definition at line 176 of file qsystemtrayicon.cpp.

{
    Q_D(QSystemTrayIcon);
    d->menu = menu;
    d->updateMenu_sys();
}

setIcon()

void QSystemTrayIcon::setIcon

(

const QIcon &

icon

)

Definition at line 204 of file qsystemtrayicon.cpp.

Referenced by QSystemTrayIcon().

{
    Q_D(QSystemTrayIcon);
    d->icon = icon;
    d->updateIcon_sys();
}

setToolTip()

void QSystemTrayIcon::setToolTip

(

const QString &

tip

)

Definition at line 227 of file qsystemtrayicon.cpp.

{
    Q_D(QSystemTrayIcon);
    d->toolTip = tooltip;
    d->updateToolTip_sys();
}

setVisible

void QSystemTrayIcon::setVisible ( bool  visible )

slot

Definition at line 289 of file qsystemtrayicon.cpp.

{
    Q_D(QSystemTrayIcon);
    if (visible == d->visible)
        return;
    if (d->icon.isNull() && visible)
        qWarning("QSystemTrayIcon::setVisible: No Icon set");
    d->visible = visible;
    if (d->visible)
        d->install_sys();
    else
        d->remove_sys();
}

show

void QSystemTrayIcon::show ( )

inlineslot

Shows the icon in the system tray.

See also

hide(), visible

Definition at line 108 of file qsystemtrayicon.h.

{ setVisible(true); }

showMessage()

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

Shows a balloon message for the entry with the given title, message and icon for the time specified in millisecondsTimeoutHint.

Since

4.3

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.

On Mac OS X, the Growl notification system must be installed for this function to display messages.

See also

show() supportsMessages()

Definition at line 421 of file qsystemtrayicon.cpp.

{
    Q_D(QSystemTrayIcon);
    if (d->visible)
        d->showMessage_sys(title, msg, icon, msecs);
}

supportsMessages()

bool QSystemTrayIcon::supportsMessages ( )

static

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

See also

showMessage()

Definition at line 390 of file qsystemtrayicon.cpp.

{
    return QSystemTrayIconPrivate::supportsMessages_sys();
}

toolTip()

QString QSystemTrayIcon::toolTip

(

)

const

Referenced by setToolTip().

Friends and Related Functions

QBalloonTip

friend class QBalloonTip

friend

Definition at line 123 of file qsystemtrayicon.h.

Referenced by QBalloonTip::showBalloon().

QSystemTrayIconSys

friend class QSystemTrayIconSys

friend

Definition at line 122 of file qsystemtrayicon.h.

qtsystray_sendActivated

void qtsystray_sendActivated ( QSystemTrayIcon *  , int    )

friend

Definition at line 703 of file qsystemtrayicon.cpp.

{
    emit i->activated((QSystemTrayIcon::ActivationReason)r);
}

Properties

icon

QIcon QSystemTrayIcon::icon

private

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 69 of file qsystemtrayicon.h.

Referenced by QSystemTrayIconSys::createIcon(), and QSystemTrayIconSys::paintEvent().

toolTip

QString QSystemTrayIcon::toolTip

private

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 68 of file qsystemtrayicon.h.

Referenced by QSystemTrayIconSys::setIconContents().

visible

QSystemTrayIcon::visible

private

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 70 of file qsystemtrayicon.h.

Referenced by setVisible().

---

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

• /src/gui/util/qsystemtrayicon.h
• /src/gui/util/qsystemtrayicon.cpp