1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Matthias Ettrich <ettrich@kde.org>
3 Copyright (C) 2007 by Charles Connell <charles@connells.org>
4 Copyright (C) 2008 Lukas Appelhans <l.appelhans@gmx.de>
5
6 This library is free software; you can redistribute it and/or
7 modify it under the terms of the GNU Library General Public
8 License version 2 as published by the Free Software Foundation.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20#ifndef KSYSTEMTRAY_H
21#define KSYSTEMTRAY_H
22
23#include <kdeui_export.h>
24#include <kglobal.h>
25
26#include <QtGui/QSystemTrayIcon>
27
28class KActionCollection;
29class KSystemTrayIconPrivate;
30class QAction;
31class QMovie;
32
33/**
34 * \brief %KDE System Tray Window class
35 *
36 * This class implements system tray windows.
37 *
38 * A tray window is a small window (typically 22x22 pixel) that docks
39 * into the system tray in the desktop panel. It usually displays an
40 * icon or an animated icon there. The icon represents
41 * the application, similar to a taskbar button, but consumes less
42 * screen space.
43 *
44 * When the user clicks with the left mouse button on the icon, the
45 * main application window is shown/raised and activated. With the
46 * right mouse button, she gets a popupmenu with application specific
47 * commands, including "Minimize/Restore" and "Quit".
48 *
49 * Please note that this class is being phased out in favor of the KStatusNotifierItem
50 * class, you should consider to use it instead if you are writing a new application
51 * or consider porting the code that uses this class to the KStatusNotifierItem API.
52 *
53 * Also, QSystemTrayIcon::showMessage(..) should not be
54 * used for KDE application because the popup message has no KDE standard
55 * look & feel and cannot be controlled by KDE configurations.
56 * Use KNotification or KPassivePopup instead.
57 *
58 * @author Matthias Ettrich <ettrich@kde.org>
59 **/
60class KDEUI_EXPORT KSystemTrayIcon : public QSystemTrayIcon //krazy:exclude=qclasses
61{
62 Q_OBJECT
63public:
64 /**
65 * Construct a system tray icon.
66 *
67 * The parent widget @p parent has a special meaning:
68 * Besides owning the tray window, the parent widget will
69 * disappear from taskbars when it is iconified while the tray
70 * window is visible. This is the desired behavior. After all,
71 * the tray window @p is the parent's taskbar icon.
72 *
73 * Furthermore, the parent widget is shown or raised respectively
74 * when the user clicks on the tray window with the left mouse
75 * button.
76 **/
77 explicit KSystemTrayIcon( QWidget* parent = 0 );
78
79 /**
80 * Same as above but allows one to define the icon by name that should
81 * be used for the system tray icon.
82 */
83 explicit KSystemTrayIcon( const QString& icon, QWidget* parent = 0 );
84
85 /**
86 * Same as above but allows one to define the icon by name that should
87 * be used for the system tray icon.
88 */
89 explicit KSystemTrayIcon( const QIcon& icon, QWidget* parent = 0 );
90
91 /**
92 * Same as above but allows one to define the movie by QMovie that should
93 * be used for the system tray icon. Memory management for the movie will
94 * be handled by KSystemTrayIcon.
95 */
96 explicit KSystemTrayIcon(QMovie* movie, QWidget* parent);
97
98 /**
99 * Destructor
100 */
101 ~KSystemTrayIcon();
102
103 /**
104 * Set the movie to use. To manipulate the movie (start, stop, pause), call
105 * @see movie() and make calls on the QMovie* that it returns.
106 * Memory management for the movie will be handled by KSystemTrayIcon.
107 * @since 4.2
108 */
109 void setMovie(QMovie* movie);
110
111 /**
112 * Get a pointer to the movie. Use this pointer to manipulate the movie
113 * (start, stop, pause).
114 * Will return null if no movie has been set
115 * @since 4.2
116 */
117 const QMovie* movie() const;
118
119 /**
120 Easy access to the actions in the context menu
121 Currently includes KStandardAction::Quit and minimizeRestore
122 */
123 KActionCollection* actionCollection();
124
125 /**
126 Returns the QWidget set by the constructor
127 */
128 QWidget *parentWidget() const;
129
130 /**
131 Function to be used from function handling closing of the window associated
132 with the tray icon (i.e. QWidget::closeEvent(), KMainWindow::queryClose() or
133 similar). When false is returned, the window closing should proceed normally,
134 when true is returned, special systray-related handling should take place.
135 */
136 bool parentWidgetTrayClose() const;
137
138 /**
139 * Loads an icon @p icon using the icon loader class of the given componentData @p componentData.
140 * The icon is applied the panel effect as it should only be used to be shown in the
141 * system tray.
142 * It's commonly used in the form : systray->setPixmap( systray->loadIcon( "mysystray" ) );
143 */
144 static QIcon loadIcon(const QString &icon, const KComponentData &componentData = KGlobal::mainComponent());
145
146 /**
147 * Sets the context menu title action to @p action.
148 * The following code shows how to change the current title.
149 * <code>
150 * QAction *titleAction = contextMenuTitle();
151 * titleAction->setText("New Title");
152 * setContextMenuTitle(titleAction);
153 * </code>
154 * @since 4.1
155 */
156 void setContextMenuTitle(QAction *action);
157
158 /**
159 * Returns the context menu title action.
160 * @since 4.1
161 */
162 QAction *contextMenuTitle() const;
163
164Q_SIGNALS:
165 /**
166 * Emitted when quit is selected in the menu. If you want to perform any other
167 * action than to close the main application window please connect to this signal.
168 */
169 void quitSelected();
170
171public Q_SLOTS:
172 void toggleActive();
173
174private Q_SLOTS:
175 void contextMenuAboutToShow();
176 void minimizeRestoreAction();
177 void maybeQuit();
178 void activateOrHide( QSystemTrayIcon::ActivationReason reasonCalled );
179
180private:
181 void init( QWidget* );
182 void minimizeRestore( bool restore );
183
184 KSystemTrayIconPrivate* const d;
185
186Q_PRIVATE_SLOT(d, void _k_slotNewFrame())
187};
188
189#endif
190
191