1 | // -*- c++ -*- |
2 | |
3 | /* |
4 | * Copyright (C) 2001-2006 by Richard Moore <rich@kde.org> |
5 | * Copyright (C) 2004-2005 by Sascha Cunz <sascha.cunz@tiscali.de> |
6 | * |
7 | * This library is free software; you can redistribute it and/or |
8 | * modify it under the terms of the GNU Lesser General Public |
9 | * License as published by the Free Software Foundation; either |
10 | * version 2 of the License, or (at your option) any later version. |
11 | * |
12 | * This library is distributed in the hope that it will be useful, |
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
15 | * Lesser General Public License for more details. |
16 | * |
17 | * You should have received a copy of the GNU Lesser General Public |
18 | * License along with this library; if not, write to the Free Software |
19 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
20 | */ |
21 | |
22 | #ifndef KPASSIVEPOPUP_H |
23 | #define KPASSIVEPOPUP_H |
24 | |
25 | #include <kdeui_export.h> |
26 | |
27 | #include <QtGui/QFrame> |
28 | |
29 | class KVBox; |
30 | class QSystemTrayIcon; |
31 | |
32 | /** |
33 | * @short A dialog-like popup that displays messages without interrupting the user. |
34 | * |
35 | * The simplest uses of KPassivePopup are by using the various message() static |
36 | * methods. The position the popup appears at depends on the type of the parent window: |
37 | * |
38 | * @li Normal Windows: The popup is placed adjacent to the icon of the window. |
39 | * @li System Tray Windows: The popup is placed adjact to the system tray window itself. |
40 | * @li Skip Taskbar Windows: The popup is placed adjact to the window |
41 | * itself if it is visible, and at the edge of the desktop otherwise. |
42 | * |
43 | * You also have the option of calling show with a QPoint as a parameter that |
44 | * removes the automatic placing of KPassivePopup and shows it in the point you want. |
45 | * |
46 | * The most basic use of KPassivePopup displays a popup containing a piece of text: |
47 | * \code |
48 | * KPassivePopup::message( "This is the message", this ); |
49 | * \endcode |
50 | * We can create popups with titles and icons too, as this example shows: |
51 | * \code |
52 | * QPixmap px; |
53 | * px.load( "hi32-app-logtracker.png" ); |
54 | * KPassivePopup::message( "Some title", "This is the main text", px, this ); |
55 | * \endcode |
56 | * This screenshot shows a popup with both a caption and a main text which is |
57 | * being displayed next to the toolbar icon of the window that triggered it: |
58 | * \image html kpassivepopup.png "A passive popup" |
59 | * |
60 | * For more control over the popup, you can use the setView(QWidget *) method |
61 | * to create a custom popup. |
62 | * \code |
63 | * KPassivePopup *pop = new KPassivePopup( parent ); |
64 | * |
65 | * KVBox *vb = new KVBox( pop ); |
66 | * (void) new QLabel( "<b>Isn't this great?</b>", vb); |
67 | * |
68 | * KHBox *box = new KHBox( vb ); |
69 | * (void) new QPushButton( "Yes", box ); |
70 | * (void) new QPushButton( "No", box ); |
71 | * |
72 | * pop->setView( vb ); |
73 | * pop->show(); |
74 | * \endcode |
75 | * |
76 | * @author Richard Moore, rich@kde.org |
77 | * @author Sascha Cunz, sascha.cunz@tiscali.de |
78 | */ |
79 | class KDEUI_EXPORT : public QFrame |
80 | { |
81 | Q_OBJECT |
82 | Q_PROPERTY (bool autoDelete READ autoDelete WRITE setAutoDelete ) |
83 | Q_PROPERTY (int timeout READ timeout WRITE setTimeout ) |
84 | Q_PROPERTY (QRect defaultArea READ defaultArea ) |
85 | |
86 | public: |
87 | /** |
88 | * Styles that a KPassivePopup can have. |
89 | */ |
90 | enum |
91 | { |
92 | , ///< Information will appear in a framed box (default) |
93 | , ///< Information will appear in a comic-alike balloon |
94 | =128 ///< Ids greater than this are reserved for use by subclasses |
95 | }; |
96 | |
97 | /** |
98 | * Creates a popup for the specified widget. |
99 | */ |
100 | explicit ( QWidget *parent=0, Qt::WindowFlags f = 0 ); |
101 | |
102 | /** |
103 | * Creates a popup for the specified window. |
104 | */ |
105 | explicit ( WId parent ); |
106 | |
107 | #if 0 // These break macos and win32 where the definition of WId makes them ambiguous |
108 | /** |
109 | * Creates a popup for the specified widget. |
110 | * THIS WILL BE REMOVED, USE setPopupStyle(). |
111 | */ |
112 | explicit KPassivePopup( int popupStyle, QWidget *parent=0, Qt::WindowFlags f=0 ) KDE_DEPRECATED; |
113 | |
114 | /** |
115 | * Creates a popup for the specified window. |
116 | * THIS WILL BE REMOVED, USE setPopupStyle(). |
117 | */ |
118 | KPassivePopup( int popupStyle, WId parent, Qt::WindowFlags f=0 ) KDE_DEPRECATED; |
119 | #endif |
120 | |
121 | /** |
122 | * Cleans up. |
123 | */ |
124 | virtual (); |
125 | |
126 | /** |
127 | * Sets the main view to be the specified widget (which must be a child of the popup). |
128 | */ |
129 | void ( QWidget *child ); |
130 | |
131 | /** |
132 | * Creates a standard view then calls setView(QWidget*) . |
133 | */ |
134 | void ( const QString &caption, const QString &text = QString() ); |
135 | |
136 | /** |
137 | * Creates a standard view then calls setView(QWidget*) . |
138 | */ |
139 | virtual void ( const QString &caption, const QString &text, const QPixmap &icon ); |
140 | |
141 | /** |
142 | * Returns a widget that is used as standard view if one of the |
143 | * setView() methods taking the QString arguments is used. |
144 | * You can use the returned widget to customize the passivepopup while |
145 | * keeping the look similar to the "standard" passivepopups. |
146 | * |
147 | * After customizing the widget, pass it to setView( QWidget* ) |
148 | * |
149 | * @param caption The window caption (title) on the popup |
150 | * @param text The text for the popup |
151 | * @param icon The icon to use for the popup |
152 | * @param parent The parent widget used for the returned KVBox. If left 0L, |
153 | * then "this", i.e. the passive popup object will be used. |
154 | * |
155 | * @return a KVBox containing the given arguments, looking like the |
156 | * standard passivepopups. |
157 | * @see setView( QWidget * ) |
158 | * @see setView( const QString&, const QString& ) |
159 | * @see setView( const QString&, const QString&, const QPixmap& ) |
160 | */ |
161 | KVBox * standardView( const QString& caption, const QString& text, |
162 | const QPixmap& icon, QWidget *parent = 0L ); |
163 | |
164 | /** |
165 | * Returns the main view. |
166 | */ |
167 | QWidget *() const; |
168 | |
169 | /** |
170 | * Returns the delay before the popup is removed automatically. |
171 | */ |
172 | int () const; |
173 | |
174 | /** |
175 | * Enables / disables auto-deletion of this widget when the timeout |
176 | * occurs. |
177 | * The default is false. If you use the class-methods message(), |
178 | * auto-deletion is turned on by default. |
179 | */ |
180 | virtual void ( bool autoDelete ); |
181 | |
182 | /** |
183 | * @returns true if the widget auto-deletes itself when the timeout occurs. |
184 | * @see setAutoDelete |
185 | */ |
186 | bool () const; |
187 | |
188 | /** |
189 | * If no relative window (eg taskbar button, system tray window) is |
190 | * available, use this rectangle (pass it to moveNear()). |
191 | * Basically KWindowSystem::workArea() with width and height set to 0 |
192 | * so that moveNear uses the upper-left position. |
193 | * @return The QRect to be passed to moveNear() if no other is |
194 | * available. |
195 | */ |
196 | QRect () const; |
197 | |
198 | /** |
199 | * Returns the position to which this popup is anchored. |
200 | */ |
201 | QPoint () const; |
202 | |
203 | /** |
204 | * Sets the anchor of this popup. The popup tries automatically to adjust |
205 | * itself somehow around the point. |
206 | */ |
207 | void ( const QPoint& anchor ); |
208 | |
209 | // TODO KDE4: give all the static methods a const QPoint p = QPoint() that in |
210 | // case the point is not null calls the show(const QPoint &p) method instead |
211 | // of the show() one. |
212 | /** |
213 | * Convenience method that displays popup with the specified message beside the |
214 | * icon of the specified widget. |
215 | * Note that the returned object is destroyed when it is hidden. |
216 | * @see setAutoDelete |
217 | */ |
218 | static KPassivePopup *( const QString &text, QWidget *parent ); |
219 | |
220 | /** |
221 | * Convenience method that displays popup with the specified message beside the |
222 | * icon of the specified QSystemTrayIcon. |
223 | * Note that the returned object is destroyed when it is hidden. |
224 | * @see setAutoDelete |
225 | */ |
226 | static KPassivePopup *( const QString &text, QSystemTrayIcon *parent ); |
227 | |
228 | /** |
229 | * Convenience method that displays popup with the specified caption and message |
230 | * beside the icon of the specified widget. |
231 | * Note that the returned object is destroyed when it is hidden. |
232 | * @see setAutoDelete |
233 | */ |
234 | static KPassivePopup *( const QString &caption, const QString &text, |
235 | QWidget *parent ); |
236 | |
237 | /** |
238 | * Convenience method that displays popup with the specified caption and message |
239 | * beside the icon of the specified QSystemTrayIcon. |
240 | * Note that the returned object is destroyed when it is hidden. |
241 | * @see setAutoDelete |
242 | */ |
243 | static KPassivePopup *( const QString &caption, const QString &text, |
244 | QSystemTrayIcon *parent ); |
245 | |
246 | /** |
247 | * Convenience method that displays popup with the specified icon, caption and |
248 | * message beside the icon of the specified widget. |
249 | * Note that the returned object is destroyed when it is hidden. |
250 | * @see setAutoDelete |
251 | */ |
252 | static KPassivePopup *( const QString &caption, const QString &text, |
253 | const QPixmap &icon, |
254 | QWidget *parent, int timeout = -1 ); |
255 | |
256 | /** |
257 | * Convenience method that displays popup with the specified icon, caption and |
258 | * message beside the icon of the specified QSystemTrayIcon. |
259 | * Note that the returned object is destroyed when it is hidden. |
260 | * @see setAutoDelete |
261 | */ |
262 | static KPassivePopup *( const QString &caption, const QString &text, |
263 | const QPixmap &icon, |
264 | QSystemTrayIcon *parent, int timeout = -1 ); |
265 | |
266 | /** |
267 | * Convenience method that displays popup with the specified icon, caption and |
268 | * message beside the icon of the specified window. |
269 | * Note that the returned object is destroyed when it is hidden. |
270 | * @see setAutoDelete |
271 | */ |
272 | static KPassivePopup *( const QString &caption, const QString &text, |
273 | const QPixmap &icon, |
274 | WId parent, int timeout = -1 ); |
275 | |
276 | /** |
277 | * Convenience method that displays popup with the specified popup-style and message beside the |
278 | * icon of the specified widget. |
279 | * Note that the returned object is destroyed when it is hidden. |
280 | * @see setAutoDelete |
281 | */ |
282 | static KPassivePopup *( int , const QString &text, QWidget *parent ); |
283 | |
284 | /** |
285 | * Convenience method that displays popup with the specified popup-style and message beside the |
286 | * icon of the specified QSystemTrayIcon. |
287 | * Note that the returned object is destroyed when it is hidden. |
288 | * @see setAutoDelete |
289 | */ |
290 | static KPassivePopup *( int , const QString &text, QSystemTrayIcon *parent ); |
291 | |
292 | /** |
293 | * Convenience method that displays popup with the specified popup-style, caption and message |
294 | * beside the icon of the specified QSystemTrayIcon. |
295 | * Note that the returned object is destroyed when it is hidden. |
296 | * @see setAutoDelete |
297 | */ |
298 | static KPassivePopup *( int , const QString &caption, const QString &text, |
299 | QSystemTrayIcon *parent ); |
300 | |
301 | /** |
302 | * Convenience method that displays popup with the specified popup-style, caption and message |
303 | * beside the icon of the specified widget. |
304 | * Note that the returned object is destroyed when it is hidden. |
305 | * @see setAutoDelete |
306 | */ |
307 | static KPassivePopup *( int , const QString &caption, const QString &text, |
308 | QWidget *parent ); |
309 | |
310 | /** |
311 | * Convenience method that displays popup with the specified popup-style, icon, caption and |
312 | * message beside the icon of the specified widget. |
313 | * Note that the returned object is destroyed when it is hidden. |
314 | * @see setAutoDelete |
315 | */ |
316 | static KPassivePopup *( int , const QString &caption, const QString &text, |
317 | const QPixmap &icon, |
318 | QWidget *parent, int timeout = -1 ); |
319 | |
320 | /** |
321 | * Convenience method that displays popup with the specified popup-style, icon, caption and |
322 | * message beside the icon of the specified QSystemTrayIcon. |
323 | * Note that the returned object is destroyed when it is hidden. |
324 | * @see setAutoDelete |
325 | */ |
326 | static KPassivePopup *( int , const QString &caption, const QString &text, |
327 | const QPixmap &icon, |
328 | QSystemTrayIcon *parent, int timeout = -1 ); |
329 | |
330 | /** |
331 | * Convenience method that displays popup with the specified popup-style, icon, caption and |
332 | * message beside the icon of the specified window. |
333 | * Note that the returned object is destroyed when it is hidden. |
334 | * @see setAutoDelete |
335 | */ |
336 | static KPassivePopup *( int , const QString &caption, const QString &text, |
337 | const QPixmap &icon, |
338 | WId parent, int timeout = -1 ); |
339 | |
340 | |
341 | public Q_SLOTS: |
342 | /** |
343 | * Sets the delay for the popup is removed automatically. Setting the delay to 0 |
344 | * disables the timeout, if you're doing this, you may want to connect the |
345 | * clicked() signal to the hide() slot. |
346 | * Setting the delay to -1 makes it use the default value. |
347 | * |
348 | * @see timeout |
349 | */ |
350 | void ( int delay ); |
351 | |
352 | /** |
353 | * Sets the visual appearance of the popup. |
354 | * @see PopupStyle |
355 | */ |
356 | void ( int ); |
357 | |
358 | /** |
359 | * Reimplemented to reposition the popup. |
360 | */ |
361 | void (); |
362 | |
363 | /** |
364 | * Shows the popup in the given point |
365 | */ |
366 | void (const QPoint &p); |
367 | |
368 | virtual void (bool visible); |
369 | |
370 | Q_SIGNALS: |
371 | /** |
372 | * Emitted when the popup is clicked. |
373 | */ |
374 | void (); |
375 | |
376 | /** |
377 | * Emitted when the popup is clicked. |
378 | */ |
379 | void ( const QPoint &pos ); |
380 | |
381 | protected: |
382 | /** |
383 | * This method positions the popup. |
384 | */ |
385 | virtual void (); |
386 | |
387 | /** |
388 | * Reimplemented to destroy the object when autoDelete() is |
389 | * enabled. |
390 | */ |
391 | virtual void ( QHideEvent * ); |
392 | |
393 | /** |
394 | * Moves the popup to be adjacent to the icon of the specified rectangle. |
395 | */ |
396 | void ( const QRect &target ); |
397 | |
398 | /** |
399 | * Calculates the position to place the popup near the specified rectangle. |
400 | */ |
401 | QPoint ( const QRect &target); |
402 | |
403 | /** |
404 | * Reimplemented to detect mouse clicks. |
405 | */ |
406 | virtual void ( QMouseEvent *e ); |
407 | |
408 | /** |
409 | * Updates the transparency mask. Unused if PopupStyle == Boxed |
410 | */ |
411 | void (); |
412 | |
413 | /** |
414 | * Overwrite to paint the border when PopupStyle == Balloon. |
415 | * Unused if PopupStyle == Boxed |
416 | */ |
417 | virtual void ( QPaintEvent* pe ); |
418 | |
419 | private: |
420 | void ( WId window ); |
421 | |
422 | /* @internal */ |
423 | class ; |
424 | Private *const ; |
425 | }; |
426 | |
427 | #endif // KPASSIVEPOPUP_H |
428 | |
429 | // Local Variables: |
430 | // c-basic-offset: 4 |
431 | // End: |
432 | |
433 | |