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
29class KVBox;
30class 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 */
79class KDEUI_EXPORT KPassivePopup : 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
86public:
87 /**
88 * Styles that a KPassivePopup can have.
89 */
90 enum PopupStyle
91 {
92 Boxed, ///< Information will appear in a framed box (default)
93 Balloon, ///< Information will appear in a comic-alike balloon
94 CustomStyle=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 KPassivePopup( QWidget *parent=0, Qt::WindowFlags f = 0 );
101
102 /**
103 * Creates a popup for the specified window.
104 */
105 explicit KPassivePopup( 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 ~KPassivePopup();
125
126 /**
127 * Sets the main view to be the specified widget (which must be a child of the popup).
128 */
129 void setView( QWidget *child );
130
131 /**
132 * Creates a standard view then calls setView(QWidget*) .
133 */
134 void setView( const QString &caption, const QString &text = QString() );
135
136 /**
137 * Creates a standard view then calls setView(QWidget*) .
138 */
139 virtual void setView( 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 *view() const;
168
169 /**
170 * Returns the delay before the popup is removed automatically.
171 */
172 int timeout() 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 setAutoDelete( bool autoDelete );
181
182 /**
183 * @returns true if the widget auto-deletes itself when the timeout occurs.
184 * @see setAutoDelete
185 */
186 bool autoDelete() 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 defaultArea() const;
197
198 /**
199 * Returns the position to which this popup is anchored.
200 */
201 QPoint anchor() 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 setAnchor( 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 *message( 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 *message( 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 *message( 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 *message( 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 *message( 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 *message( 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 *message( 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 *message( int popupStyle, 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 *message( int popupStyle, 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 *message( int popupStyle, 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 *message( int popupStyle, 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 *message( int popupStyle, 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 *message( int popupStyle, 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 *message( int popupStyle, const QString &caption, const QString &text,
337 const QPixmap &icon,
338 WId parent, int timeout = -1 );
339
340
341public 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 setTimeout( int delay );
351
352 /**
353 * Sets the visual appearance of the popup.
354 * @see PopupStyle
355 */
356 void setPopupStyle( int popupstyle );
357
358 /**
359 * Reimplemented to reposition the popup.
360 */
361 void show();
362
363 /**
364 * Shows the popup in the given point
365 */
366 void show(const QPoint &p);
367
368 virtual void setVisible(bool visible);
369
370Q_SIGNALS:
371 /**
372 * Emitted when the popup is clicked.
373 */
374 void clicked();
375
376 /**
377 * Emitted when the popup is clicked.
378 */
379 void clicked( const QPoint &pos );
380
381protected:
382 /**
383 * This method positions the popup.
384 */
385 virtual void positionSelf();
386
387 /**
388 * Reimplemented to destroy the object when autoDelete() is
389 * enabled.
390 */
391 virtual void hideEvent( QHideEvent * );
392
393 /**
394 * Moves the popup to be adjacent to the icon of the specified rectangle.
395 */
396 void moveNear( const QRect &target );
397
398 /**
399 * Calculates the position to place the popup near the specified rectangle.
400 */
401 QPoint calculateNearbyPoint( const QRect &target);
402
403 /**
404 * Reimplemented to detect mouse clicks.
405 */
406 virtual void mouseReleaseEvent( QMouseEvent *e );
407
408 /**
409 * Updates the transparency mask. Unused if PopupStyle == Boxed
410 */
411 void updateMask();
412
413 /**
414 * Overwrite to paint the border when PopupStyle == Balloon.
415 * Unused if PopupStyle == Boxed
416 */
417 virtual void paintEvent( QPaintEvent* pe );
418
419private:
420 void init( WId window );
421
422 /* @internal */
423 class Private;
424 Private *const d;
425};
426
427#endif // KPASSIVEPOPUP_H
428
429// Local Variables:
430// c-basic-offset: 4
431// End:
432
433