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

From KDE Community Wiki
No edit summary
 
(13 intermediate revisions by one other user not shown)
Line 1: Line 1:
=API=
{| cellspacing="0" cellpadding="5" border="1" style="border: 1px solid gray; border-collapse: collapse; text-align: left; width: 100%;" class="sortable"
{| 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;"
|- 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;"
Line 6: Line 7:
! Method  
! Method  


{{FeatureTodo|Remove| explicit DataEngine(QObject *parent , KService::Ptr service);}}
{{FeatureDone|Remove| explicit DataEngine(QObject *parent , KService::Ptr service);}}
{{FeatureTodo|Add|explicit DataEngine(QObject *parent, const KPluginInfo &info);}}
{{FeatureDone|Add|explicit DataEngine(QObject *parent, const KPluginInfo &info);}}
{{FeatureTodo|Remove| DataEngine(QObject *parent, const QVariantList &args);}}
{{FeatureDone|Remove| DataEngine(QObject *parent, const QVariantList &args);}}
{{FeatureDone|Keep|~DataEngine();}}
{{FeatureDone|Keep|~DataEngine();}}
{{FeatureTodo|Remove?|virtual void init(); can be removed is there will be only one constructor}}
{{FeatureDone|Remove?|virtual void init(); can be removed is there will be only one constructor}}
{{FeatureDone|Keep| virtual QStringList sources() const;}}
{{FeatureDone|Keep| virtual QStringList sources() const;}}
{{FeatureDone|Keep| virtual Service *serviceForSource(const QString &source);}}
{{FeatureDone|Keep| virtual Service *serviceForSource(const QString &source);}}
{{FeatureTodo|Add|KPluginInfo pluginInfo() const;}}
{{FeatureDone|Add|KPluginInfo pluginInfo() const;}}
{{FeatureTodo|Remove|QString name() const;}}
{{FeatureDone|Remove|QString name() const;}}
{{FeatureTodo|Remove|QString icon() const;}}
{{FeatureDone|Remove|QString icon() const;}}
{{FeatureTodo|Remove|QString pluginName() const;}}
{{FeatureDone|Remove|QString pluginName() const;}}
{{FeatureDone|Keep| void connectSource(const QString &source, QObject *visualization, uint pollingInterval, Plasma::IntervalAlignment intervalAlignment ) const;}}
{{FeatureDone|Keep| void connectSource(const QString &source, QObject *visualization, uint pollingInterval, Plasma::IntervalAlignment intervalAlignment ) const;}}
{{FeatureDone|Keep| void connectAllSources(QObject *visualization, uint pollingInterval, Plasma::IntervalAlignment intervalAlignment) const;}}
{{FeatureDone|Keep| void connectAllSources(QObject *visualization, uint pollingInterval, Plasma::IntervalAlignment intervalAlignment) const;}}
{{FeatureDone|Keep| void disconnectSource(const QString &source, QObject *visualization) const;}}
{{FeatureDone|Keep| void disconnectSource(const QString &source, QObject *visualization) const;}}
{{FeatureDone|Keep| DataContainer *containerForSource(const QString &source);}}
{{FeatureDone|Keep| DataContainer *containerForSource(const QString &source);}}
{{FeatureTodo|Remove| DataEngine::Data query(const QString &source) const;}}
{{FeatureDone|Remove| DataEngine::Data query(const QString &source) const;}}
{{FeatureDone|Keep|  bool isValid() const;}}
{{FeatureDone|Keep|  bool isValid() const;}}
{{FeatureDone|Keep|  bool isEmpty() const;}}
{{FeatureDone|Keep|  bool isEmpty() const;}}
{{FeatureDone|Keep|  Package package() const;}}
{{FeatureDone|Keep| Package package() const;}}
{{FeatureTodo|Remove|  Service* createDefaultService(QObject *parent = 0);}}
{{FeatureDone|Remove| Service* createDefaultService(QObject *parent );}}
{{FeatureTodo|Move|  static QStringList listAllEngines(const QString &parentApp); -> in PluginLoader}}
{{FeatureDone|Move| static QStringList listAllEngines(const QString &parentApp); -> in PluginLoader}}
{{FeatureTodo|Move|  static KPluginInfo::List listEngineInfo(const QString &parentApp); -> in PluginLoader}}
{{FeatureDone|Move| static KPluginInfo::List listEngineInfo(const QString &parentApp); -> in PluginLoader}}
{{FeatureTodo|Move| static KPluginInfo::List listEngineInfoByCategory(const QString &category, const QString &parentApp);}}
{{FeatureDone|Move| static KPluginInfo::List listEngineInfoByCategory(const QString &category, const QString &parentApp);}}
{{FeatureDone|Keep|  void sourceAdded(const QString &source);}}
{{FeatureDone|Keep|  void sourceRemoved(const QString &source);}}
{{FeatureDone|Keep| virtual bool sourceRequestEvent(const QString &source);}}
{{FeatureDone|Keep| virtual bool updateSourceEvent(const QString &source);}}
{{FeatureDone|Keep|  void setData(const QString &source, const QVariant &value);}}
{{FeatureDone|Keep|  void setData(const QString &source, const QString &key, const QVariant &value);}}
{{FeatureDone|Signature|  void setData(const QString &source, const Data ->QHash<QString, QVariant> &data); -> Data becomes QHash<QString, QVariant> }}
{{FeatureDone|Keep|  void removeAllData(const QString &source);}}
{{FeatureDone|Keep|  void removeData(const QString &source, const QString &key);}}
{{FeatureDone|Keep|  void addSource(DataContainer *source);}}
{{FeatureDone|Keep|  void setMinimumPollingInterval(int minimumMs);}}
{{FeatureDone|Keep|  int minimumPollingInterval() const;}}
{{FeatureDone|Keep|  void setPollingInterval(uint frequency);}}
{{FeatureDone|Keep|  void removeAllSources();}}
{{FeatureDone|Keep|  void setValid(bool valid);}}
{{FeatureDone|Signature|  SourceDict -> QHash<QString, DataContainer*> containerDict() const;}}
{{FeatureDone|Keep| void timerEvent(QTimerEvent *event);}}
{{FeatureDone|Remove| void setName(const QString &name);}}
{{FeatureDone|Remove| void setIcon(const QString &icon);}}
{{FeatureDone|Remove| void setDefaultService(const QString &serviceName);}}
{{FeatureDone|Keep| void setStorageEnabled(const QString &source, bool store);}}
{{FeatureDone|Move| slot void scheduleSourcesUpdated(); -> to private class}}
{{FeatureDone|Keep| slot void removeSource(const QString &source);}}
{{FeatureDone|Keep| slot  void updateAllSources();}}
{{FeatureDone|Keep| slot  void forceImmediateUpdateOfAllVisualizations();}}
 
|}
 
=DataEngine functionality currently:=
    * Timed updates
    * Ease of item creation and update
    * Item destruction when not used
    * Service integration
 
=DataEngine functionality missing:=
    * Introspection / self-documenting structures
    * Ability to represent as model internally
 
=Open Questions=
These questions have come up during review-review, and should be clarified to users of our API:
    * When to write a DataEngine, when to use an import? (In a world, where we have import security)
    * Add possibility to expose QObject*s in the API, much like QAIM*s
    * Why have QVariant(Map,Hash) *and* models, why not deprecate one?
    * Should we deprecate the QVariant*, now we have models?
 
=QML Access=
    * Can haz a model?
 
DataEngine {
public:
QAbstractItemModel *model() const;
}
 
DataSource {
engine: “keystate”
sources: “*Button”
fields: {“Pressed”}
}
 
 
=Example of source types of twitter engine=
Twitter tweets posting
identi.ca 1 dents posting
identi.ca 2 dents posting
avatars model { name : picture }
 
TwitterModel *model = new TwitterModel(“twitter account foo”);
setData(“twitter account foo”, model);
 
bool pressedState = false;
setData(“key”, “pressed”, pressedState);
 
DataContainer -> model, or contains a model …
 
=What do we want?=
 
* lifecycle management
* ondemand creation
* keep existing API (setData, service-related stuff)
* make it easy to use “3rd party models” (e.g. some akonadi model)




|}
=Current dataengines=
* akonadi                              - Akonadi PIM data engine
* applicationjobs                    - Application job updates (via kuiserver)                                                                                                                                                             
* apps                                  - Information and launching of all applications in * the app menu.                                                                                                                                     
* calendar                              - Calendar data engine                                                                                                                                                                               
* comic                                - Online comic strips                                                                                                                                                                                 
* devicenotifications                  - Passive device notifications for the user.                                                                                                                                                         
* dict                                  - Look up word meanings                                                                                                                                                                               
* executable                            - Run Executable Data Engine                                                                                                                                                                         
* favicons                              - Data Engine for getting favicons of web sites                                                                                                                                                       
* filebrowser                          - Information about files and directories.                                                                                                                                                           
* geolocation                          - Geolocation Data Engine                                                                                                                                                                             
* hotplug                              - Tracks hot-pluggable devices as they appear and disappear.                                                                                                                                         
* kdeobservatory                        - A Data Engine for acquiring consolidated data about KDE projects                                                                                                                                   
* keystate                              - Keyboard modifier and mouse buttons states                                                                                                                                                         
* kget                                  - No description available                                                                                                                                                                           
* kimpanel                              - DataEngine for Kimpanel                                                                                                                                                                             
* kremotecontrol                        - Data engine for kremotecontrol                                                                                                                                                                     
* ktorrent                              - KTorrent data engine, for getting information from KTorrent                                                                                                                                         
* metadata                              - No description available                                                                                                                                                                           
* microblog                            - identi.ca and twitter micro-blogging services                                                                                                                                                       
* mixer                                - No description available                                                                                                                                                                           
* mouse                                - Mouse position and cursor                                                                                                                                                                           
* mpris2                                - Provides information from and control over media players via MPRIS2                                                                                                                                 
* network                              - Network interface information                                                                                                                                                                       
* networkmanagement                    - Network Manager data engine                                                                                                                                                                         
* notifications                        - Passive visual notifications for the user.                                                                                                                                                         
* nowplaying                            - Lists currently playing music                                                                                                                                                                       
* obsdataengine                        - DataEngine to make API Calls to the Open Build Service
* ocs                                  - No description available
* openstreetmap                        - The OpenStreetMap data engine can be used to query things near the user.
* org.kde.active.apps                  - Information and launching of all applications in the app menu.
* org.kde.active.bookmarks              - Bookmarks from Nepomuk
* org.kde.active.capabilities          - Provides information and services for device-specific aspects
* org.kde.active.customsearch          - Provides metadata for custom searches in semantic resources
* org.kde.active.metadata              - Provides metadata for semantic resources
* org.kde.active.persons                - Provides metadata for custom searches in semantic resources
* org.kde.activities                    - Information on Plasma Activities
* org.kde.alarms                        - List and set Akonadi Alarms
* org.kde.devicecapabilities            - Provides information and services for device-specific aspects
* org.kde.examples.customDataContainers - A demonstration of how to subclass DataContainer
* org.kde.examples.simpleEngine        - A very basic DataEngine implementation
* org.kde.examples.sourcesOnRequest    - A DataEngine example showing how to respond to requests for source creation and updates
* org.kde.konqprofiles                  - List and launch Konqueror profiles
* org.kde.konsoleprofiles              - List and launch Konsole profiles
* org.kde.mobilenetworkengine          - Mobile network engine
* org.kde.mobileprofileengine          - No description available
* org.kde.plasma.dataengine.share      - Engine to share content using different services
* org.kde.preview                      - Shows previews for webpages
* org.kde.printers                      - No description available
* org.kde.printjobs                    - No description available
* org.kde.runner                        - Query KRunner and execute the results
* org.kde.sharelikeconnect              - Provider of actions for sharing resources
* parley                                - Vocabulary data for Plasmoids
* places                                - Places, as seen in the file manager and in file dialogs.
* potd                                  - Data Engine for getting various online Pictures of The Day.
* powermanagement                      - Battery, AC, sleep and PowerDevil information.
* publictransport                      - Plasma data engine for public transport
* rss                                  - RSS News Data Engine
* rtm                                  - An engine to work with Remember the Milk.
* searchlaunch                          - Engine to handle queries to SAL containment
* soliddevice                          - Device data via Solid
* statusnotifieritem                    - Engine for applications' status information, based on the Status Notifier protocol.
* systemmonitor                        - System status information
* tasks                                - Information and management services for all available windows.
* time                                  - Date and time by timezone
* weather                              - Weather data from multiple online sources
* workareas                            - Workareas Data Engine, as described in the WorkFlow Project

Latest revision as of 14:15, 6 May 2013

API

Status Action Method
DONE Remove explicit DataEngine(QObject *parent , KService::Ptr service);
DONE Add explicit DataEngine(QObject *parent, const KPluginInfo &info);
DONE Remove DataEngine(QObject *parent, const QVariantList &args);
DONE Keep ~DataEngine();
DONE Remove? virtual void init(); can be removed is there will be only one constructor
DONE Keep virtual QStringList sources() const;
DONE Keep virtual Service *serviceForSource(const QString &source);
DONE Add KPluginInfo pluginInfo() const;
DONE Remove QString name() const;
DONE Remove QString icon() const;
DONE Remove QString pluginName() const;
DONE Keep void connectSource(const QString &source, QObject *visualization, uint pollingInterval, Plasma::IntervalAlignment intervalAlignment ) const;
DONE Keep void connectAllSources(QObject *visualization, uint pollingInterval, Plasma::IntervalAlignment intervalAlignment) const;
DONE Keep void disconnectSource(const QString &source, QObject *visualization) const;
DONE Keep DataContainer *containerForSource(const QString &source);
DONE Remove DataEngine::Data query(const QString &source) const;
DONE Keep bool isValid() const;
DONE Keep bool isEmpty() const;
DONE Keep Package package() const;
DONE Remove Service* createDefaultService(QObject *parent );
DONE Move static QStringList listAllEngines(const QString &parentApp); -> in PluginLoader
DONE Move static KPluginInfo::List listEngineInfo(const QString &parentApp); -> in PluginLoader
DONE Move static KPluginInfo::List listEngineInfoByCategory(const QString &category, const QString &parentApp);
DONE Keep void sourceAdded(const QString &source);
DONE Keep void sourceRemoved(const QString &source);
DONE Keep virtual bool sourceRequestEvent(const QString &source);
DONE Keep virtual bool updateSourceEvent(const QString &source);
DONE Keep void setData(const QString &source, const QVariant &value);
DONE Keep void setData(const QString &source, const QString &key, const QVariant &value);
DONE Signature void setData(const QString &source, const Data ->QHash<QString, QVariant> &data); -> Data becomes QHash<QString, QVariant>
DONE Keep void removeAllData(const QString &source);
DONE Keep void removeData(const QString &source, const QString &key);
DONE Keep void addSource(DataContainer *source);
DONE Keep void setMinimumPollingInterval(int minimumMs);
DONE Keep int minimumPollingInterval() const;
DONE Keep void setPollingInterval(uint frequency);
DONE Keep void removeAllSources();
DONE Keep void setValid(bool valid);
DONE Signature SourceDict -> QHash<QString, DataContainer*> containerDict() const;
DONE Keep void timerEvent(QTimerEvent *event);
DONE Remove void setName(const QString &name);
DONE Remove void setIcon(const QString &icon);
DONE Remove void setDefaultService(const QString &serviceName);
DONE Keep void setStorageEnabled(const QString &source, bool store);
DONE Move slot void scheduleSourcesUpdated(); -> to private class
DONE Keep slot void removeSource(const QString &source);
DONE Keep slot void updateAllSources();
DONE Keep slot void forceImmediateUpdateOfAllVisualizations();


DataEngine functionality currently:

   * Timed updates
   * Ease of item creation and update
   * Item destruction when not used
   * Service integration

DataEngine functionality missing:

   * Introspection / self-documenting structures
   * Ability to represent as model internally

Open Questions

These questions have come up during review-review, and should be clarified to users of our API:

   * When to write a DataEngine, when to use an import? (In a world, where we have import security)
   * Add possibility to expose QObject*s in the API, much like QAIM*s
   * Why have QVariant(Map,Hash) *and* models, why not deprecate one?
   * Should we deprecate the QVariant*, now we have models?

QML Access

   * Can haz a model?
DataEngine {
public:
	QAbstractItemModel *model() const;
}
DataSource {
	engine: “keystate”
	sources: “*Button”
	fields: {“Pressed”}
}


Example of source types of twitter engine

Twitter			tweets		posting
identi.ca 1		dents		posting
identi.ca 2 		dents		posting
avatars		model { name : picture }

TwitterModel *model = new TwitterModel(“twitter account foo”); setData(“twitter account foo”, model);

bool pressedState = false; setData(“key”, “pressed”, pressedState);

DataContainer -> model, or contains a model …

What do we want?

  • lifecycle management
  • ondemand creation
  • keep existing API (setData, service-related stuff)
  • make it easy to use “3rd party models” (e.g. some akonadi model)


Current dataengines

  • akonadi - Akonadi PIM data engine
  • applicationjobs - Application job updates (via kuiserver)
  • apps - Information and launching of all applications in * the app menu.
  • calendar - Calendar data engine
  • comic - Online comic strips
  • devicenotifications - Passive device notifications for the user.
  • dict - Look up word meanings
  • executable - Run Executable Data Engine
  • favicons - Data Engine for getting favicons of web sites
  • filebrowser - Information about files and directories.
  • geolocation - Geolocation Data Engine
  • hotplug - Tracks hot-pluggable devices as they appear and disappear.
  • kdeobservatory - A Data Engine for acquiring consolidated data about KDE projects
  • keystate - Keyboard modifier and mouse buttons states
  • kget - No description available
  • kimpanel - DataEngine for Kimpanel
  • kremotecontrol - Data engine for kremotecontrol
  • ktorrent - KTorrent data engine, for getting information from KTorrent
  • metadata - No description available
  • microblog - identi.ca and twitter micro-blogging services
  • mixer - No description available
  • mouse - Mouse position and cursor
  • mpris2 - Provides information from and control over media players via MPRIS2
  • network - Network interface information
  • networkmanagement - Network Manager data engine
  • notifications - Passive visual notifications for the user.
  • nowplaying - Lists currently playing music
  • obsdataengine - DataEngine to make API Calls to the Open Build Service
  • ocs - No description available
  • openstreetmap - The OpenStreetMap data engine can be used to query things near the user.
  • org.kde.active.apps - Information and launching of all applications in the app menu.
  • org.kde.active.bookmarks - Bookmarks from Nepomuk
  • org.kde.active.capabilities - Provides information and services for device-specific aspects
  • org.kde.active.customsearch - Provides metadata for custom searches in semantic resources
  • org.kde.active.metadata - Provides metadata for semantic resources
  • org.kde.active.persons - Provides metadata for custom searches in semantic resources
  • org.kde.activities - Information on Plasma Activities
  • org.kde.alarms - List and set Akonadi Alarms
  • org.kde.devicecapabilities - Provides information and services for device-specific aspects
  • org.kde.examples.customDataContainers - A demonstration of how to subclass DataContainer
  • org.kde.examples.simpleEngine - A very basic DataEngine implementation
  • org.kde.examples.sourcesOnRequest - A DataEngine example showing how to respond to requests for source creation and updates
  • org.kde.konqprofiles - List and launch Konqueror profiles
  • org.kde.konsoleprofiles - List and launch Konsole profiles
  • org.kde.mobilenetworkengine - Mobile network engine
  • org.kde.mobileprofileengine - No description available
  • org.kde.plasma.dataengine.share - Engine to share content using different services
  • org.kde.preview - Shows previews for webpages
  • org.kde.printers - No description available
  • org.kde.printjobs - No description available
  • org.kde.runner - Query KRunner and execute the results
  • org.kde.sharelikeconnect - Provider of actions for sharing resources
  • parley - Vocabulary data for Plasmoids
  • places - Places, as seen in the file manager and in file dialogs.
  • potd - Data Engine for getting various online Pictures of The Day.
  • powermanagement - Battery, AC, sleep and PowerDevil information.
  • publictransport - Plasma data engine for public transport
  • rss - RSS News Data Engine
  • rtm - An engine to work with Remember the Milk.
  • searchlaunch - Engine to handle queries to SAL containment
  • soliddevice - Device data via Solid
  • statusnotifieritem - Engine for applications' status information, based on the Status Notifier protocol.
  • systemmonitor - System status information
  • tasks - Information and management services for all available windows.
  • time - Date and time by timezone
  • weather - Weather data from multiple online sources
  • workareas - Workareas Data Engine, as described in the WorkFlow Project