Plasma/libplasma2/API Review/Containment: Difference between revisions

From KDE Community Wiki
(Created page with "= Constructors = All still needed? * explicit Containment(QObject *parent = 0, const QString &serviceId = QString(), uint containmentId = 0) * Containment(QObject *parent, c...")
 
 
(37 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=Q_PROPERTIES=
All qproperties and invokables must go
=Enums=
Type probably goes in plasma.h
        enum Type {
            NoContainmentType = -1,  /**< @internal */
            DesktopContainment = 0,  /**< A desktop containment */ New name -> suggestions [ Canvas ]
            PanelContainment,        /**< A desktop panel */
            CustomContainment = 127, /**< A containment that is neither a desktop nor a panel
                                        but something application specific */
          CustomPanelContainment = 128 /**< A customized desktop panel */
        };
ToolType goes in plasma.h
it becomes  ActionType (not related to toolbox anymore)
        enum ToolType {
            AddTool = 0,
            ConfigureTool = 100,
            ControlTool = 200,
            MiscTool = 300,
            DestructiveTool = 400,
            UserToolType = DestructiveTool + 1000
        };
        Q_ENUMS(ToolType)
{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"
! Status
! Action
! Enum
{{FeatureDone|Move|Type -> move to Plasma::ContainmenType}}
{{FeatureDone|Move|ToolType -> move to Plasma::ActionType}}
|}
= Constructors =
= Constructors =
All still needed?
* explicit Containment(QObject *parent = 0,  const QString &serviceId = QString(),  uint containmentId = 0)
* Containment(QObject *parent, const QVariantList &args);
* private Containment(const QString &packagePath, uint appletId, const QVariantList &args);


= Methods =
{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
* Applet *addApplet(const QString &name, const QVariantList &args = QVariantList(),  const QRectF &geometry = QRectF(-1, -1, -1, -1)); Remove Geometry? not possible anymore
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"
* void addApplet(Applet *applet, const QPointF &pos = QPointF(-1, -1)); Remove pos? (not possible anymore)
as
* void setScreen(int screen, int desktop = -1); Drop desktop? (that means dropping the per-virtual desktop views feature, it can be "emulated" with activities and would make things dramatically simpler)
! Status
* int desktop() const;
! Action
* int lastDesktop() const;
! Method
* void showContextMenu(const QPointF &containmentPos, const QPoint &screenPos);
 
* virtual void showDropZone(const QPoint pos);
{{FeatureDone|Keep|explicit Containment(QObject *parent , const QString &serviceId , uint containmentId );}}
* void contextMenuEvent(QContextMenuEvent *event);
{{FeatureDone|Keep|Containment(QObject *parent, const QVariantList &args);}}
* void keyPressEvent(QKeyEvent *event);
{{FeatureDone|Keep|~Containment();}}
* void wheelEvent(QWheelEvent *event);
 
|}
 
= Bookkeeping =
 
{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"
as
! Status
! Action
! Method
 
{{FeatureDone|Rename| Applet *addApplet(const QString &name, const QVariantList args,  const QRectF geometry ; -> becomes createApplet, args and geometry arguments go away}}
{{FeatureDone | Paramenters| void addApplet(Applet *applet, const QPointF pos);  -> pos parameter goes }}
{{FeatureDone | Keep| QList<Applet *> applets() const; }}
{{FeatureDone | Remove| void clearApplets(); }}
{{FeatureDone | Paramenters| void setScreen(int screen, int desktop); -> remove desktop }}
{{FeatureDone | Keep| int screen() const; }}
{{FeatureDone | Remove| int lastScreen() const; }}
{{FeatureDone | Remove|  int desktop() const; }}
{{FeatureDone | Remove|  int lastDesktop() const; }}
{{FeatureDone | Remove| void addAssociatedWidget(QWidget *widget); }}
{{FeatureDone | Remove|  void removeAssociatedWidget(QWidget *widget); }}
{{FeatureTodo | Remove|  bool drawWallpaper(); (to be decided)}}
{{FeatureTodo | Remove|  slot void setDrawWallpaper(bool drawWallpaper); (to be decided)}}
{{FeatureDone | Keep|  signal void wallpaperChanged();}}
{{FeatureDone | Keep|  void setWallpaper(const QString &pluginName); }}
{{FeatureDone | Keep|  QString wallpaper() const; }}
{{FeatureDone | Keep|  void setActivity(const QString &activityId); }}
{{FeatureDone | Keep|  QString activity() const; }}
{{FeatureDone | Paramenters| signal void appletAdded(Plasma::Applet *applet, const QPointF &pos); Remove pos}}
{{FeatureDone | Keep|  signal void appletRemoved(Plasma::Applet *applet);}}
{{FeatureDone| Paramenters| void screenChanged(int wasScreen, int isScreen, Plasma::Containment *containment); -> remove containment parameter. From the usage in Corona seems that the containment parameter may make sense (can be converted to use sender() but seems uglier)}}
{{FeatureDone | Keep|  void configureRequested(Plasma::Containment *containment); -> not completely sure }}
{{FeatureDone | Keep|  slot void setLocation(Plasma::Location location);}}
{{FeatureDone | Keep|  slot void setFormFactor(Plasma::FormFactor formFactor);}}
{{FeatureDone | Remove|  slot void destroy();}}
{{FeatureDone | Remove|  slot void destroy(bool confirm);}}
{{FeatureDone | Keep| slot void setContainmentType(Containment::Type type);}}
|}
 
= Actions =
 
{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"
as
! Status
! Action
! Method
 
{{FeatureDone|Keep| void enableAction(const QString &name, bool enable); }}
{{FeatureDone|Remove| void addToolBoxAction(QAction *action); }}
{{FeatureDone|Remove| void removeToolBoxAction(QAction *action); }}
 
|}
 
=Containment Actions=
 
{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"
as
! Status
! Action
! Method
 
{{FeatureDone | Rename |  void setContainmentActions(const QString &trigger, const QString &pluginName); -> Rename to addContainmentActions }}
{{FeatureDone | Remove | QString containmentActions(const QString &trigger); }}
{{FeatureDone | Remove | QStringList containmentActionsTriggers();}}
{{FeatureDone | Add |  QHash<QString, ContainmentsActions *> containmentActions() const; }}
{{FeatureDone | Remove | KConfigGroup containmentActionsConfig(); Remove after adding ContainmentActions::config() -> problem is that this config group has to exist before ContainmentActions * itself}}
 
|}
 
= Plugin loading =
 
{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"
as
! Status
! Action
! Method
 
{{FeatureDone | PluginLoader|  static KPluginInfo::List listContainments(const QString &category, const QString &parentApp); }}
{{FeatureDone | PluginLoader|  static KPluginInfo::List listContainmentsOfType(const QString &type, const QString &category , const QString &parentApp ); }}
{{FeatureDone | PluginLoader| static QStringList listContainmentTypes(); }}
{{FeatureDone | PluginLoader| static KPluginInfo::List listContainmentsForMimeType(const QString &mimeType); }}
 
|}
 
= Configuration =
 
{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"
 
! Status
! Action
! Method
 
{{FeatureDone | Keep|  void save(KConfigGroup &group) const; }}
{{FeatureDone | Keep|  void restore(KConfigGroup &group); }}
{{FeatureDone | Keep|  protected virtual void saveContents(KConfigGroup &group) const; }}
{{FeatureDone | Keep|  protected virtual void restoreContents(KConfigGroup &group); }}
{{FeatureDone | Move| slot void showConfigurationInterface(); -> into scriptengine}}
|}
 
= UI specific stuff =
 
UI specific things don't belong to this library
 
{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
|- style="background: rgb(236, 236, 236) none repeat scroll 0% 0%; -moz-background-clip: border; -moz-background-origin: padding; -moz-background-inline-policy: continuous; white-space: nowrap;"
as
! Status
! Action
! Method


=== In PluginLoader? ===
{{FeatureDone|Remove| void showContextMenu(const QPointF &containmentPos, const QPoint &screenPos);}}
* static KPluginInfo::List listContainments(const QString &category = QString(), const QString &parentApp = QString());
{{FeatureDone|Remove| virtual void showDropZone(const QPoint pos);}}
* static KPluginInfo::List listContainmentsOfType(const QString &type,  const QString &category = QString(),  const QString &parentApp = QString());
{{FeatureDone|Remove| void contextMenuEvent(QContextMenuEvent *event);}}
* static QStringList listContainmentTypes();
{{FeatureDone|Remove| void wheelEvent(QWheelEvent *event);}}
* static KPluginInfo::List listContainmentsForMimeType(const QString &mimeType);
{{FeatureDone|Remove| signal void toolBoxToggled();}}
{{FeatureDone|Remove| signal void toolBoxVisibilityChanged(bool);}}


= Signals =
|}
* void toolBoxToggled();
* void toolBoxVisibilityChanged(bool);
* void showAddWidgetsInterface(const QPointF &pos); (cannot have a position, maybe not needed at all)

Latest revision as of 14:37, 22 January 2014

Q_PROPERTIES

All qproperties and invokables must go

Enums

Type probably goes in plasma.h

       enum Type {
           NoContainmentType = -1,  /**< @internal */
           DesktopContainment = 0,  /**< A desktop containment */ New name -> suggestions [ Canvas ]
           PanelContainment,        /**< A desktop panel */
           CustomContainment = 127, /**< A containment that is neither a desktop nor a panel
                                       but something application specific */
          CustomPanelContainment = 128 /**< A customized desktop panel */
       };

ToolType goes in plasma.h it becomes ActionType (not related to toolbox anymore)

       enum ToolType {
           AddTool = 0,
           ConfigureTool = 100,
           ControlTool = 200,
           MiscTool = 300,
           DestructiveTool = 400,
           UserToolType = DestructiveTool + 1000
       };
       Q_ENUMS(ToolType)
Status Action Enum
DONE Move Type -> move to Plasma::ContainmenType
DONE Move ToolType -> move to Plasma::ActionType


Constructors

as
Status Action Method
DONE Keep explicit Containment(QObject *parent , const QString &serviceId , uint containmentId );
DONE Keep Containment(QObject *parent, const QVariantList &args);
DONE Keep ~Containment();


Bookkeeping

as
Status Action Method
DONE Rename Applet *addApplet(const QString &name, const QVariantList args, const QRectF geometry ; -> becomes createApplet, args and geometry arguments go away
DONE Paramenters void addApplet(Applet *applet, const QPointF pos); -> pos parameter goes
DONE Keep QList<Applet *> applets() const;
DONE Remove void clearApplets();
DONE Paramenters void setScreen(int screen, int desktop); -> remove desktop
DONE Keep int screen() const;
DONE Remove int lastScreen() const;
DONE Remove int desktop() const;
DONE Remove int lastDesktop() const;
DONE Remove void addAssociatedWidget(QWidget *widget);
DONE Remove  void removeAssociatedWidget(QWidget *widget);
TO DO Remove  bool drawWallpaper(); (to be decided) <{{{3}}}>
TO DO Remove  slot void setDrawWallpaper(bool drawWallpaper); (to be decided) <{{{3}}}>
DONE Keep  signal void wallpaperChanged();
DONE Keep  void setWallpaper(const QString &pluginName);
DONE Keep  QString wallpaper() const;
DONE Keep  void setActivity(const QString &activityId);
DONE Keep  QString activity() const;
DONE Paramenters signal void appletAdded(Plasma::Applet *applet, const QPointF &pos); Remove pos
DONE Keep  signal void appletRemoved(Plasma::Applet *applet);
DONE Paramenters void screenChanged(int wasScreen, int isScreen, Plasma::Containment *containment); -> remove containment parameter. From the usage in Corona seems that the containment parameter may make sense (can be converted to use sender() but seems uglier)
DONE Keep  void configureRequested(Plasma::Containment *containment); -> not completely sure
DONE Keep  slot void setLocation(Plasma::Location location);
DONE Keep  slot void setFormFactor(Plasma::FormFactor formFactor);
DONE Remove  slot void destroy();
DONE Remove  slot void destroy(bool confirm);
DONE Keep slot void setContainmentType(Containment::Type type);

Actions

as
Status Action Method
DONE Keep void enableAction(const QString &name, bool enable);
DONE Remove void addToolBoxAction(QAction *action);
DONE Remove void removeToolBoxAction(QAction *action);


Containment Actions

as
Status Action Method
DONE Rename void setContainmentActions(const QString &trigger, const QString &pluginName); -> Rename to addContainmentActions
DONE Remove QString containmentActions(const QString &trigger);
DONE Remove QStringList containmentActionsTriggers();
DONE Add QHash<QString, ContainmentsActions *> containmentActions() const;
DONE Remove KConfigGroup containmentActionsConfig(); Remove after adding ContainmentActions::config() -> problem is that this config group has to exist before ContainmentActions * itself


Plugin loading

as
Status Action Method
DONE PluginLoader static KPluginInfo::List listContainments(const QString &category, const QString &parentApp);
DONE PluginLoader static KPluginInfo::List listContainmentsOfType(const QString &type, const QString &category , const QString &parentApp );
DONE PluginLoader static QStringList listContainmentTypes();
DONE PluginLoader static KPluginInfo::List listContainmentsForMimeType(const QString &mimeType);


Configuration

Status Action Method
DONE Keep void save(KConfigGroup &group) const;
DONE Keep void restore(KConfigGroup &group);
DONE Keep protected virtual void saveContents(KConfigGroup &group) const;
DONE Keep protected virtual void restoreContents(KConfigGroup &group);
DONE Move slot void showConfigurationInterface(); -> into scriptengine

UI specific stuff

UI specific things don't belong to this library

as
Status Action Method
DONE Remove void showContextMenu(const QPointF &containmentPos, const QPoint &screenPos);
DONE Remove virtual void showDropZone(const QPoint pos);
DONE Remove void contextMenuEvent(QContextMenuEvent *event);
DONE Remove void wheelEvent(QWheelEvent *event);
DONE Remove signal void toolBoxToggled();
DONE Remove signal void toolBoxVisibilityChanged(bool);