<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- systray.qdoc -->
<title>System Tray Icon Example | Qt Widgets 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td >Qt 5.9</td><td ><a href="qtwidgets-index.html">Qt Widgets</a></td><td ><a href="examples-widgets.html">Qt Widgets Examples</a></td><td >System Tray Icon Example</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#window-class-definition">Window Class Definition</a></li>
<li class="level1"><a href="#window-class-implementation">Window Class Implementation</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">System Tray Icon Example</h1>
<span class="subtitle"></span>
<!-- $$$desktop/systray-description -->
<div class="descr"> <a name="details"></a>
<div class="border"><p class="centerAlign"><img src="images/systemtray-example.png" alt="" /></p></div><p class="figCaption">Screenshot of the System Tray Icon</p>
<p>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.</p>
<p>This example consists of one single class, <code>Window</code>, providing the main application window (i.e., an editor for the system tray icon) and the associated icon.</p>
<div class="border"><p class="centerAlign"><img src="images/systemtray-editor.png" alt="" /></p></div><p>The editor allows the user to choose the preferred icon as well as set the balloon message's type and duration. The user can also edit the message's title and body. Finally, the editor provides a checkbox controlling whether the icon is actually shown in the system tray, or not.</p>
<a name="window-class-definition"></a>
<h2 id="window-class-definition">Window Class Definition</h2>
<p>The <code>Window</code> class inherits <a href="qwidget.html">QWidget</a>:</p>
<pre class="cpp">
<span class="keyword">class</span> Window : <span class="keyword">public</span> <span class="type"><a href="qdialog.html">QDialog</a></span>
{
Q_OBJECT
<span class="keyword">public</span>:
Window();
<span class="type">void</span> setVisible(bool visible) override;
<span class="keyword">protected</span>:
<span class="type">void</span> closeEvent(<span class="type"><a href="../qtgui/qcloseevent.html">QCloseEvent</a></span> <span class="operator">*</span>event) override;
<span class="keyword">private</span> <span class="keyword">slots</span>:
<span class="type">void</span> setIcon(<span class="type">int</span> index);
<span class="type">void</span> iconActivated(<span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>ActivationReason reason);
<span class="type">void</span> showMessage();
<span class="type">void</span> messageClicked();
<span class="keyword">private</span>:
<span class="type">void</span> createIconGroupBox();
<span class="type">void</span> createMessageGroupBox();
<span class="type">void</span> createActions();
<span class="type">void</span> createTrayIcon();
<span class="type"><a href="qgroupbox.html">QGroupBox</a></span> <span class="operator">*</span>iconGroupBox;
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>iconLabel;
<span class="type"><a href="qcombobox.html">QComboBox</a></span> <span class="operator">*</span>iconComboBox;
<span class="type"><a href="qcheckbox.html">QCheckBox</a></span> <span class="operator">*</span>showIconCheckBox;
<span class="type"><a href="qgroupbox.html">QGroupBox</a></span> <span class="operator">*</span>messageGroupBox;
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>typeLabel;
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>durationLabel;
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>durationWarningLabel;
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>titleLabel;
<span class="type"><a href="qlabel.html">QLabel</a></span> <span class="operator">*</span>bodyLabel;
<span class="type"><a href="qcombobox.html">QComboBox</a></span> <span class="operator">*</span>typeComboBox;
<span class="type"><a href="qspinbox.html">QSpinBox</a></span> <span class="operator">*</span>durationSpinBox;
<span class="type"><a href="qlineedit.html">QLineEdit</a></span> <span class="operator">*</span>titleEdit;
<span class="type"><a href="qtextedit.html">QTextEdit</a></span> <span class="operator">*</span>bodyEdit;
<span class="type"><a href="qpushbutton.html">QPushButton</a></span> <span class="operator">*</span>showMessageButton;
<span class="type"><a href="qaction.html">QAction</a></span> <span class="operator">*</span>minimizeAction;
<span class="type"><a href="qaction.html">QAction</a></span> <span class="operator">*</span>maximizeAction;
<span class="type"><a href="qaction.html">QAction</a></span> <span class="operator">*</span>restoreAction;
<span class="type"><a href="qaction.html">QAction</a></span> <span class="operator">*</span>quitAction;
<span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span> <span class="operator">*</span>trayIcon;
<span class="type"><a href="qmenu.html">QMenu</a></span> <span class="operator">*</span>trayIconMenu;
};
</pre>
<p>We implement several private slots to respond to user interaction. The other private functions are only convenience functions provided to simplify the constructor.</p>
<p>The tray icon is an instance of the <a href="qsystemtrayicon.html">QSystemTrayIcon</a> class. To check whether a system tray is present on the user's desktop, call the static <a href="qsystemtrayicon.html#isSystemTrayAvailable">QSystemTrayIcon::isSystemTrayAvailable</a>() function. Associated with the icon, we provide a menu containing the typical <b>minimize</b>, <b>maximize</b>, <b>restore</b> and <b>quit</b> actions. We reimplement the <a href="qwidget.html#visible-prop">QWidget::setVisible</a>() function to update the tray icon's menu whenever the editor's appearance changes, e.g., when maximizing or minimizing the main application window.</p>
<p>Finally, we reimplement <a href="qwidget.html">QWidget</a>'s <a href="qwidget.html#closeEvent">closeEvent()</a> function to be able to inform the user (when closing the editor window) that the program will keep running in the system tray until the user chooses the <b>Quit</b> entry in the icon's context menu.</p>
<a name="window-class-implementation"></a>
<h2 id="window-class-implementation">Window Class Implementation</h2>
<p>When constructing the editor widget, we first create the various editor elements before we create the actual system tray icon:</p>
<pre class="cpp">
Window<span class="operator">::</span>Window()
{
createIconGroupBox();
createMessageGroupBox();
iconLabel<span class="operator">-</span><span class="operator">></span>setMinimumWidth(durationLabel<span class="operator">-</span><span class="operator">></span>sizeHint()<span class="operator">.</span>width());
createActions();
createTrayIcon();
connect(showMessageButton<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qabstractbutton.html">QAbstractButton</a></span><span class="operator">::</span>clicked<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>Window<span class="operator">::</span>showMessage);
connect(showIconCheckBox<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qabstractbutton.html">QAbstractButton</a></span><span class="operator">::</span>toggled<span class="operator">,</span> trayIcon<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>setVisible);
connect(iconComboBox<span class="operator">,</span> <span class="type">QOverload</span><span class="operator"><</span><span class="type">int</span><span class="operator">></span><span class="operator">::</span>of(<span class="operator">&</span><span class="type"><a href="qcombobox.html">QComboBox</a></span><span class="operator">::</span>currentIndexChanged)<span class="operator">,</span>
<span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>Window<span class="operator">::</span>setIcon);
connect(trayIcon<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>messageClicked<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>Window<span class="operator">::</span>messageClicked);
connect(trayIcon<span class="operator">,</span> <span class="operator">&</span><span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>activated<span class="operator">,</span> <span class="keyword">this</span><span class="operator">,</span> <span class="operator">&</span>Window<span class="operator">::</span>iconActivated);
<span class="type"><a href="qvboxlayout.html">QVBoxLayout</a></span> <span class="operator">*</span>mainLayout <span class="operator">=</span> <span class="keyword">new</span> <span class="type"><a href="qvboxlayout.html">QVBoxLayout</a></span>;
mainLayout<span class="operator">-</span><span class="operator">></span>addWidget(iconGroupBox);
mainLayout<span class="operator">-</span><span class="operator">></span>addWidget(messageGroupBox);
setLayout(mainLayout);
iconComboBox<span class="operator">-</span><span class="operator">></span>setCurrentIndex(<span class="number">1</span>);
trayIcon<span class="operator">-</span><span class="operator">></span>show();
setWindowTitle(tr(<span class="string">"Systray"</span>));
resize(<span class="number">400</span><span class="operator">,</span> <span class="number">300</span>);
}
</pre>
<p>We ensure that the application responds to user input by connecting most of the editor's input widgets (including the system tray icon) to the application's private slots. But note the visibility checkbox; its <a href="qabstractbutton.html#toggled">toggled()</a> signal is connected to the <i>icon</i>'s <a href="qsystemtrayicon.html#visible-prop">setVisible()</a> function instead.</p>
<pre class="cpp">
<span class="type">void</span> Window<span class="operator">::</span>setIcon(<span class="type">int</span> index)
{
<span class="type"><a href="../qtgui/qicon.html">QIcon</a></span> icon <span class="operator">=</span> iconComboBox<span class="operator">-</span><span class="operator">></span>itemIcon(index);
trayIcon<span class="operator">-</span><span class="operator">></span>setIcon(icon);
setWindowIcon(icon);
trayIcon<span class="operator">-</span><span class="operator">></span>setToolTip(iconComboBox<span class="operator">-</span><span class="operator">></span>itemText(index));
}
</pre>
<p>The <code>setIcon()</code> slot is triggered whenever the current index in the icon combobox changes, i.e., whenever the user chooses another icon in the editor. Note that it is also called when the user activates the tray icon with the left mouse button, triggering the icon's <a href="qsystemtrayicon.html#activated">activated()</a> signal. We will come back to this signal shortly.</p>
<p>The <a href="qsystemtrayicon.html#icon-prop">QSystemTrayIcon::setIcon</a>() function sets the <a href="qsystemtrayicon.html#icon-prop">icon</a> property that holds the actual 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.</p>
<p>Note that on X11, due to a limitation in the system tray specification, mouse clicks on transparent areas in the icon are propagated to the system tray. If this behavior is unacceptable, we suggest using an icon with no transparency.</p>
<pre class="cpp">
<span class="type">void</span> Window<span class="operator">::</span>iconActivated(<span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>ActivationReason reason)
{
<span class="keyword">switch</span> (reason) {
<span class="keyword">case</span> <span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>Trigger:
<span class="keyword">case</span> <span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>DoubleClick:
iconComboBox<span class="operator">-</span><span class="operator">></span>setCurrentIndex((iconComboBox<span class="operator">-</span><span class="operator">></span>currentIndex() <span class="operator">+</span> <span class="number">1</span>) <span class="operator">%</span> iconComboBox<span class="operator">-</span><span class="operator">></span>count());
<span class="keyword">break</span>;
<span class="keyword">case</span> <span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>MiddleClick:
showMessage();
<span class="keyword">break</span>;
<span class="keyword">default</span>:
;
}
}
</pre>
<p>Whenever the user activates the system tray icon, it emits its <a href="qsystemtrayicon.html#activated">activated()</a> signal passing the triggering reason as parameter. <a href="qsystemtrayicon.html">QSystemTrayIcon</a> provides the <a href="qsystemtrayicon.html#ActivationReason-enum">ActivationReason</a> enum to describe how the icon was activated.</p>
<p>In the constructor, we connected our icon's <a href="qsystemtrayicon.html#activated">activated()</a> signal to our custom <code>iconActivated()</code> slot: If the user has clicked the icon using the left mouse button, this function changes the icon image by incrementing the icon combobox's current index, triggering the <code>setIcon()</code> slot as mentioned above. If the user activates the icon using the middle mouse button, it calls the custom <code>showMessage()</code> slot:</p>
<pre class="cpp">
<span class="type">void</span> Window<span class="operator">::</span>showMessage()
{
showIconCheckBox<span class="operator">-</span><span class="operator">></span>setChecked(<span class="keyword">true</span>);
<span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>MessageIcon msgIcon <span class="operator">=</span> <span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>MessageIcon(
typeComboBox<span class="operator">-</span><span class="operator">></span>itemData(typeComboBox<span class="operator">-</span><span class="operator">></span>currentIndex())<span class="operator">.</span>toInt());
<span class="keyword">if</span> (msgIcon <span class="operator">=</span><span class="operator">=</span> <span class="type"><a href="qsystemtrayicon.html">QSystemTrayIcon</a></span><span class="operator">::</span>NoIcon) {
<span class="type"><a href="../qtgui/qicon.html">QIcon</a></span> icon(iconComboBox<span class="operator">-</span><span class="operator">></span>itemIcon(iconComboBox<span class="operator">-</span><span class="operator">></span>currentIndex()));
trayIcon<span class="operator">-</span><span class="operator">></span>showMessage(titleEdit<span class="operator">-</span><span class="operator">></span>text()<span class="operator">,</span> bodyEdit<span class="operator">-</span><span class="operator">></span>toPlainText()<span class="operator">,</span> icon<span class="operator">,</span>
durationSpinBox<span class="operator">-</span><span class="operator">></span>value() <span class="operator">*</span> <span class="number">1000</span>);
} <span class="keyword">else</span> {
trayIcon<span class="operator">-</span><span class="operator">></span>showMessage(titleEdit<span class="operator">-</span><span class="operator">></span>text()<span class="operator">,</span> bodyEdit<span class="operator">-</span><span class="operator">></span>toPlainText()<span class="operator">,</span> msgIcon<span class="operator">,</span>
durationSpinBox<span class="operator">-</span><span class="operator">></span>value() <span class="operator">*</span> <span class="number">1000</span>);
}
}
</pre>
<p>When the <i>showMessage()</i> slot is triggered, we first retrieve the message icon depending on the currently chosen message type. The <a href="qsystemtrayicon.html#MessageIcon-enum">QSystemTrayIcon::MessageIcon</a> enum describes the icon that is shown when a balloon message is displayed. Then we call <a href="qsystemtrayicon.html">QSystemTrayIcon</a>'s <a href="qsystemtrayicon.html#showMessage">showMessage()</a> function to show the message with the title, body, and icon for the time specified in milliseconds.</p>
<p>macOS users note: The Growl notification system must be installed for <a href="qsystemtrayicon.html#showMessage">QSystemTrayIcon::showMessage</a>() to display messages.</p>
<p><a href="qsystemtrayicon.html">QSystemTrayIcon</a> also has the corresponding, <a href="qsystemtrayicon.html#messageClicked">messageClicked()</a> signal, which is emitted when the user clicks a message displayed by <a href="qsystemtrayicon.html#showMessage">showMessage()</a>.</p>
<pre class="cpp">
<span class="type">void</span> Window<span class="operator">::</span>messageClicked()
{
<span class="type"><a href="qmessagebox.html">QMessageBox</a></span><span class="operator">::</span>information(<span class="number">0</span><span class="operator">,</span> tr(<span class="string">"Systray"</span>)<span class="operator">,</span>
tr(<span class="string">"Sorry, I already gave what help I could.\n"</span>
<span class="string">"Maybe you should try asking a human?"</span>));
}
</pre>
<p>In the constructor, we connected the <a href="qsystemtrayicon.html#messageClicked">messageClicked()</a> signal to our custom <code>messageClicked()</code> slot that simply displays a message using the <a href="qmessagebox.html">QMessageBox</a> class.</p>
<p><a href="qmessagebox.html">QMessageBox</a> provides a modal dialog with a short message, an icon, and buttons laid out depending on the current style. It supports four severity levels: "Question", "Information", "Warning" and "Critical". The easiest way to pop up a message box in Qt is to call one of the associated static functions, e.g., <a href="qmessagebox.html#information">QMessageBox::information</a>().</p>
<p>As we mentioned earlier, we reimplement a couple of <a href="qwidget.html">QWidget</a>'s virtual functions:</p>
<pre class="cpp">
<span class="type">void</span> Window<span class="operator">::</span>setVisible(bool visible)
{
minimizeAction<span class="operator">-</span><span class="operator">></span>setEnabled(visible);
maximizeAction<span class="operator">-</span><span class="operator">></span>setEnabled(<span class="operator">!</span>isMaximized());
restoreAction<span class="operator">-</span><span class="operator">></span>setEnabled(isMaximized() <span class="operator">|</span><span class="operator">|</span> <span class="operator">!</span>visible);
<span class="type"><a href="qdialog.html">QDialog</a></span><span class="operator">::</span>setVisible(visible);
}
</pre>
<p>Our reimplementation of the <a href="qwidget.html#visible-prop">QWidget::setVisible</a>() function updates the tray icon's menu whenever the editor's appearance changes, e.g., when maximizing or minimizing the main application window, before calling the base class implementation.</p>
<pre class="cpp">
<span class="type">void</span> Window<span class="operator">::</span>closeEvent(<span class="type"><a href="../qtgui/qcloseevent.html">QCloseEvent</a></span> <span class="operator">*</span>event)
{
<span class="preprocessor">#ifdef Q_OS_OSX</span>
<span class="keyword">if</span> (<span class="operator">!</span>event<span class="operator">-</span><span class="operator">></span>spontaneous() <span class="operator">|</span><span class="operator">|</span> <span class="operator">!</span>isVisible()) {
<span class="keyword">return</span>;
}
<span class="preprocessor">#endif</span>
<span class="keyword">if</span> (trayIcon<span class="operator">-</span><span class="operator">></span>isVisible()) {
<span class="type"><a href="qmessagebox.html">QMessageBox</a></span><span class="operator">::</span>information(<span class="keyword">this</span><span class="operator">,</span> tr(<span class="string">"Systray"</span>)<span class="operator">,</span>
tr(<span class="string">"The program will keep running in the "</span>
<span class="string">"system tray. To terminate the program, "</span>
<span class="string">"choose <b>Quit</b> in the context menu "</span>
<span class="string">"of the system tray entry."</span>));
hide();
event<span class="operator">-</span><span class="operator">></span>ignore();
}
}
</pre>
<p>We have reimplemented the <a href="qwidget.html#closeEvent">QWidget::closeEvent</a>() event handler to receive widget close events, showing the above message to the users when they are closing the editor window. On macOS we need to avoid showing the message and accepting the close event when the user really intends to quit the application, that is, when the user has triggered "Quit" in the menu bar or pressed the Command+Q shortcut.</p>
<p>In addition to the functions and slots discussed above, we have also implemented several convenience functions to simplify the constructor: <code>createIconGroupBox()</code>, <code>createMessageGroupBox()</code>, <code>createActions()</code> and <code>createTrayIcon()</code>. See the <a href="qtwidgets-desktop-systray-window-cpp.html">window.cpp</a> file for details.</p>
<p>Files:</p>
<ul>
<li><a href="qtwidgets-desktop-systray-window-cpp.html">desktop/systray/window.cpp</a></li>
<li><a href="qtwidgets-desktop-systray-window-h.html">desktop/systray/window.h</a></li>
<li><a href="qtwidgets-desktop-systray-main-cpp.html">desktop/systray/main.cpp</a></li>
<li><a href="qtwidgets-desktop-systray-systray-pro.html">desktop/systray/systray.pro</a></li>
<li><a href="qtwidgets-desktop-systray-systray-qrc.html">desktop/systray/systray.qrc</a></li>
</ul>
<p>Images:</p>
<ul>
<li><a href="images/used-in-examples/desktop/systray/images/bad.png">desktop/systray/images/bad.png</a></li>
<li><a href="images/used-in-examples/desktop/systray/images/heart.png">desktop/systray/images/heart.png</a></li>
<li><a href="images/used-in-examples/desktop/systray/images/trash.png">desktop/systray/images/trash.png</a></li>
</ul>
</div>
<!-- @@@desktop/systray -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
armv5tl
>
media
>
core-updates
>
by-pkgid
>
768f7d9f703884aa2562bf0a651086df
>
files
>
3718
