diff options
Diffstat (limited to 'kdeui/kpassivepopup.h')
| -rw-r--r-- | kdeui/kpassivepopup.h | 363 |
1 files changed, 363 insertions, 0 deletions
diff --git a/kdeui/kpassivepopup.h b/kdeui/kpassivepopup.h new file mode 100644 index 000000000..40c1e789b --- /dev/null +++ b/kdeui/kpassivepopup.h @@ -0,0 +1,363 @@ +// -*- c++ -*- + +/* + * Copyright : (C) 2001-2002 by Richard Moore + * Copyright : (C) 2004-2005 by Sascha Cunz + * License : This file is released under the terms of the LGPL, version 2. + * Email : rich@kde.org + * Email : sascha.cunz@tiscali.de + */ + +#ifndef KPASSIVEPOPUP_H +#define KPASSIVEPOPUP_H + +#include <qframe.h> + +#include <kdelibs_export.h> + +class QBoxLayout; +class QTimer; +class QLabel; +class QVBox; + +/** + * @short A dialog-like popup that displays messages without interupting the user. + * + * The simplest uses of KPassivePopup are by using the various message() static + * methods. The position the popup appears at depends on the type of the parent window: + * + * @li Normal Windows: The popup is placed adjacent to the icon of the window. + * @li System Tray Windows: The popup is placed adjact to the system tray window itself. + * @li Skip Taskbar Windows: The popup is placed adjact to the window + * itself if it is visible, and at the edge of the desktop otherwise. + * + * You also have the option of calling show with a QPoint as a parameter that + * removes the automatic placing of KPassivePopup and shows it in the point you want. + * + * The most basic use of KPassivePopup displays a popup containing a piece of text: + * \code + * KPassivePopup::message( "This is the message", this ); + * \endcode + * We can create popups with titles and icons too, as this example shows: + * \code + * QPixmap px; + * px.load( "hi32-app-logtracker.png" ); + * KPassivePopup::message( "Some title", "This is the main text", px, this ); + * \endcode + * For more control over the popup, you can use the setView(QWidget *) method + * to create a custom popup. + * \code + * KPassivePopup *pop = new KPassivePopup( parent ); + * + * QVBox *vb = new QVBox( pop ); + * (void) new QLabel( vb, "<b>Isn't this great?</b>" ); + * + * QHBox *box = new QHBox( vb ); + * (void) new QPushButton( box, "Yes" ); + * (void) new QPushButton( box, "No" ); + * + * pop->setView( vb ); + * pop->show(); + * \endcode + * + * @version $Id$ + * @since 3.1 + * @author Richard Moore, rich@kde.org + * @author Sascha Cunz, sascha.cunz@tiscali.de + */ +class KDEUI_EXPORT KPassivePopup : public QFrame +{ + Q_OBJECT + Q_PROPERTY (bool autoDelete READ autoDelete WRITE setAutoDelete ) + Q_PROPERTY (int timeout READ timeout WRITE setTimeout ) + +public: + /** + * Styles that a KPassivePopup can have. + * @since 3.5 + */ + enum PopupStyle + { + Boxed, ///< Information will appear in a framed box (default) + Balloon, ///< Information will appear in a comic-alike balloon + CustomStyle=128 ///< Ids greater than this are reserved for use by subclasses + }; + + /** + * Creates a popup for the specified widget. + */ + KPassivePopup( QWidget *parent=0, const char *name=0, WFlags f=0 ); + + /** + * Creates a popup for the specified window. + */ + KPassivePopup( WId parent, const char *name=0, WFlags f=0 ); + + /** + * Creates a popup for the specified widget. + * @since 3.5 + */ + KPassivePopup( int popupStyle, QWidget *parent=0, const char *name=0, WFlags f=0 ); + + /** + * Creates a popup for the specified window. + * @since 3.5 + */ + KPassivePopup( int popupStyle, WId parent, const char *name=0, WFlags f=0 ); + + /** + * Cleans up. + */ + virtual ~KPassivePopup(); + + /** + * Sets the main view to be the specified widget (which must be a child of the popup). + */ + void setView( QWidget *child ); + + /** + * Creates a standard view then calls setView(QWidget*) . + */ + void setView( const QString &caption, const QString &text = QString::null ); + + /** + * Creates a standard view then calls setView(QWidget*) . + */ + virtual void setView( const QString &caption, const QString &text, const QPixmap &icon ); + + /** + * Returns a widget that is used as standard view if one of the + * setView() methods taking the QString arguments is used. + * You can use the returned widget to customize the passivepopup while + * keeping the look similar to the "standard" passivepopups. + * + * After customizing the widget, pass it to setView( QWidget* ) + * + * @param caption The window caption (title) on the popup + * @param text The text for the popup + * @param icon The icon to use for the popup + * @param parent The parent widget used for the returned QVBox. If left 0L, + * then "this", i.e. the passive popup object will be used. + * + * @return a QVBox containing the given arguments, looking like the + * standard passivepopups. + * @see setView( QWidget * ) + * @see setView( const QString&, const QString& ) + * @see setView( const QString&, const QString&, const QPixmap& ) + */ + QVBox * standardView( const QString& caption, const QString& text, + const QPixmap& icon, QWidget *parent = 0L ); + + /** + * Returns the main view. + */ + QWidget *view() const { return msgView; } + + /** + * Returns the delay before the popup is removed automatically. + */ + int timeout() const { return hideDelay; } + + /** + * Enables / disables auto-deletion of this widget when the timeout + * occurs. + * The default is false. If you use the class-methods message(), + * auto-delection is turned on by default. + */ + virtual void setAutoDelete( bool autoDelete ); + + /** + * @returns true if the widget auto-deletes itself when the timeout occurs. + * @see setAutoDelete + */ + bool autoDelete() const { return m_autoDelete; } + + /** + * Sets the anchor of this balloon. The balloon tries automatically to adjust + * itself somehow around the point. + * @since 3.5 + */ + void setAnchor( const QPoint& anchor ); + + // TODO KDE4: give all the statics method a const QPoint p = QPoint() that in + // case the point is not null calls the show(cosnt QPoint &p) method instead + // the show() one. + /** + * Convenience method that displays popup with the specified message beside the + * icon of the specified widget. + * Note that the returned object is destroyed when it is hidden. + * @see setAutoDelete + */ + static KPassivePopup *message( const QString &text, QWidget *parent, const char *name=0 ); + + /** + * Convenience method that displays popup with the specified caption and message + * beside the icon of the specified widget. + * Note that the returned object is destroyed when it is hidden. + * @see setAutoDelete + */ + static KPassivePopup *message( const QString &caption, const QString &text, + QWidget *parent, const char *name=0 ); + + /** + * Convenience method that displays popup with the specified icon, caption and + * message beside the icon of the specified widget. + * Note that the returned object is destroyed when it is hidden. + * @see setAutoDelete + */ + static KPassivePopup *message( const QString &caption, const QString &text, + const QPixmap &icon, + QWidget *parent, const char *name=0, int timeout = -1 ); + + /** + * Convenience method that displays popup with the specified icon, caption and + * message beside the icon of the specified window. + * Note that the returned object is destroyed when it is hidden. + * @see setAutoDelete + */ + static KPassivePopup *message( const QString &caption, const QString &text, + const QPixmap &icon, + WId parent, const char *name=0, int timeout = -1 ); + + /** + * Convenience method that displays popup with the specified popup-style and message beside the + * icon of the specified widget. + * Note that the returned object is destroyed when it is hidden. + * @see setAutoDelete + */ + static KPassivePopup *message( int popupStyle, const QString &text, QWidget *parent, + const char *name=0 ); + + /** + * Convenience method that displays popup with the specified popup-style, caption and message + * beside the icon of the specified widget. + * Note that the returned object is destroyed when it is hidden. + * @see setAutoDelete + */ + static KPassivePopup *message( int popupStyle, const QString &caption, const QString &text, + QWidget *parent, const char *name=0 ); + + /** + * Convenience method that displays popup with the specified popup-style, icon, caption and + * message beside the icon of the specified widget. + * Note that the returned object is destroyed when it is hidden. + * @see setAutoDelete + */ + static KPassivePopup *message( int popupStyle, const QString &caption, const QString &text, + const QPixmap &icon, + QWidget *parent, const char *name=0, int timeout = -1 ); + + /** + * Convenience method that displays popup with the specified popup-style, icon, caption and + * message beside the icon of the specified window. + * Note that the returned object is destroyed when it is hidden. + * @see setAutoDelete + */ + static KPassivePopup *message( int popupStyle, const QString &caption, const QString &text, + const QPixmap &icon, + WId parent, const char *name=0, int timeout = -1 ); + + +public slots: + /** + * Sets the delay for the popup is removed automatically. Setting the delay to 0 + * disables the timeout, if you're doing this, you may want to connect the + * clicked() signal to the hide() slot. + * Setting the delay to -1 makes it use the default value. + * + * @see timeout + */ + void setTimeout( int delay ); + + /** + * Reimplemented to reposition the popup. + */ + virtual void show(); + + /** + * Shows the popup in the given point + * @since 3.5 + */ + void show(const QPoint &p); + +signals: + /** + * Emitted when the popup is clicked. + */ + void clicked(); + + /** + * Emitted when the popup is clicked. + */ + void clicked( QPoint pos ); + +protected: + /** + * This method positions the popup. + */ + virtual void positionSelf(); + + /** + * Reimplemented to destroy the object when autoDelete() is + * enabled. + */ + virtual void hideEvent( QHideEvent * ); + + /** + * Moves the popup to be adjacent to the icon of the specified rectangle. + */ + void moveNear( QRect target ); + + /** + * Reimplemented to detect mouse clicks. + */ + virtual void mouseReleaseEvent( QMouseEvent *e ); + + /** + * If no relative window (eg taskbar button, system tray window) is + * available, use this rectangle (pass it to moveNear()). + * Basically KWinModule::workArea() with width and height set to 0 + * so that moveNear uses the upper-left position. + * @return The QRect to be passed to moveNear() if no other is + * available. + */ + QRect defaultArea() const; + + /** + * Updates the transparency mask. Unused if PopupStyle == Boxed + * @since 3.5 + */ + void updateMask(); + + /** + * Overwrite to paint the border when PopupStyle == Balloon. + * Unused if PopupStyle == Boxed + */ + virtual void paintEvent( QPaintEvent* pe ); + +private: + void init( int popupStyle ); + + WId window; + QWidget *msgView; + QBoxLayout *topLayout; + int hideDelay; + QTimer *hideTimer; + + QLabel *ttlIcon; + QLabel *ttl; + QLabel *msg; + + bool m_autoDelete; + + /* @internal */ + class Private; + Private *d; +}; + +#endif // KPASSIVEPOPUP_H + +// Local Variables: +// c-basic-offset: 4 +// End: + |