kdeui/util/kpassivepopup.h

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