Plasma

dataenginescript.h
1 /*
2  SPDX-FileCopyrightText: 2007 Aaron Seigo <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.0-or-later
5 */
6 
7 #ifndef PLASMA_DATAENGINESCRIPT_H
8 #define PLASMA_DATAENGINESCRIPT_H
9 
10 #include <plasma/plasma_export.h>
11 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 94)
12 #include <KPluginInfo>
13 #endif
14 
15 #include <plasma/dataengine.h>
16 #include <plasma/scripting/scriptengine.h>
17 
18 namespace Plasma
19 {
20 class DataEngineScriptPrivate;
21 class Service;
22 
23 /**
24  * @class DataEngineScript plasma/scripting/dataenginescript.h <Plasma/Scripting/DataEngineScript>
25  *
26  * @short Provides a restricted interface for scripting a DataEngine
27  */
28 class PLASMA_EXPORT DataEngineScript : public ScriptEngine
29 {
30  Q_OBJECT
31 
32 public:
33  /**
34  * Default constructor for a DataEngineScript.
35  * Subclasses should not attempt to access the Plasma::DataEngine
36  * associated with this DataEngineScript in the constructor. All
37  * such set up that requires the DataEngine itself should be done
38  * in the init() method.
39  */
40  explicit DataEngineScript(QObject *parent = nullptr);
41  ~DataEngineScript() override;
42 
43  /**
44  * Sets the Plasma::DataEngine associated with this DataEngineScript
45  */
46  void setDataEngine(DataEngine *dataEngine);
47 
48  /**
49  * Returns the Plasma::DataEngine associated with this script component
50  */
51  DataEngine *dataEngine() const;
52 
53  /**
54  * @return a list of all the data sources available via this DataEngine
55  * Whether these sources are currently available (which is what
56  * the default implementation provides) or not is up to the
57  * DataEngine to decide. By default, this returns dataEngine()->sources()
58  */
59  virtual QStringList sources() const;
60 
61  /**
62  * Called when the script should create a source that does not currently
63  * exist.
64  *
65  * @param name the name of the source that should be created
66  * @return true if a DataContainer was set up, false otherwise
67  */
68  virtual bool sourceRequestEvent(const QString &name);
69 
70  /**
71  * Called when the script should refresh the data contained in a given
72  * source.
73  *
74  * @param source the name of the source that should be updated
75  * @return true if the data was changed, or false if there was no
76  * change or if the change will occur later
77  **/
78  virtual bool updateSourceEvent(const QString &source);
79 
80  /**
81  * @param source the source to targe the Service at
82  * @return a Service that has the source as a destination. The service
83  * is parented to the DataEngine, but may be deleted by the
84  * caller when finished with it
85  */
86  virtual Service *serviceForSource(const QString &source);
87 
88 protected:
89 #if PLASMA_BUILD_DEPRECATED_SINCE(5, 83)
90  /**
91  * @return absolute path to the main script file for this plasmoid
92  */
93  QString mainScript() const override;
94 
95  /**
96  * @return the Package associated with this plasmoid which can
97  * be used to request resources, such as images and
98  * interface files.
99  */
100  PLASMA_DEPRECATED_VERSION(5, 83, "Use kpackage API instead")
101  Package package() const override;
102 #endif
103 
104 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 67)
105  /**
106  * @return the KPluginInfo associated with this dataengine
107  *
108  * @deprecated since 5.67 use metadata()
109  */
110  PLASMA_DEPRECATED_VERSION(5, 67, "Use KPluginMetaData metadata()")
111  KPluginInfo description() const;
112 #endif
113 
114  /**
115  * @return the KPluginMetaData associated with this dataengine
116  *
117  * @since 5.67
118  */
119  KPluginMetaData metadata() const;
120 
121  void setData(const QString &source, const QString &key, const QVariant &value);
122  void setData(const QString &source, const QVariant &value);
123 
124  /**
125  * Adds a set of values to a source
126  * @param source the name of the source to set the data on
127  * @values a key/value collection to add to the source
128  * @since 4.5
129  */
130  void setData(const QString &source, const DataEngine::Data &values);
131 
132  void removeAllData(const QString &source);
133  void removeData(const QString &source, const QString &key);
134  void setMinimumPollingInterval(int minimumMs);
135  int minimumPollingInterval() const;
136  void setPollingInterval(uint frequency);
137  void removeAllSources();
138  void addSource(DataContainer *source);
139  DataEngine::SourceDict containerDict() const;
140  void removeSource(const QString &source);
141  void updateAllSources();
142  void forceImmediateUpdateOfAllVisualizations();
143 
144 private:
145  DataEngineScriptPrivate *const d;
146 };
147 
148 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 88)
149 /// @deprecated Since 5.88, use K_PLUGIN_CLASS_WITH_JSON instead
150 #define K_EXPORT_PLASMA_DATAENGINESCRIPTENGINE(libname, classname) K_PLUGIN_FACTORY(factory, registerPlugin<classname>();)
151 
152 /// @deprecated Since 5.88, use K_PLUGIN_CLASS_WITH_JSON instead
153 #define K_EXPORT_PLASMA_DATAENGINESCRIPTENGINE_WITH_JSON(libname, classname, jsonFile) \
154  K_PLUGIN_FACTORY_WITH_JSON(factory, jsonFile, registerPlugin<classname>();)
155 #endif
156 } // Plasma namespace
157 
158 #endif
Provides a restricted interface for scripting a DataEngine.
Data provider for plasmoids (Plasma plugins)
Definition: dataengine.h:50
Namespace for everything in libplasma.
Definition: datamodel.cpp:14
The base class for scripting interfaces to be used in loading plasmoids of a given language.
Definition: scriptengine.h:37
This class provides a generic API for write access to settings or services.
Definition: service.h:77
A set of data exported via a DataEngine.
Definition: datacontainer.h:51
object representing an installed Plasma package
Definition: package.h:76
QVector< V > values(const QMultiHash< K, V > &c)
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Feb 5 2023 04:14:15 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.