applet.h

Go to the documentation of this file.

/*
 *   Copyright 2006-2007 by Aaron Seigo <aseigo@kde.org>
 *   Copyright 2007 by Riccardo Iaconelli <riccardo@kde.org>
 *   Copyright 2008 by Ménard Alexis <darktears31@gmail.com>

 *   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_APPLET_H
#define PLASMA_APPLET_H

#include <QtGui/QGraphicsItem>
#include <QtGui/QGraphicsWidget>
#include <QtGui/QIcon>

#include <kconfiggroup.h>
#include <kgenericfactory.h>
#include <kplugininfo.h>
#include <kshortcut.h>

#include <plasma/configloader.h>
#include <plasma/packagestructure.h>
#include <plasma/plasma.h>
#include <plasma/animator.h>
#include <plasma/version.h>
#include <plasma/framesvg.h>

class QWidget;

class KConfigDialog;
class QGraphicsView;
class KActionCollection;

namespace Plasma
{

class AppletPrivate;
class Containment;
class Context;
class DataEngine;
class Extender;
class ExtenderItem;
class Package;


class PLASMA_EXPORT Applet : public QGraphicsWidget
{
    Q_OBJECT
    Q_PROPERTY(bool hasConfigurationInterface READ hasConfigurationInterface)
    Q_PROPERTY(QString name READ name)
    Q_PROPERTY(QString pluginName READ pluginName)
    Q_PROPERTY(QString category READ category)
    Q_PROPERTY(ImmutabilityType immutability READ immutability WRITE setImmutability)
    Q_PROPERTY(bool hasFailedToLaunch READ hasFailedToLaunch WRITE setFailedToLaunch)
    Q_PROPERTY(bool isBusy READ isBusy WRITE setBusy) //KDE5: remove
    Q_PROPERTY(bool busy READ isBusy WRITE setBusy)
    Q_PROPERTY(bool configurationRequired READ configurationRequired WRITE setConfigurationRequired)
    Q_PROPERTY(QRectF geometry READ geometry WRITE setGeometry)
    Q_PROPERTY(bool shouldConserveResources READ shouldConserveResources)
    Q_PROPERTY(uint id READ id)
    Q_PROPERTY(bool userConfiguring READ isUserConfiguring)
    Q_PROPERTY(BackgroundHints backgroundHints READ backgroundHints WRITE setBackgroundHints)
    Q_ENUMS(BackgroundHints)

    public:
        typedef QList<Applet*> List;
        typedef QHash<QString, Applet*> Dict;

        enum BackgroundHint {
            NoBackground = 0,         
            StandardBackground = 1,   
            TranslucentBackground = 2, 
            DefaultBackground = StandardBackground 
        };
        Q_DECLARE_FLAGS(BackgroundHints, BackgroundHint)

        ~Applet();

        static PackageStructure::Ptr packageStructure();

        uint id() const;

        KConfigGroup config() const;

        KConfigGroup config(const QString &group) const;

        virtual void save(KConfigGroup &group) const;

        virtual void restore(KConfigGroup &group);

        KConfigGroup globalConfig() const;

        ConfigLoader *configScheme() const;

        Q_INVOKABLE DataEngine *dataEngine(const QString &name) const;

        const Package *package() const;

        QGraphicsView *view() const;

        QRectF mapFromView(const QGraphicsView *view, const QRect &rect) const;

        QRect mapToView(const QGraphicsView *view, const QRectF &rect) const;

        QPoint popupPosition(const QSize &s) const;

        QPoint popupPosition(const QSize &s, Qt::AlignmentFlag alignment) const;

        void updateConstraints(Plasma::Constraints constraints = Plasma::AllConstraints);

        virtual FormFactor formFactor() const;

        virtual Location location() const;

        Context *context() const;

        Plasma::AspectRatioMode aspectRatioMode() const;

        void setAspectRatioMode(Plasma::AspectRatioMode);

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

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

        static KPluginInfo::List listAppletInfoForUrl(const QUrl &url);

        static QStringList listCategories(const QString &parentApp = QString(),
                                          bool visibleOnly = true);

        void setCustomCategories(const QStringList &categories);

        QStringList customCategories();

        static Applet *loadPlasmoid(const QString &path, uint appletId = 0,
                                    const QVariantList &args = QVariantList());

        static Applet *load(const QString &name, uint appletId = 0,
                            const QVariantList &args = QVariantList());

        static Applet *load(const KPluginInfo &info, uint appletId = 0,
                            const QVariantList &args = QVariantList());

        static QString category(const KPluginInfo &applet);

        static QString category(const QString &appletName);

        virtual void paintInterface(QPainter *painter,
                                    const QStyleOptionGraphicsItem *option,
                                    const QRect &contentsRect);

        QString name() const;

        QFont font() const;

        QString pluginName() const;

        bool shouldConserveResources() const;

        QString icon() const;

        QString category() const;

        ImmutabilityType immutability() const;

        void paintWindowFrame(QPainter *painter,
                              const QStyleOptionGraphicsItem *option, QWidget *widget);

        bool hasFailedToLaunch() const;

        bool isBusy() const;

        bool configurationRequired() const;

        bool hasConfigurationInterface() const;

        virtual QList<QAction*> contextualActions();

        Q_INVOKABLE QAction *action(QString name) const;

        void addAction(QString name, QAction *action);

        void setBackgroundHints(const BackgroundHints hints);

        BackgroundHints backgroundHints() const;

        bool isContainment() const;

        QRect screenRect() const;

        int type() const;
        enum {
            Type = Plasma::AppletType
        };

        Containment *containment() const;

        void setGlobalShortcut(const KShortcut &shortcut);

        KShortcut globalShortcut() const;

        virtual bool isPopupShowing() const;

        virtual void addAssociatedWidget(QWidget *widget);

        virtual void removeAssociatedWidget(QWidget *widget);

        virtual void initExtenderItem(ExtenderItem *item);

        explicit Applet(QGraphicsItem *parent = 0,
                        const QString &serviceId = QString(),
                        uint appletId = 0);

        explicit Applet(const KPluginInfo &info, QGraphicsItem *parent = 0, uint appletId = 0);

        explicit Applet(QGraphicsItem *parent,
                        const QString &serviceId,
                        uint appletId,
                        const QVariantList &args);


        bool destroyed() const;

        virtual void createConfigurationInterface(KConfigDialog *parent);

        bool hasAuthorization(const QString &constraint) const;

        void setAssociatedApplication(const QString &string);

        void setAssociatedApplicationUrls(const KUrl::List &urls);

        QString associatedApplication() const;

        KUrl::List associatedApplicationUrls() const;

        bool hasValidAssociatedApplication() const;

    Q_SIGNALS:
        void releaseVisualFocus();

#if QT_VERSION >= 0x040700
    protected:
        void geometryChanged(); // in QGraphicsWidget now; preserve BC
#else

        void geometryChanged();
#endif

    Q_SIGNALS:
        void appletTransformedByUser();

        void appletTransformedItself();

        void sizeHintChanged(Qt::SizeHint which);

        void configNeedsSaving();

        void activate();

        void messageButtonPressed(const Plasma::MessageButton button);

        void appletDestroyed(Plasma::Applet *applet);

        void newStatus(Plasma::ItemStatus status);

        void extenderItemRestored(Plasma::ExtenderItem *item);

        void immutabilityChanged(Plasma::ImmutabilityType immutable);

    public Q_SLOTS:
        void setImmutability(const ImmutabilityType immutable);

        virtual void destroy();

        virtual void showConfigurationInterface();

        void showConfigurationInterface(QWidget *widget);

        bool isUserConfiguring() const;

        void raise();

        void lower();

        void flushPendingConstraintsEvents();

        virtual void init();

        virtual void configChanged();

        void setBusy(bool busy);

        QVariantList startupArguments() const;

        ItemStatus status() const;

        void setStatus(const ItemStatus stat);

        void publish(Plasma::AnnouncementMethods methods, const QString &resourceName);

        void unpublish();

        bool isPublished() const;

        void runAssociatedApplication();

    protected:
        Applet(QObject *parent, const QVariantList &args);

        void setFailedToLaunch(bool failed, const QString &reason = QString());

        virtual void saveState(KConfigGroup &config) const;

        void setHasConfigurationInterface(bool hasInterface);

        void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());

        void showMessage(const QIcon &icon, const QString &message, const Plasma::MessageButtons buttons);

        virtual void constraintsEvent(Plasma::Constraints constraints);

        void registerAsDragHandle(QGraphicsItem *item);

        void unregisterAsDragHandle(QGraphicsItem *item);

        bool isRegisteredAsDragHandle(QGraphicsItem *item);

        Extender *extender() const;

        bool eventFilter(QObject *o, QEvent *e);

        bool sceneEventFilter (QGraphicsItem *watched, QEvent *event);

        void mouseMoveEvent(QGraphicsSceneMouseEvent *event);

        void focusInEvent(QFocusEvent *event);

        void resizeEvent(QGraphicsSceneResizeEvent *event);

        QVariant itemChange(GraphicsItemChange change, const QVariant &value);

        QPainterPath shape() const;

        QSizeF sizeHint(Qt::SizeHint which, const QSizeF & constraint = QSizeF()) const;

        void hoverEnterEvent(QGraphicsSceneHoverEvent *event);

        void hoverLeaveEvent(QGraphicsSceneHoverEvent *event);

        void timerEvent (QTimerEvent *event);


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

        Q_PRIVATE_SLOT(d, void setFocus())
        Q_PRIVATE_SLOT(d, void themeChanged())
        Q_PRIVATE_SLOT(d, void cleanUpAndDelete())
        Q_PRIVATE_SLOT(d, void selectItemToDestroy())
        Q_PRIVATE_SLOT(d, void updateRect(const QRectF& rect))
        Q_PRIVATE_SLOT(d, void destroyMessageOverlay())
        Q_PRIVATE_SLOT(d, void clearShortcutEditorPtr())
        Q_PRIVATE_SLOT(d, void configDialogFinished())
        Q_PRIVATE_SLOT(d, void updateShortcuts())
        Q_PRIVATE_SLOT(d, void publishCheckboxStateChanged(int state))
        Q_PRIVATE_SLOT(d, void globalShortcutChanged())
        Q_PRIVATE_SLOT(d, void propagateConfigChanged())
        Q_PRIVATE_SLOT(d, void handleDisappeared(AppletHandle *handle))

        void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0);

        AppletPrivate *const d;

        //Corona needs to access setFailedToLaunch and init
        friend class Corona;
        friend class CoronaPrivate;
        friend class Containment;
        friend class ContainmentPrivate;
        friend class AppletScript;
        friend class AppletHandle;
        friend class AppletPrivate;
        friend class AccessAppletJobPrivate;
        friend class PluginLoader;
        friend class PopupApplet;
        friend class PopupAppletPrivate;
        friend class AssociatedApplicationManager;

        friend class Extender;
        friend class ExtenderGroup;
        friend class ExtenderGroupPrivate;
        friend class ExtenderPrivate;
        friend class ExtenderItem;
};

} // Plasma namespace

Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::Applet::BackgroundHints)

#define K_EXPORT_PLASMA_APPLET(libname, classname) \
K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
K_EXPORT_PLUGIN(factory("plasma_applet_" #libname)) \
K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION)

#endif // multiple inclusion guard