containment.h

Go to the documentation of this file.

/*
 *   Copyright 2007 by Aaron Seigo <aseigo@kde.org>
 *   Copyright 2008 by Ménard Alexis <darktears31@gmail.com>
 *   Copyright (c) 2009 Chani Armitage <chani@kde.org>
 *
 *   This program is free software; you can redistribute it and/or modify
 *   it under the terms of the GNU Library General Public License as
 *   published by the Free Software Foundation; either version 2, or
 *   (at your option) any later version.
 *
 *   This program is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details
 *
 *   You should have received a copy of the GNU Library General Public
 *   License along with this program; if not, write to the
 *   Free Software Foundation, Inc.,
 *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 */

#ifndef PLASMA_CONTAINMENT_H
#define PLASMA_CONTAINMENT_H

#include <QtGui/QGraphicsItem>
#include <QtGui/QWidget>
#include <QtGui/QStyleOptionGraphicsItem>

#include <kplugininfo.h>
#include <ksharedconfig.h>
#include <kgenericfactory.h>

#include <plasma/applet.h>
#include <plasma/animator.h>


namespace Plasma
{

class AccessAppletJob;
class AppletHandle;
class DataEngine;
class Package;
class Corona;
class View;
class Wallpaper;
class ContainmentActions;
class ContainmentPrivate;
class AbstractToolBox;

class PLASMA_EXPORT Containment : public Applet
{
    Q_OBJECT

    public:
        class PLASMA_EXPORT StyleOption : public QStyleOptionGraphicsItem
        {
            public:
                explicit StyleOption();
                explicit StyleOption(const StyleOption &other);
                explicit StyleOption(const QStyleOptionGraphicsItem &other);

                enum StyleOptionType {
                    Type = SO_CustomBase + 1
                };
                enum StyleOptionVersion {
                    Version = QStyleOptionGraphicsItem::Version + 1
                };

                Plasma::View *view;
        };

        enum Type {
            NoContainmentType = -1,  
            DesktopContainment = 0,  
            PanelContainment,        
            CustomContainment = 127, 
            CustomPanelContainment = 128 
        };

        explicit Containment(QGraphicsItem *parent = 0,
                             const QString &serviceId = QString(),
                             uint containmentId = 0);

        Containment(QObject *parent, const QVariantList &args);

        ~Containment();

        void init();

        Type containmentType() const;

        Corona *corona() const;

        static KPluginInfo::List listContainments(const QString &category = QString(),
                                                  const QString &parentApp = QString());

        static KPluginInfo::List listContainmentsOfType(const QString &type,
                                                        const QString &category = QString(),
                                                        const QString &parentApp = QString());

        static QStringList listContainmentTypes();

        static KPluginInfo::List listContainmentsForMimetype(const QString &mimetype);

        Applet *addApplet(const QString &name, const QVariantList &args = QVariantList(),
                          const QRectF &geometry = QRectF(-1, -1, -1, -1));

        void addApplet(Applet *applet, const QPointF &pos = QPointF(-1, -1), bool dontInit = true);

        Applet::List applets() const;

        void clearApplets();

        void setScreen(int screen, int desktop = -1);

        int screen() const;

        int lastScreen() const;

        int desktop() const;

        int lastDesktop() const;

        void save(KConfigGroup &group) const;

        void restore(KConfigGroup &group);

        void enableAction(const QString &name, bool enable);

        void addToolBoxAction(QAction *action);

        void removeToolBoxAction(QAction *action);

        void setToolBoxOpen(bool open);

        bool isToolBoxOpen() const;

        void openToolBox();

        void closeToolBox();

        void addAssociatedWidget(QWidget *widget);

        void removeAssociatedWidget(QWidget *widget);

        bool drawWallpaper();

        void setWallpaper(const QString &pluginName, const QString &mode = QString());

        Plasma::Wallpaper *wallpaper() const;

        void setActivity(const QString &activity);

        QString activity() const;

        Context* context() const;

        void showContextMenu(const QPointF &containmentPos, const QPoint &screenPos);

        virtual void showDropZone(const QPoint pos);

        void setContainmentActions(const QString &trigger, const QString &pluginName);

        QStringList containmentActionsTriggers();

        QString containmentActions(const QString &trigger);

        KConfigGroup containmentActionsConfig();

Q_SIGNALS:
        void appletAdded(Plasma::Applet *applet, const QPointF &pos);

        void appletRemoved(Plasma::Applet *applet);

        void zoomRequested(Plasma::Containment *containment, Plasma::ZoomDirection direction);

        void toolBoxToggled();

        void toolBoxVisibilityChanged(bool);

        void addSiblingContainment(Plasma::Containment *);

        void showAddWidgetsInterface(const QPointF &pos);

        void screenChanged(int wasScreen, int isScreen, Plasma::Containment *containment);

        void configureRequested(Plasma::Containment *containment);

        void contextChanged(Plasma::Context *context);

    public Q_SLOTS:
        void setLocation(Plasma::Location location);

        void setFormFactor(Plasma::FormFactor formFactor);

        void addSiblingContainment();

        void focusNextApplet();

        void focusPreviousApplet();

        void destroy();

        void destroy(bool confirm);

        void showConfigurationInterface();

        void configChanged();

    protected:
        //FIXME plasma2: those should be public to allow scripted containments access them
        void setContainmentType(Containment::Type type);

        void setDrawWallpaper(bool drawWallpaper);

        virtual void saveContents(KConfigGroup &group) const;

        virtual void restoreContents(KConfigGroup &group);

        void mouseMoveEvent(QGraphicsSceneMouseEvent *event);
        void mousePressEvent(QGraphicsSceneMouseEvent *event);
        void mouseReleaseEvent(QGraphicsSceneMouseEvent *event);
        void contextMenuEvent(QGraphicsSceneContextMenuEvent *event);
        void keyPressEvent(QKeyEvent *event);
        void wheelEvent(QGraphicsSceneWheelEvent *event);
        bool sceneEventFilter(QGraphicsItem *watched, QEvent *event);
        QVariant itemChange(GraphicsItemChange change, const QVariant &value);

        void dragEnterEvent(QGraphicsSceneDragDropEvent *event);

        void dragLeaveEvent(QGraphicsSceneDragDropEvent *event);

        void dragMoveEvent(QGraphicsSceneDragDropEvent *event);

        void dropEvent(QGraphicsSceneDragDropEvent *event);

        void resizeEvent(QGraphicsSceneResizeEvent *event);

#ifndef KDE_NO_DEPRECATED
        KDE_DEPRECATED const QGraphicsItem *toolBoxItem() const;
#endif

        void setToolBox(AbstractToolBox *toolBox);

        AbstractToolBox *toolBox() const;

    private:
        Containment(const QString &packagePath, uint appletId, const QVariantList &args);

        Q_PRIVATE_SLOT(d, void appletDestroyed(Plasma::Applet*))
        Q_PRIVATE_SLOT(d, void appletAppearAnimationComplete())
        Q_PRIVATE_SLOT(d, void triggerShowAddWidgets())
        Q_PRIVATE_SLOT(d, void positionToolBox())
        Q_PRIVATE_SLOT(d, void requestConfiguration())
        Q_PRIVATE_SLOT(d, void updateToolBoxVisibility())
        Q_PRIVATE_SLOT(d, void showDropZoneDelayed())
        Q_PRIVATE_SLOT(d, void checkStatus(Plasma::ItemStatus))
        Q_PRIVATE_SLOT(d, void remoteAppletReady(Plasma::AccessAppletJob *))
        Q_PRIVATE_SLOT(d, void onContextChanged(Plasma::Context *con))
        Q_PRIVATE_SLOT(d, void mimeTypeRetrieved(KIO::Job *, const QString &))
        Q_PRIVATE_SLOT(d, void dropJobResult(KJob *))

        friend class Applet;
        friend class AppletPrivate;
        friend class AppletScript;
        friend class CoronaPrivate;
        friend class ContainmentPrivate;
        friend class ContainmentActions;
        friend class PopupApplet;
        friend class View;
        ContainmentPrivate *const d;
};

} // Plasma namespace

#endif // multiple inclusion guard