plasma/popupapplet.h

   1 /*
   2  * Copyright 2008 by Montel Laurent <montel@kde.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the Free Software
  16  * Foundation, Inc., 51 Franklin St, Fifth Floor,
  17  * Boston, MA  02110-1301  USA
  18  */
  19
  20 #ifndef PLASMA_POPUPAPPLET_H
  21 #define PLASMA_POPUPAPPLET_H
  22
  23 #include <plasma/applet.h>
  24 #include <plasma/plasma_export.h>
  25
  26 class QGraphicsProxyWidget;
  27 class QGraphicsLinearLayout;
  28
  29 namespace Plasma
  30 {
  31
  32 class Dialog;
  33 class IconWidget;
  34 class PopupAppletPrivate;
  35
  36 /**
  37  * Allows applets to automatically 'collapse' into an icon when put in an panel, and is a convenient
  38  * base class for any applet that wishes to use extenders.
  39  *
  40  * Applets that subclass this class should implement either widget() or graphicsWidget() to return a
  41  * widget that will be displayed in the applet if the applet is in a Planar or MediaCenter form
  42  * factor. If the applet is put in a panel, an icon will be displayed instead, which shows the
  43  * widget in a popup when clicked.
  44  *
  45  * If you use this class as a base class for your extender using applet, the extender will
  46  * automatically be used for the popup; reimplementing graphicsWidget() is unnecessary in this case.
  47  */
  48
  49 class PLASMA_EXPORT PopupApplet : public Plasma::Applet
  50 {
  51     Q_OBJECT
  52 public:
  53     PopupApplet(QObject *parent, const QVariantList &args);
  54     ~PopupApplet();
  55
  56     /**
  57      * @arg icon the icon that has to be displayed when the applet is in a panel.
  58      */
  59     void setPopupIcon(const QIcon &icon);
  60
  61     /**
  62      * @arg icon the icon that has to be displayed when the applet is in a panel.
  63      */
  64     void setPopupIcon(const QString &iconName);
  65
  66     /**
  67      * @return the icon that is displayed when the applet is in a panel.
  68      */
  69     QIcon popupIcon() const;
  70
  71     /**
  72      * Implement either this function or graphicsWidget().
  73      * @return the widget that will get shown in either a layout, in the applet or in a Dialog,
  74      * depending on the form factor of the applet.
  75      */
  76     virtual QWidget *widget();
  77
  78     /**
  79      * Implement either this function or widget().
  80      * @return the widget that will get shown in either a layout, in the applet or in a Dialog,
  81      * depending on the form factor of the applet.
  82      */
  83     virtual QGraphicsWidget *graphicsWidget();
  84
  85     /**
  86      * @return the placement of the popup relating to the icon
  87      */
  88     Plasma::PopupPlacement popupPlacement() const;
  89
  90     /**
  91      * Sets whether or not the dialog popup that gets created should be a "passive" popup
  92      * that does not steal focus from other windows or not.
  93      *
  94      * @arg passive true if the dialog should be treated as a passive popup
  95      */
  96     void setPassivePopup(bool passive);
  97
  98     /**
  99      * @return true if the dialog will be treated as a passive poup
 100      */
 101     bool isPassivePopup() const;
 102
 103     /**
 104      * @return true if the applet is popped up
 105      */
 106     bool isPopupShowing() const;
 107
 108 public Q_SLOTS:
 109     /**
 110      * Hides the popup.
 111      */
 112     void hidePopup();
 113
 114     /**
 115      * Shows the dialog showing the widget if the applet is in a panel.
 116      * @arg displayTime the time in ms that the popup should be displayed, defaults to 0 which means
 117      * always (until the user closes it again, that is).
 118      */
 119     void showPopup(uint displayTime = 0);
 120
 121     /**
 122      * Toggles the popup.
 123      */
 124     void togglePopup();
 125
 126 protected:
 127     /**
 128      * This event handler can be reimplemented in a subclass to receive an
 129      * event before the popup is shown or hidden.
 130      * @arg show true if the popup is going to be shown, false if the popup
 131      * is going to be hidden.
 132      * Note that showing and hiding the popup on click is already done in PopupApplet.
 133      */
 134     virtual void popupEvent(bool show);
 135
 136     void mousePressEvent(QGraphicsSceneMouseEvent *event);
 137     void mouseReleaseEvent(QGraphicsSceneMouseEvent *event);
 138     bool eventFilter(QObject *watched, QEvent *event);
 139     void dragEnterEvent(QGraphicsSceneDragDropEvent *event);
 140     void dragLeaveEvent(QGraphicsSceneDragDropEvent *event);
 141     void dropEvent(QGraphicsSceneDragDropEvent *event);
 142
 143 private:
 144     Q_PRIVATE_SLOT(d, void internalTogglePopup())
 145     Q_PRIVATE_SLOT(d, void hideTimedPopup())
 146     Q_PRIVATE_SLOT(d, void clearPopupLostFocus())
 147     Q_PRIVATE_SLOT(d, void dialogSizeChanged())
 148     Q_PRIVATE_SLOT(d, void dialogStatusChanged(bool))
 149
 150     friend class Applet;
 151     friend class PopupAppletPrivate;
 152     PopupAppletPrivate * const d;
 153 };
 154
 155 } // Plasma namespace
 156
 157 #endif /* POPUPAPPLET_H */
 158