Plasma/libplasma2/API Review/Applet

From KDE Community Wiki

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);
DONE Keep  bool hasFailedToLaunch() const;
TO DO Keep  void setFailedToLaunch(bool failed, const QString &reason); TODO: show why the thing failed in the UI <{{{3}}}>
DONE Keep  bool destroyed() const;
DONE Keep  virtual void destroy();
TO DO Keep Containment *containment() const; NOTE: Containment is NOT an applet anymore <{{{3}}}>
TO DO Not Slot  ItemStatus status() const; → unslotify <{{{3}}}>
DONE Keep  void setStatus(const ItemStatus stat);
TO DO Change name  SIGNAL void newStatus(Plasma::ItemStatus status); TODO: change name to statusChanged <{{{3}}}>
TO DO Not virtual  virtual FormFactor formFactor() const;   -> not virtual <{{{3}}}>
TO DO Not virtual  virtual Location location() const;    -> not virtual <{{{3}}}>


DONE Remove  Plasma::AspectRatioMode aspectRatioMode() const;
DONE Remove   void setAspectRatioMode(Plasma::AspectRatioMode);
TO DO Remove  bool isContainment() const; <{{{3}}}>
TO DO Remove  virtual bool isPopupShowing() const; <{{{3}}}>
TO DO Remove  QVariantList startupArguments() const; TODO: templated config for startup <{{{3}}}>


       

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}}}>
TO DO Remove  DataEngine *dataEngine(const QString &name) const; <{{{3}}}>


Metadata

Status Action Method
TO DO Add  KPluginInfo pluginInfo() const; <{{{3}}}>
TO DO Rename  QString name() const; -> becomes title() <{{{3}}}>
TO DO Rename  void setName(const QString &name) const; ->setTitle() <{{{3}}}>
TO DO Move to PluginLoader  static KPluginInfo::List listAppletInfo(const QString category, const QString parentApp); -> PluginLoader <{{{3}}}>
TO DO Move to PluginLoader  static KPluginInfo::List listAppletInfoForMimeType(const QString &mimetype); <{{{3}}}>
TO DO Move to PluginLoader static KPluginInfo::List listAppletInfoForUrl(const QUrl &url); <{{{3}}}>
TO DO Move to PluginLoader  static QStringList listCategories(const QString &parentApp, bool visibleOnly); <{{{3}}}>
TO DO 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 <{{{3}}}>
TO DO Move to PluginLoader  QStringList customCategories() const; <{{{3}}}>
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}}}>
TO DO Move to PluginLoader  static QString category(const QString &appletName); -> PluginLoader <{{{3}}}>
TO DO Remove  QString icon() const; Maybe there is an use case? <{{{3}}}>
TO DO Remove  QString category() const; <{{{3}}}>
TO DO Remove  QString pluginName() const; <{{{3}}}>
TO DO Remove  static QString category(const KPluginInfo &applet); <{{{3}}}>
TO DO Remove  bool shouldConserveResources() const; <{{{3}}}>

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}}}>
TO DO Remove   bool hasAuthorization(const QString &constraint) const; <{{{3}}}>



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}}}>
TO DO Remove void appletTransformedByUser(); <{{{3}}}>
TO DO Remove void appletTransformedItself(); <{{{3}}}>
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
TO DO Remove void publish(Plasma::AnnouncementMethods methods, const QString &resourceName); <{{{3}}}>
TO DO Remove void unpublish(); <{{{3}}}>
TO DO Remove bool isPublished() const; <{{{3}}}>


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}}}>
TO DO Remove  bool hasFocus() const; <{{{3}}}>
TO DO Remove  void setFocus(Qt::FocusReason); <{{{3}}}>
TO DO Remove  QFont font() const; <{{{3}}}>
TO DO Move  void setBackgroundHints(const Plasma::BackgroundHints hint); <{{{3}}}>
TO DO Move  Plasma::BackgroundHints backgroundHints() const; <{{{3}}}>
TO DO Move   bool isBusy() const; <{{{3}}}>
TO DO Move  void setBusy(bool busy); <{{{3}}}>
TO DO Remove  virtual void addAssociatedWidget(QWidget *widget); <{{{3}}}>
TO DO Remove  virtual void removeAssociatedWidget(QWidget *widget); <{{{3}}}>
TO DO Remove  void messageButtonPressed(const Plasma::MessageButton button); <{{{3}}}>
TO DO Move  void showMessage(const QIcon &icon, const QString &message, const Plasma::MessageButtons buttons); <{{{3}}}>
TO DO Remove  SIGNAL void backgroundHintsChanged(Plasma::BackgroundHints backgroundHints); <{{{3}}}>
TO DO Move  QPoint popupPosition(const QSize &s) const; -> Dialog in bindings <{{{3}}}>
TO DO Move  QPoint popupPosition(const QSize &s, Qt::AlignmentFlag alignment) const; <{{{3}}}>