home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kpassivepopup.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-09-10  |  11.3 KB  |  364 lines

  1. // -*- c++ -*-
  2.  
  3. /*
  4.  *   Copyright            : (C) 2001-2002 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.  
  11. #ifndef KPASSIVEPOPUP_H
  12. #define KPASSIVEPOPUP_H
  13.  
  14. #include <qframe.h>
  15.  
  16. #include <kdelibs_export.h>
  17.  
  18. class QBoxLayout;
  19. class QTimer;
  20. class QLabel;
  21. class QVBox;
  22.  
  23. /**
  24.  * @short A dialog-like popup that displays messages without interupting the user.
  25.  *
  26.  * The simplest uses of KPassivePopup are by using the various message() static
  27.  * methods. The position the popup appears at depends on the type of the parent window:
  28.  *
  29.  * @li Normal Windows: The popup is placed adjacent to the icon of the window.
  30.  * @li System Tray Windows: The popup is placed adjact to the system tray window itself.
  31.  * @li Skip Taskbar Windows: The popup is placed adjact to the window
  32.  *     itself if it is visible, and at the edge of the desktop otherwise.
  33.  *
  34.  * You also have the option of calling show with a QPoint as a parameter that
  35.  * removes the automatic placing of KPassivePopup and shows it in the point you want.
  36.  *
  37.  * The most basic use of KPassivePopup displays a popup containing a piece of text:
  38.  * \code
  39.  *    KPassivePopup::message( "This is the message", this );
  40.  * \endcode
  41.  * We can create popups with titles and icons too, as this example shows:
  42.  * \code
  43.  *    QPixmap px;
  44.  *    px.load( "hi32-app-logtracker.png" );
  45.  *    KPassivePopup::message( "Some title", "This is the main text", px, this );
  46.  * \endcode
  47.  * For more control over the popup, you can use the setView(QWidget *) method
  48.  * to create a custom popup.
  49.  * \code
  50.  *    KPassivePopup *pop = new KPassivePopup( parent );
  51.  *
  52.  *    QVBox *vb = new QVBox( pop );
  53.  *    (void) new QLabel( vb, "<b>Isn't this great?</b>" );
  54.  *
  55.  *    QHBox *box = new QHBox( vb );
  56.  *    (void) new QPushButton( box, "Yes" );
  57.  *    (void) new QPushButton( box, "No" );
  58.  *
  59.  *    pop->setView( vb );
  60.  *    pop->show();
  61.  * \endcode
  62.  *
  63.  * @version $Id: kpassivepopup.h 428049 2005-06-22 21:24:17Z aacid $
  64.  * @since 3.1
  65.  * @author Richard Moore, rich@kde.org
  66.  * @author Sascha Cunz, sascha.cunz@tiscali.de
  67.  */
  68. class KDEUI_EXPORT KPassivePopup : public QFrame
  69. {
  70.     Q_OBJECT
  71.     Q_PROPERTY (bool autoDelete READ autoDelete WRITE setAutoDelete )
  72.     Q_PROPERTY (int timeout READ timeout WRITE setTimeout )
  73.  
  74. public:
  75.     /**
  76.      * Styles that a KPassivePopup can have.
  77.      * @since 3.5
  78.      */
  79.     enum PopupStyle
  80.     {
  81.         Boxed,             ///< Information will appear in a framed box (default)
  82.         Balloon,           ///< Information will appear in a comic-alike balloon
  83.     CustomStyle=128    ///< Ids greater than this are reserved for use by subclasses
  84.     };
  85.  
  86.     /**
  87.      * Creates a popup for the specified widget.
  88.      */
  89.     KPassivePopup( QWidget *parent=0, const char *name=0, WFlags f=0 );
  90.  
  91.     /**
  92.      * Creates a popup for the specified window.
  93.      */
  94.     KPassivePopup( WId parent, const char *name=0, WFlags f=0 );
  95.  
  96.     /**
  97.      * Creates a popup for the specified widget.
  98.      * @since 3.5
  99.      */
  100.     KPassivePopup( int popupStyle, QWidget *parent=0, const char *name=0, WFlags f=0 );
  101.  
  102.     /**
  103.      * Creates a popup for the specified window.
  104.      * @since 3.5
  105.      */
  106.     KPassivePopup( int popupStyle, WId parent, const char *name=0, WFlags f=0 );
  107.  
  108.     /**
  109.      * Cleans up.
  110.      */
  111.     virtual ~KPassivePopup();
  112.  
  113.     /**
  114.      * Sets the main view to be the specified widget (which must be a child of the popup).
  115.      */
  116.     void setView( QWidget *child );
  117.  
  118.     /**
  119.      * Creates a standard view then calls setView(QWidget*) .
  120.      */
  121.     void setView( const QString &caption, const QString &text = QString::null );
  122.  
  123.     /**
  124.      * Creates a standard view then calls setView(QWidget*) .
  125.      */
  126.     virtual void setView( const QString &caption, const QString &text, const QPixmap &icon );
  127.  
  128.     /**
  129.      * Returns a widget that is used as standard view if one of the 
  130.      * setView() methods taking the QString arguments is used.
  131.      * You can use the returned widget to customize the passivepopup while 
  132.      * keeping the look similar to the "standard" passivepopups.
  133.      *
  134.      * After customizing the widget, pass it to setView( QWidget* )
  135.      *
  136.      * @param caption The window caption (title) on the popup
  137.      * @param text The text for the popup
  138.      * @param icon The icon to use for the popup
  139.      * @param parent The parent widget used for the returned QVBox. If left 0L,
  140.      * then "this", i.e. the passive popup object will be used.
  141.      *
  142.      * @return a QVBox containing the given arguments, looking like the
  143.      * standard passivepopups.
  144.      * @see setView( QWidget * )
  145.      * @see setView( const QString&, const QString& )
  146.      * @see setView( const QString&, const QString&, const QPixmap& )
  147.      */
  148.     QVBox * standardView( const QString& caption, const QString& text,
  149.                           const QPixmap& icon, QWidget *parent = 0L );
  150.  
  151.     /**
  152.      * Returns the main view.
  153.      */
  154.     QWidget *view() const { return msgView; }
  155.  
  156.     /**
  157.      * Returns the delay before the popup is removed automatically.
  158.      */
  159.     int timeout() const { return hideDelay; }
  160.  
  161.     /**
  162.      * Enables / disables auto-deletion of this widget when the timeout
  163.      * occurs.
  164.      * The default is false. If you use the class-methods message(),
  165.      * auto-delection is turned on by default.
  166.      */
  167.     virtual void setAutoDelete( bool autoDelete );
  168.  
  169.     /**
  170.      * @returns true if the widget auto-deletes itself when the timeout occurs.
  171.      * @see setAutoDelete
  172.      */
  173.     bool autoDelete() const { return m_autoDelete; }
  174.  
  175.     /**
  176.      * Sets the anchor of this balloon. The balloon tries automatically to adjust
  177.      * itself somehow around the point.
  178.      * @since 3.5
  179.      */
  180.     void setAnchor( const QPoint& anchor );
  181.  
  182.     // TODO KDE4: give all the statics method a const QPoint p = QPoint() that in 
  183.     // case the point is not null calls the show(cosnt QPoint &p) method instead
  184.     // the show() one.
  185.     /**
  186.      * Convenience method that displays popup with the specified  message  beside the
  187.      * icon of the specified widget.
  188.      * Note that the returned object is destroyed when it is hidden.
  189.      * @see setAutoDelete
  190.      */
  191.     static KPassivePopup *message( const QString &text, QWidget *parent, const char *name=0 );
  192.  
  193.     /**
  194.      * Convenience method that displays popup with the specified caption and message
  195.      * beside the icon of the specified widget.
  196.      * Note that the returned object is destroyed when it is hidden.
  197.      * @see setAutoDelete
  198.      */
  199.     static KPassivePopup *message( const QString &caption, const QString &text,
  200.                    QWidget *parent, const char *name=0 );
  201.  
  202.     /**
  203.      * Convenience method that displays popup with the specified icon, caption and
  204.      * message beside the icon of the specified widget.
  205.      * Note that the returned object is destroyed when it is hidden.
  206.      * @see setAutoDelete
  207.      */
  208.     static KPassivePopup *message( const QString &caption, const QString &text,
  209.                    const QPixmap &icon,
  210.                    QWidget *parent, const char *name=0, int timeout = -1 );
  211.  
  212.     /**
  213.      * Convenience method that displays popup with the specified icon, caption and
  214.      * message beside the icon of the specified window.
  215.      * Note that the returned object is destroyed when it is hidden.
  216.      * @see setAutoDelete
  217.      */
  218.     static KPassivePopup *message( const QString &caption, const QString &text,
  219.                    const QPixmap &icon,
  220.                    WId parent, const char *name=0, int timeout = -1 );
  221.  
  222.     /**
  223.      * Convenience method that displays popup with the specified popup-style and message beside the
  224.      * icon of the specified widget.
  225.      * Note that the returned object is destroyed when it is hidden.
  226.      * @see setAutoDelete
  227.      */
  228.     static KPassivePopup *message( int popupStyle, const QString &text, QWidget *parent,
  229.                    const char *name=0 );
  230.  
  231.     /**
  232.      * Convenience method that displays popup with the specified popup-style, 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( int popupStyle, const QString &caption, const QString &text,
  238.                    QWidget *parent, const char *name=0 );
  239.  
  240.     /**
  241.      * Convenience method that displays popup with the specified popup-style, icon, caption and
  242.      * message beside the icon of the specified widget.
  243.      * Note that the returned object is destroyed when it is hidden.
  244.      * @see setAutoDelete
  245.      */
  246.     static KPassivePopup *message( int popupStyle, const QString &caption, const QString &text,
  247.                    const QPixmap &icon,
  248.                    QWidget *parent, const char *name=0, int timeout = -1 );
  249.  
  250.     /**
  251.      * Convenience method that displays popup with the specified popup-style, icon, caption and
  252.      * message beside the icon of the specified window.
  253.      * Note that the returned object is destroyed when it is hidden.
  254.      * @see setAutoDelete
  255.      */
  256.     static KPassivePopup *message( int popupStyle, const QString &caption, const QString &text,
  257.                    const QPixmap &icon,
  258.                    WId parent, const char *name=0, int timeout = -1 );
  259.  
  260.  
  261. public slots:
  262.     /**
  263.      * Sets the delay for the popup is removed automatically. Setting the delay to 0
  264.      * disables the timeout, if you're doing this, you may want to connect the
  265.      * clicked() signal to the hide() slot.
  266.      * Setting the delay to -1 makes it use the default value.
  267.      *
  268.      * @see timeout
  269.      */
  270.     void setTimeout( int delay );
  271.  
  272.     /**
  273.      * Reimplemented to reposition the popup.
  274.      */
  275.     virtual void show();
  276.  
  277.     /**
  278.      * Shows the popup in the given point
  279.      * @since 3.5
  280.      */
  281.     void show(const QPoint &p);
  282.  
  283. signals:
  284.     /**
  285.      * Emitted when the popup is clicked.
  286.      */
  287.     void clicked();
  288.  
  289.     /**
  290.      * Emitted when the popup is clicked.
  291.      */
  292.     void clicked( QPoint pos );
  293.  
  294. protected:
  295.     /**
  296.      * This method positions the popup.
  297.      */
  298.     virtual void positionSelf();
  299.  
  300.     /**
  301.      * Reimplemented to destroy the object when autoDelete() is
  302.      * enabled.
  303.      */
  304.     virtual void hideEvent( QHideEvent * );
  305.  
  306.     /**
  307.      * Moves the popup to be adjacent to the icon of the specified rectangle.
  308.      */
  309.     void moveNear( QRect target );
  310.  
  311.     /**
  312.      * Reimplemented to detect mouse clicks.
  313.      */
  314.     virtual void mouseReleaseEvent( QMouseEvent *e );
  315.  
  316.     /**
  317.      * If no relative window (eg taskbar button, system tray window) is
  318.      * available, use this rectangle (pass it to moveNear()).
  319.      * Basically KWinModule::workArea() with width and height set to 0
  320.      * so that moveNear uses the upper-left position.
  321.      * @return The QRect to be passed to moveNear() if no other is
  322.      * available.
  323.      */
  324.     QRect defaultArea() const;
  325.  
  326.     /**
  327.      * Updates the transparency mask. Unused if PopupStyle == Boxed
  328.      * @since 3.5
  329.      */
  330.     void updateMask();
  331.  
  332.     /**
  333.      * Overwrite to paint the border when PopupStyle == Balloon.
  334.      * Unused if PopupStyle == Boxed
  335.      */
  336.     virtual void paintEvent( QPaintEvent* pe );
  337.  
  338. private:
  339.     void init( int popupStyle );
  340.  
  341.     WId window;
  342.     QWidget *msgView;
  343.     QBoxLayout *topLayout;
  344.     int hideDelay;
  345.     QTimer *hideTimer;
  346.  
  347.     QLabel *ttlIcon;
  348.     QLabel *ttl;
  349.     QLabel *msg;
  350.  
  351.     bool m_autoDelete;
  352.  
  353.     /* @internal */
  354.     class Private;
  355.     Private *d;
  356. };
  357.  
  358. #endif // KPASSIVEPOPUP_H
  359.  
  360. // Local Variables:
  361. // c-basic-offset: 4
  362. // End:
  363.  
  364.