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 | |
28 | class KActionCollection; |
29 | class KSystemTrayIconPrivate; |
30 | class QAction; |
31 | class 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 | **/ |
60 | class KDEUI_EXPORT KSystemTrayIcon : public QSystemTrayIcon //krazy:exclude=qclasses |
61 | { |
62 | Q_OBJECT |
63 | public: |
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 (QAction *action); |
157 | |
158 | /** |
159 | * Returns the context menu title action. |
160 | * @since 4.1 |
161 | */ |
162 | QAction *() const; |
163 | |
164 | Q_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 | |
171 | public Q_SLOTS: |
172 | void toggleActive(); |
173 | |
174 | private Q_SLOTS: |
175 | void (); |
176 | void minimizeRestoreAction(); |
177 | void maybeQuit(); |
178 | void activateOrHide( QSystemTrayIcon::ActivationReason reasonCalled ); |
179 | |
180 | private: |
181 | void init( QWidget* ); |
182 | void minimizeRestore( bool restore ); |
183 | |
184 | KSystemTrayIconPrivate* const d; |
185 | |
186 | Q_PRIVATE_SLOT(d, void _k_slotNewFrame()) |
187 | }; |
188 | |
189 | #endif |
190 | |
191 | |