workspace/libs/plasma/containment.h

   1 /*
   2  *   Copyright 2007 by Aaron Seigo <aseigo@kde.org>
   3  *
   4  *   This program is free software; you can redistribute it and/or modify
   5  *   it under the terms of the GNU Library General Public License as
   6  *   published by the Free Software Foundation; either version 2, or
   7  *   (at your option) any later version.
   8  *
   9  *   This program 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
  12  *   GNU General Public License for more details
  13  *
  14  *   You should have received a copy of the GNU Library General Public
  15  *   License along with this program; if not, write to the
  16  *   Free Software Foundation, Inc.,
  17  *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  18  */
  19
  20 #ifndef PLASMA_CONTAINMENT_H
  21 #define PLASMA_CONTAINMENT_H
  22
  23 #include <QtGui/QGraphicsItem>
  24 #include <QtGui/QWidget>
  25 #include <QtGui/QStyleOptionGraphicsItem>
  26
  27 #include <kplugininfo.h>
  28 #include <ksharedconfig.h>
  29 #include <kgenericfactory.h>
  30
  31 #include <plasma/applet.h>
  32 #include <plasma/phase.h>
  33
  34 #include "widgets/icon.h"
  35
  36 namespace Plasma
  37 {
  38
  39 class AppletHandle;
  40 class DataEngine;
  41 class Package;
  42 class Corona;
  43
  44 /**
  45  * @short The base class for plugins that provide backgrounds and applet grouping containers
  46  *
  47  * Containment objects provide the means to group applets into functional sets.
  48  * They also provide the following:
  49  *
  50  * creation of focussing event
  51  * - drawing of the background image (which can be interactive)
  52  * - form factors (e.g. panel, desktop, full screen, etc)
  53  * - applet layout management
  54  *
  55  * Since containment is actually just a Plasma::Applet, all the techniques used
  56  * for writing the visual presentation of Applets is applicable to Containtments.
  57  * Containments are differentiated from Applets by being marked with the ServiceType
  58  * of Plasma/Containment. Plugins registered with both the Applet and the Containment
  59  * ServiceTypes can be loaded for us in either situation.
  60  *
  61  * See techbase.kde.org for a tutorial on writing Containments using this class.
  62  */
  63 class PLASMA_EXPORT Containment : public Applet
  64 {
  65     Q_OBJECT
  66
  67     public:
  68         class StyleOption : public QStyleOptionGraphicsItem
  69         {
  70             public:
  71                 explicit StyleOption();
  72                 explicit StyleOption(const StyleOption &other);
  73                 explicit StyleOption(const QStyleOptionGraphicsItem &other);
  74
  75                 int desktop;
  76         };
  77
  78         typedef QList<Applet*> List;
  79         typedef QHash<QString, Applet*> Dict;
  80
  81         enum Type { NoContainmentType = -1 /**< @internal */,
  82                     DesktopContainment = 0 /**< A desktop containment */,
  83                     PanelContainment /**< A desktop panel */,
  84                     CustomContainment /**< A containment that is neither a desktop nor a panel,
  85                                            but something application specific */
  86                   };
  87
  88         /**
  89          * @arg parent the QGraphicsItem this applet is parented to
  90          * @arg serviceId the name of the .desktop file containing the
  91          *      information about the widget
  92          * @arg appletId a unique id used to differentiate between multiple
  93          *      instances of the same Applet type
  94          */
  95         explicit Containment(QGraphicsItem* parent = 0,
  96                              const QString& serviceId = QString(),
  97                              uint containmentId = 0);
  98
  99         /**
 100          * This constructor is to be used with the plugin loading systems
 101          * found in KPluginInfo and KService. The argument list is expected
 102          * to have two elements: the KService service ID for the desktop entry
 103          * and an applet ID which must be a base 10 number.
 104          *
 105          * @arg parent a QObject parent; you probably want to pass in 0
 106          * @arg args a list of strings containing two entries: the service id
 107          *      and the applet id
 108          */
 109         Containment(QObject* parent, const QVariantList& args);
 110
 111         ~Containment();
 112
 113         /**
 114          * Reimplemented from Applet
 115          */
 116         void init();
 117
 118         /**
 119          * Returns the type of containment
 120          */
 121         Type containmentType() const;
 122
 123         /**
 124          * Sets the type of this containment.
 125          */
 126         void setContainmentType(Containment::Type type);
 127
 128         /**
 129          * Returns the current form factor the applets in this Containment
 130          * are being displayed in.
 131          *
 132          * @see Plasma::FormFactor
 133          */
 134         FormFactor formFactor() const;
 135
 136         /**
 137          * Returns the location of this Containment
 138          *
 139          * @see Plasma::Location
 140          */
 141         Location location() const;
 142
 143         /**
 144          * Returns a list of all known containments.
 145          *
 146          * @param category Only applets matchin this category will be returned.
 147          *                 Useful in conjunction with knownCategories.
 148          *                 If "Misc" is passed in, then applets without a
 149          *                 Categories= entry are also returned.
 150          *                 If an empty string is passed in, all applets are
 151          *                 returned.
 152          * @param parentApp the application to filter applets on. Uses the
 153          *                  X-KDE-ParentApp entry (if any) in the plugin info.
 154          *                  The default value of QString() will result in a
 155          *                  list containing only applets not specifically
 156          *                  registered to an application.
 157          * @return list of applets
 158          **/
 159         static KPluginInfo::List knownContainments(const QString &category = QString(),
 160                                                    const QString &parentApp = QString());
 161
 162         /**
 163          * Returns a list of all known applets associated with a certain mimetype
 164          *
 165          * @return list of applets
 166          **/
 167         static KPluginInfo::List knownContainmentsForMimetype(const QString &mimetype);
 168
 169         /**
 170          * Adds an applet to this Containment
 171          *
 172          * @param name the plugin name for the applet, as given by
 173          *        KPluginInfo::pluginName()
 174          * @param args argument list to pass to the plasmoid
 175          * @param id to assign to this applet, or 0 to auto-assign it a new id
 176          * @param geometry where to place the applet, or to auto-place it if an invalid
 177          *                 is provided
 178          * @param delayedInit if true, init() will not be called on the applet
 179          *
 180          * @return a pointer to the applet on success, or 0 on failure
 181          */
 182         Applet* addApplet(const QString& name, const QVariantList& args = QVariantList(),
 183                           uint id = 0, const QRectF &geometry = QRectF(-1, -1, -1, -1),
 184                           bool delayedInit = false);
 185
 186         /**
 187          * @return the applets currently in this Containment
 188          */
 189         Applet::List applets() const;
 190
 191         /**
 192          * Removes all applets from this Containment
 193          */
 194         void clearApplets();
 195
 196         /**
 197          * add existing applet to this containment at pos
 198          * @param pos the containment-relative position
 199          * @param dontInit if true, init() will not be called on the applet
 200          */
 201         void addApplet(Applet *applet, const QPointF &pos = QPointF(-1, -1), bool dontInit = true);
 202
 203         /**
 204          * @return the index to insert an applet at if you want it near the point pos.
 205          * @param pos the containment-relative position
 206          */
 207         virtual int indexAt(const QPointF &pos) const;
 208
 209         /**
 210          * Sets the physical screen this Containment is associated with.
 211          *
 212          * @param screen the screen number this containment is the desktop for, or -1
 213          *               if it is not serving as the desktop for any screen
 214          */
 215         void setScreen(int screen);
 216
 217         /**
 218          * @return the screen number this containment is serving as the desktop for
 219          *         or -1 if none
 220          */
 221         int screen() const;
 222
 223         /**
 224          * @internal
 225          */
 226         void saveConstraints(KConfigGroup* group) const;
 227
 228         /**
 229          * @internal
 230          */
 231         void loadConstraints(KConfigGroup* group);
 232
 233         /**
 234          * Emits the launchActivated() signal
 235          */
 236         void emitLaunchActivated();
 237
 238         /**
 239          * Constructs a toolbox item and adds it to the toolbox. The toolbox takes over ownership of the item. Returns the constructed tool.
 240          *
 241          * @arg name of the tool
 242          * @arg name of the icon
 243          * @arg text to be displayed on the icon
 244          *
 245          * @return the constructed tool
 246          */
 247         Plasma::Widget * addToolBoxTool(const QString &toolName = QString(), const QString &iconName = QString(), const QString &iconText = QString());
 248
 249         /**
 250          * Enables or disables a toolbox tool by name
 251          *
 252          * @arg name the name of the tool
 253          * @arg enable true to enable, false to disable
 254          */
 255         void enableToolBoxTool(const QString &toolname, bool enable);
 256
 257         /**
 258          * Returns whether or not a given toolbox tool is enabled
 259          */
 260         bool isToolboxToolEnabled(const QString &toolname) const;
 261
 262         /**
 263          * @internal
 264          * Called when constraints have been updated on this containment to provide
 265          * constraint services common to all containments. Containments should still
 266          * implement their own constraintsUpdated method
 267          */
 268         void containmentConstraintsUpdated(Plasma::Constraints constraints);
 269
 270         /**
 271          * Open the Plasma toolbox
 272          */
 273         void showToolbox();
 274
 275         /**
 276          * Close the Plasma toolbox
 277          */
 278         void hideToolbox();
 279
 280         /**
 281          * Repositions the Plasma toolbox.  Useful to ensure its always in the correct place within the view.
 282          */
 283         void repositionToolbox();
 284
 285     Q_SIGNALS:
 286         /**
 287          * This signal is emitted when a new applet is created by the containment
 288          */
 289         void appletAdded(Plasma::Applet* applet);
 290
 291         /**
 292          * This signal is emitted when an applet is destroyed
 293          */
 294         void appletRemoved(Plasma::Applet* applet);
 295
 296         /**
 297          * This signal indicates that an application launch, window
 298          * creation or window focus event was triggered. This is used, for instance,
 299          * to ensure that the Dashboard view in Plasma hides when such an event is
 300          * triggered by an item it is displaying.
 301          */
 302         void launchActivated();
 303
 304         /**
 305          * Emitted when the containment requests zooming out one step.
 306          * Usually only used for desktop containments.
 307          */
 308         void zoomIn();
 309
 310         /**
 311          * Emitted when the containment requests zooming out one step.
 312          * Usually only used for desktop containments.
 313          */
 314         void zoomOut();
 315
 316         /**
 317          * Emitted when the containment requests an add widgets dialog is shown.
 318          * Usually only used for desktop containments.
 319          */
 320         void showAddWidgets();
 321
 322     public Q_SLOTS:
 323         /**
 324          * Informs the Corona as to what position it is in. This is informational
 325          * only, as the Corona doesn't change it's actual location. This is,
 326          * however, passed on to Applets that may be managed by this Corona.
 327          *
 328          * @param location the new location of this Corona
 329          */
 330         void setLocation(Plasma::Location location);
 331
 332         /**
 333          * Sets the form factor for this Corona. This may cause changes in both
 334          * the arrangement of Applets as well as the display choices of individual
 335          * Applets.
 336          */
 337         void setFormFactor(Plasma::FormFactor formFactor);
 338
 339         /**
 340          * Returns the Corona (if any) that this Containment is hosted by
 341          */
 342         Corona* corona() const;
 343
 344     protected:
 345         void contextMenuEvent(QGraphicsSceneContextMenuEvent * event);
 346         void hoverEnterEvent(QGraphicsSceneHoverEvent *event);
 347         void hoverLeaveEvent(QGraphicsSceneHoverEvent *event);
 348         bool sceneEventFilter(QGraphicsItem *watched, QEvent *event);
 349
 350     protected Q_SLOTS:
 351         /**
 352          * @internal
 353          */
 354         void appletDestroyed(QObject*);
 355         void appletAnimationComplete(QGraphicsItem *item, Plasma::Phase::Animation anim);
 356         void dropEvent(QGraphicsSceneDragDropEvent* event);
 357
 358     private Q_SLOTS:
 359         void handleDisappeared(AppletHandle *handle);
 360         void destroyApplet();
 361
 362     private:
 363         QRectF geometryForApplet(Applet *applet) const;
 364         bool regionIsEmpty(const QRectF &region, Applet *ignoredApplet=0) const;
 365         void prepareApplet(Applet *applet, bool delayInit);
 366
 367         Q_DISABLE_COPY(Containment)
 368
 369         class Private;
 370         Private* const d;
 371 };
 372
 373 } // Plasma namespace
 374
 375
 376 #endif // multiple inclusion guard