Plasma

appletscript.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_APPLETSCRIPT_H
8 #define PLASMA_APPLETSCRIPT_H
9 
10 #include <QObject>
11 #include <QRect>
12 #include <QSizeF>
13 
14 #include <plasma/plasma_export.h>
15 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 94)
16 #include <KPluginInfo>
17 #endif
18 
19 #include <plasma/containment.h>
20 #include <plasma/scripting/scriptengine.h>
21 
22 class QAction;
23 class QPainter;
24 
25 namespace Plasma
26 {
27 class AppletScriptPrivate;
28 class Extender;
29 
30 /**
31  * @class AppletScript plasma/scripting/appletscript.h <Plasma/Scripting/AppletScript>
32  *
33  * @short Provides a restricted interface for scripted applets.
34  */
35 class PLASMA_EXPORT AppletScript : public ScriptEngine
36 {
37  Q_OBJECT
38 
39 public:
40  /**
41  * Default constructor for an AppletScript.
42  *
43  * Subclasses should not attempt to access the Plasma::Applet
44  * associated with this AppletScript in the constructor. All
45  * such set up that requires the Applet itself should be done
46  * in the init() method.
47  */
48  explicit AppletScript(QObject *parent = nullptr);
49  ~AppletScript() override;
50 
51  /**
52  * Sets the applet associated with this AppletScript
53  */
54  void setApplet(Plasma::Applet *applet);
55 
56  /**
57  * Returns the Plasma::Applet associated with this script component
58  */
59  Plasma::Applet *applet() const;
60 
61  /**
62  * Called when any of the geometry constraints have been updated.
63  *
64  * This is always called prior to painting and should be used as an
65  * opportunity to layout the widget, calculate sizings, etc.
66  *
67  * Do not call update() from this method; an update() will be triggered
68  * at the appropriate time for the applet.
69  *
70  * @param constraints the type of constraints that were updated
71  */
72  virtual void constraintsEvent(Plasma::Types::Constraints constraints);
73 
74  /**
75  * Returns a list of context-related QAction instances.
76  *
77  * @return A list of actions. The default implementation returns an
78  * empty list.
79  */
80  virtual QList<QAction *> contextualActions();
81 
82  /**
83  * Sets whether or not this script has a configuration interface or not
84  *
85  * @param hasInterface true if the applet is user configurable
86  */
87  void setHasConfigurationInterface(bool hasInterface);
88 
89  /**
90  * @see Applet
91  */
92  void setConfigurationRequired(bool req, const QString &reason = QString());
93 
94  /**
95  * @see Applet
96  */
97  void setLaunchErrorMessage(const QString &reason = QString());
98 
99  /**
100  * @see Applet
101  */
102  void configNeedsSaving() const;
103 
104  /**
105  * @see Containment
106  * @since 4.7
107  */
108  Plasma::Types::ContainmentType containmentType() const;
109 
110  /**
111  * @see Containment
112  * @since 4.7
113  */
114  void setContainmentType(Plasma::Types::ContainmentType type);
115 
116 Q_SIGNALS:
117  /**
118  * @see Applet
119  */
120  void saveState(KConfigGroup &group) const;
121 
122  /**
123  * @param uiReady true if the UI for this applet is ready
124  */
125  void uiReadyChanged(bool uiReady);
126 
127 public Q_SLOTS:
128 
129  /**
130  * Configure was changed.
131  */
132  virtual void configChanged();
133 
134 protected:
135  /**
136  * @return absolute path to the main script file for this plasmoid
137  */
138  QString mainScript() const override;
139 
140 #if PLASMA_BUILD_DEPRECATED_SINCE(5, 83)
141 
142  /**
143  * @return the Package associated with this plasmoid which can
144  * be used to request resources, such as images and
145  * interface files.
146  */
147  PLASMA_DEPRECATED_VERSION(5, 83, "Use kpackage API instead")
148  Package package() const override;
149 #endif
150 
151 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 81)
152  /**
153  * @return the KPluginInfo associated with this plasmoid
154  * @deprecated since 5.81, use applet()->pluginMetaData() instead.
155  */
156  PLASMA_DEPRECATED_VERSION(5, 81, "Use applet()->pluginMetaData() instead.")
157  KPluginInfo description() const;
158 #endif
159 
160 private:
161  friend class Applet;
162 
163  AppletScriptPrivate *const d;
164 };
165 
166 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 88)
167 /// @deprecated Since 5.88, use K_PLUGIN_CLASS_WITH_JSON instead
168 #define K_EXPORT_PLASMA_APPLETSCRIPTENGINE(libname, classname) K_PLUGIN_FACTORY(factory, registerPlugin<classname>();)
169 
170 /// @deprecated Since 5.88, use K_PLUGIN_CLASS_WITH_JSON instead
171 #define K_EXPORT_PLASMA_APPLETSCRIPTENGINE_WITH_JSON(libname, classname, jsonFile) K_PLUGIN_FACTORY_WITH_JSON(factory, jsonFile, registerPlugin<classname>();)
172 #endif
173 } // Plasma namespace
174 
175 #endif
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
Provides a restricted interface for scripted applets.
Definition: appletscript.h:35
ContainmentType
This enumeration describes the type of the Containment.
Definition: plasma.h:114
object representing an installed Plasma package
Definition: package.h:76
The base Applet class.
Definition: applet.h:71
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.