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

From KDE Community Wiki
 
(20 intermediate revisions by 2 users not shown)
Line 15: Line 15:
{{FeatureDone|Keep| ImmutabilityType immutability() const;}}
{{FeatureDone|Keep| ImmutabilityType immutability() const;}}
{{FeatureDone|Keep| SIGNAL void immutabilityChanged(Plasma::ImmutabilityType immutable);}}
{{FeatureDone|Keep| SIGNAL void immutabilityChanged(Plasma::ImmutabilityType immutable);}}
{{FeatureDone|Keep| bool hasFailedToLaunch() const;}}
{{FeatureInProgress|Keep| bool hasFailedToLaunch() const;}}
{{FeatureTodo|Keep| void setFailedToLaunch(bool failed, const QString &reason); '''TODO''':  show why the thing failed in the UI }}
{{FeatureInProgress|Keep| void setFailedToLaunch(bool failed, const QString &reason); '''TODO''':  show why the thing failed in the UI: '''PROPOSAL''': the applet keeps only the message: setLaunchErrorMessage() }}
{{FeatureDone|Keep| bool destroyed() const;}}
{{FeatureDone|Keep| bool destroyed() const;}}
{{FeatureDone|Keep| virtual void destroy();}}
{{FeatureDone|Keep| virtual void destroy();}}
{{FeatureTodo|Keep| Containment *containment() const; '''NOTE''': Containment is NOT an applet anymore}}
{{FeatureDone|Not Slot| ItemStatus status() const; → unslotify}}
{{FeatureDone|Not Slot| ItemStatus status() const; → unslotify}}
{{FeatureDone|Keep| void setStatus(const ItemStatus stat);}}
{{FeatureDone|Keep| void setStatus(const ItemStatus stat);}}
{{FeatureTodo|Change name| SIGNAL void newStatus(Plasma::ItemStatus status);  '''TODO''': change name to statusChanged}}
{{FeatureDone|Change name| SIGNAL void newStatus(Plasma::ItemStatus status);  '''TODO''': change name to statusChanged}}
{{FeatureDone|Not virtual| virtual FormFactor formFactor() const;   -> not virtual}}
{{FeatureDone|Not virtual| virtual FormFactor formFactor() const;   -> not virtual}}
{{FeatureDone|Not virtual| virtual Location location() const;    -> not virtual}}
{{FeatureDone|Not virtual| virtual Location location() const;    -> not virtual}}
Line 28: Line 27:
{{FeatureDone|Remove| Plasma::AspectRatioMode aspectRatioMode() const;}}
{{FeatureDone|Remove| Plasma::AspectRatioMode aspectRatioMode() const;}}
{{FeatureDone|Remove|  void setAspectRatioMode(Plasma::AspectRatioMode);}}
{{FeatureDone|Remove|  void setAspectRatioMode(Plasma::AspectRatioMode);}}
{{FeatureTodo|Remove| bool isContainment() const;}}
{{FeatureDone|Remove| virtual bool isPopupShowing() const;}}
{{FeatureDone|Remove| virtual bool isPopupShowing() const;}}
{{FeatureTodo|Remove| QVariantList startupArguments() const; '''TODO''': templated config for startup}}
{{FeatureDone|Remove| QVariantList startupArguments() const; '''TODO''': templated config for startup. NOTE: probably QVariantList startupArguments cannot be removed from any plugin based class}}


|}
|}
Line 68: Line 66:
{{FeatureDone|Keep| void flushPendingConstraintsEvents();}}
{{FeatureDone|Keep| void flushPendingConstraintsEvents();}}
{{FeatureTodo|Keep|virtual void constraintsEvent(Plasma::Constraints constraints); '''TODO''' Should this become a signal?}}
{{FeatureTodo|Keep|virtual void constraintsEvent(Plasma::Constraints constraints); '''TODO''' Should this become a signal?}}
{{FeatureTodo|Remove| DataEngine *dataEngine(const QString &name) const;}}
{{FeatureDone|Remove| DataEngine *dataEngine(const QString &name) const;}}


|}
|}
Line 80: Line 78:
! Method  
! Method  


{{FeatureTodo|Add| KPluginInfo pluginInfo() const;}}
{{FeatureDone|Add| KPluginInfo pluginInfo() const;}}
{{FeatureTodo|Rename| QString name() const;  -> becomes title()}}
{{FeatureDone|Rename| QString name() const;  -> becomes title()}}
{{FeatureTodo|Rename| void setName(const QString &name) const; ->setTitle()}}
{{FeatureDone|Rename| void setName(const QString &name) const; ->setTitle()}}
{{FeatureTodo|Move to PluginLoader| static KPluginInfo::List listAppletInfo(const QString category, const QString parentApp);  -> PluginLoader}}
{{FeatureDone|Move to PluginLoader| static KPluginInfo::List listAppletInfo(const QString category, const QString parentApp);  -> PluginLoader}}
{{FeatureTodo|Move to PluginLoader| static KPluginInfo::List listAppletInfoForMimeType(const QString &mimetype);}}
{{FeatureDone|Move to PluginLoader| static KPluginInfo::List listAppletInfoForMimeType(const QString &mimetype);}}
{{FeatureTodo|Move to PluginLoader| static KPluginInfo::List listAppletInfoForUrl(const QUrl &url);}}
{{FeatureDone|Move to PluginLoader| static KPluginInfo::List listAppletInfoForUrl(const QUrl &url);}}
{{FeatureTodo|Move to PluginLoader| static QStringList listCategories(const QString &parentApp, bool visibleOnly);}}
{{FeatureDone|Move to PluginLoader| static QStringList listCategories(const QString &parentApp, bool visibleOnly);}}
{{FeatureTodo|Move to PluginLoader| void setCustomCategories(const QStringList &categories); just categories in PluginLoader? : currently stored in AppletPrivate::s_customCategories perhaps every shell should set what its categories are}}
{{FeatureDone|Move to PluginLoader| void setCustomCategories(const QStringList &categories); just categories in PluginLoader? : currently stored in AppletPrivate::s_customCategories perhaps every shell should set what its categories are}}
{{FeatureTodo|Move to PluginLoader| QStringList customCategories() const;}}
{{FeatureDone|Move to PluginLoader| QStringList customCategories() const;}}
{{FeatureTodo|Move to PluginLoader| static Applet *loadPlasmoid(const QString &path, uint appletId,  const QVariantList &args); -> Merged in PluginLoader::loadApplet: right now pluginloader instantiates only the right Applet*, it should try to load the package as well.}}
{{FeatureTodo|Move to PluginLoader| static Applet *loadPlasmoid(const QString &path, uint appletId,  const QVariantList &args); -> Merged in PluginLoader::loadApplet: right now pluginloader instantiates only the right Applet*, it should try to load the package as well.}}
{{FeatureTodo|Move to PluginLoader| static QString category(const QString &appletName); -> PluginLoader}}
{{FeatureDone|Move to PluginLoader| static QString category(const QString &appletName); -> PluginLoader}}
{{FeatureTodo|Remove| QString icon() const; '''Maybe''' there is an use case?}}
{{FeatureTodo|Remove| QString icon() const; '''Maybe''' there is an use case?}}
{{FeatureTodo|Remove| QString category() const;}}
{{FeatureDone|Remove| QString category() const;}}
{{FeatureTodo|Remove| QString pluginName() const;}}
{{FeatureDone|Remove| QString pluginName() const;}}
{{FeatureTodo|Remove| static QString category(const KPluginInfo &applet); }}
{{FeatureDone|Remove| static QString category(const KPluginInfo &applet); }}
{{FeatureTodo|Remove| bool shouldConserveResources() const;}}
{{FeatureDone|Remove| bool shouldConserveResources() const;}}
|}
|}


Line 113: Line 111:
{{FeatureTodo|Remove| KShortcut globalShortcut() const;}}
{{FeatureTodo|Remove| KShortcut globalShortcut() const;}}
{{FeatureTodo|Remove| void activate();}}
{{FeatureTodo|Remove| void activate();}}
{{FeatureTodo|Remove|  bool hasAuthorization(const QString &constraint) const;}}
{{FeatureDone|Remove|  bool hasAuthorization(const QString &constraint) const;}}


|}
|}


= Constructors =
= Constructors =
Line 156: Line 153:


{{FeatureTodo|Remove|void releaseVisualFocus();}}
{{FeatureTodo|Remove|void releaseVisualFocus();}}
{{FeatureTodo|Remove|void appletTransformedByUser();}}
{{FeatureDone|Remove|void appletTransformedByUser();}}
{{FeatureTodo|Remove|void appletTransformedItself();}}
{{FeatureDone|Remove|void appletTransformedItself();}}
{{FeatureTodo|Remove|void appletDeleted(Plasma::Applet *applet); '''TODO''': fix usage in Containment}}
{{FeatureTodo|Remove|void appletDeleted(Plasma::Applet *applet); '''TODO''': fix usage in Containment}}


Line 193: Line 190:
{{FeatureTodo|Remove| bool isUserConfiguring() const}}
{{FeatureTodo|Remove| bool isUserConfiguring() const}}
{{FeatureTodo|Remove| Private class AppletConfigDialog is part of this}}
{{FeatureTodo|Remove| Private class AppletConfigDialog is part of this}}
{{FeatureTodo|Remove| bool hasFocus() const;}}
{{FeatureDone|Remove| bool hasFocus() const;}}
{{FeatureTodo|Remove| void setFocus(Qt::FocusReason);}}
{{FeatureDone|Remove| void setFocus(Qt::FocusReason);}}
{{FeatureTodo|Remove| QFont font() const;}}
{{FeatureDone|Remove| QFont font() const;}}
{{FeatureTodo|Move| void setBackgroundHints(const Plasma::BackgroundHints hint);}}
{{FeatureDone|Move| void setBackgroundHints(const Plasma::BackgroundHints hint);}}
{{FeatureTodo|Move| Plasma::BackgroundHints backgroundHints() const;}}
{{FeatureDone|Move| Plasma::BackgroundHints backgroundHints() const;}}
{{FeatureTodo|Move|  bool isBusy() const;}}
{{FeatureDone|Move|  bool isBusy() const;}}
{{FeatureTodo|Move| void setBusy(bool busy);}}
{{FeatureDone|Move| void setBusy(bool busy);}}
{{FeatureTodo|Remove| virtual void addAssociatedWidget(QWidget *widget);}}
{{FeatureTodo|Remove| virtual void addAssociatedWidget(QWidget *widget);}}
{{FeatureTodo|Remove| virtual void removeAssociatedWidget(QWidget *widget);}}
{{FeatureTodo|Remove| virtual void removeAssociatedWidget(QWidget *widget);}}
{{FeatureTodo|Remove| void messageButtonPressed(const Plasma::MessageButton button);}}
{{FeatureDone|Remove| void messageButtonPressed(const Plasma::MessageButton button);}}
{{FeatureTodo|Move| void showMessage(const QIcon &icon, const QString &message, const Plasma::MessageButtons buttons);}}
{{FeatureDone|Remove| void showMessage(const QIcon &icon, const QString &message, const Plasma::MessageButtons buttons);}}
{{FeatureTodo|Remove| SIGNAL void backgroundHintsChanged(Plasma::BackgroundHints backgroundHints);}}
{{FeatureDone|Remove| SIGNAL void backgroundHintsChanged(Plasma::BackgroundHints backgroundHints);}}
{{FeatureTodo|Move| QPoint popupPosition(const QSize &s) const; -> Dialog in bindings}}
{{FeatureDone|Move| QPoint popupPosition(const QSize &s) const; -> Dialog in bindings}}
{{FeatureTodo|Move| QPoint popupPosition(const QSize &s, Qt::AlignmentFlag alignment) const;}}
{{FeatureDone|Move| QPoint popupPosition(const QSize &s, Qt::AlignmentFlag alignment) const;}}


|}
|}

Latest revision as of 14:38, 22 January 2014

QProperties

All Q_PROPERTY and Q_INVOKABLE will be removed from Applet, that is no more directly exposed in QML.

Bookkeeping

as
Status Action Method
DONE Keep uint id() const;
DONE Keep  void setImmutability(const ImmutabilityType immutable);
DONE Keep  ImmutabilityType immutability() const;
DONE Keep  SIGNAL void immutabilityChanged(Plasma::ImmutabilityType immutable);
IN PROGRESS Keep  bool hasFailedToLaunch() const;
IN PROGRESS Keep  void setFailedToLaunch(bool failed, const QString &reason); TODO: show why the thing failed in the UI: PROPOSAL: the applet keeps only the message: setLaunchErrorMessage()
DONE Keep  bool destroyed() const;
DONE Keep  virtual void destroy();
DONE Not Slot  ItemStatus status() const; → unslotify
DONE Keep  void setStatus(const ItemStatus stat);
DONE Change name  SIGNAL void newStatus(Plasma::ItemStatus status); TODO: change name to statusChanged
DONE Not virtual  virtual FormFactor formFactor() const;   -> not virtual
DONE Not virtual  virtual Location location() const;    -> not virtual


DONE Remove  Plasma::AspectRatioMode aspectRatioMode() const;
DONE Remove   void setAspectRatioMode(Plasma::AspectRatioMode);
DONE Remove  virtual bool isPopupShowing() const;
DONE Remove  QVariantList startupArguments() const; TODO: templated config for startup. NOTE: probably QVariantList startupArguments cannot be removed from any plugin based class


       

Configuration

We should have a single configuration object binded to qml (either created by autogenerated qml, a model or a property hash)

       KConfigGroup config() const;
       KConfigGroup globalConfig() const;
       ConfigLoader *configScheme() const;

Topic: can this be made flexible enough to replace config read/write? Topic: will need a global version (for globalConfig()) Topic: should we use QML for config, if so: how?

       virtual void save(KConfigGroup &group) const;
       virtual void restore(KConfigGroup &group);
       virtual void configChanged(); -> to signal
       virtual void saveState(KConfigGroup &config) const;
       SIGNAL void configNeedsSaving();
       bool hasConfigurationInterface() const;
       void setHasConfigurationInterface(bool hasInterface);
       void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());
       bool configurationRequired() const;
       virtual void showConfigurationInterface();

Utils

Status Action Method
DONE Keep  Package package() const;
DONE Keep  void updateConstraints(Plasma::Constraints constraints);
DONE Keep  void flushPendingConstraintsEvents();
TO DO Keep virtual void constraintsEvent(Plasma::Constraints constraints); TODO Should this become a signal? <{{{3}}}>
DONE Remove  DataEngine *dataEngine(const QString &name) const;


Metadata

Status Action Method
DONE Add  KPluginInfo pluginInfo() const;
DONE Rename  QString name() const; -> becomes title()
DONE Rename  void setName(const QString &name) const; ->setTitle()
DONE Move to PluginLoader  static KPluginInfo::List listAppletInfo(const QString category, const QString parentApp); -> PluginLoader
DONE Move to PluginLoader  static KPluginInfo::List listAppletInfoForMimeType(const QString &mimetype);
DONE Move to PluginLoader static KPluginInfo::List listAppletInfoForUrl(const QUrl &url);
DONE Move to PluginLoader  static QStringList listCategories(const QString &parentApp, bool visibleOnly);
DONE Move to PluginLoader  void setCustomCategories(const QStringList &categories); just categories in PluginLoader? : currently stored in AppletPrivate::s_customCategories perhaps every shell should set what its categories are
DONE Move to PluginLoader  QStringList customCategories() const;
TO DO Move to PluginLoader  static Applet *loadPlasmoid(const QString &path, uint appletId, const QVariantList &args); -> Merged in PluginLoader::loadApplet: right now pluginloader instantiates only the right Applet*, it should try to load the package as well. <{{{3}}}>
DONE Move to PluginLoader  static QString category(const QString &appletName); -> PluginLoader
TO DO Remove  QString icon() const; Maybe there is an use case? <{{{3}}}>
DONE Remove  QString category() const;
DONE Remove  QString pluginName() const;
DONE Remove  static QString category(const KPluginInfo &applet);
DONE Remove  bool shouldConserveResources() const;

Actions

Status Action Method
DONE Keep virtual QList<QAction*> contextualActions();
DONE Keep  QAction *action(QString name) const
DONE Keep  void addAction(QString name, QAction *action);
TO DO Remove  void setGlobalShortcut(const KShortcut &shortcut); <{{{3}}}>
TO DO Remove  KShortcut globalShortcut() const; <{{{3}}}>
TO DO Remove  void activate(); <{{{3}}}>
DONE Remove   bool hasAuthorization(const QString &constraint) const;


Constructors

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

Merge the following one into above explicit Applet(QObject *parent, const QString &serviceId, uint appletId, const QVariantList &args);

       explicit Applet(const KPluginInfo &info, QObject *parent = 0, uint appletId = 0);
       Applet(QObject *parent, const QVariantList &args);
       virtual void init();

Associated Application

Status Action Method
DONE Keep void setAssociatedApplication(const QString &string);
DONE Keep void setAssociatedApplicationUrls(const QList<QUrl> &urls);
DONE Keep QString associatedApplication() const;
DONE Keep QList<QUrl> associatedApplicationUrls() const;
DONE Keep bool hasValidAssociatedApplication() const;
TO DO Keep void runAssociatedApplication(); TODO: ensure that setAssociatedApplication handles .desktop files <{{{3}}}>


Other SIGNALS

Status Action Method
TO DO Remove void releaseVisualFocus(); <{{{3}}}>
DONE Remove void appletTransformedByUser();
DONE Remove void appletTransformedItself();
TO DO Remove void appletDeleted(Plasma::Applet *applet); TODO: fix usage in Containment <{{{3}}}>


Sharing Widgets

Remote widgets will be completetely removed and eventually reimplemented again later from scratch. TODO: a new and improved revisioned remove widgets (or probably just dataengines and services) system

Status Action Method
DONE Remove void publish(Plasma::AnnouncementMethods methods, const QString &resourceName);
DONE Remove void unpublish();
DONE Remove bool isPublished() const;


To script engine

Completely UI-specific, remove or move to scriptengine

Status Action Method
TO DO Remove  void showConfigurationInterface(QWidget *widget); <{{{3}}}>
TO DO Remove  virtual void createConfigurationInterface(KConfigDialog *parent); <{{{3}}}>
TO DO Remove  bool isUserConfiguring() const <{{{3}}}>
TO DO Remove  Private class AppletConfigDialog is part of this <{{{3}}}>
DONE Remove  bool hasFocus() const;
DONE Remove  void setFocus(Qt::FocusReason);
DONE Remove  QFont font() const;
DONE Move  void setBackgroundHints(const Plasma::BackgroundHints hint);
DONE Move  Plasma::BackgroundHints backgroundHints() const;
DONE Move   bool isBusy() const;
DONE Move  void setBusy(bool busy);
TO DO Remove  virtual void addAssociatedWidget(QWidget *widget); <{{{3}}}>
TO DO Remove  virtual void removeAssociatedWidget(QWidget *widget); <{{{3}}}>
DONE Remove  void messageButtonPressed(const Plasma::MessageButton button);
DONE Remove  void showMessage(const QIcon &icon, const QString &message, const Plasma::MessageButtons buttons);
DONE Remove  SIGNAL void backgroundHintsChanged(Plasma::BackgroundHints backgroundHints);
DONE Move  QPoint popupPosition(const QSize &s) const; -> Dialog in bindings
DONE Move  QPoint popupPosition(const QSize &s, Qt::AlignmentFlag alignment) const;