Plasma

applet.h
1 /*
2  SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <[email protected]>
3  SPDX-FileCopyrightText: 2007 Riccardo Iaconelli <[email protected]>
4  SPDX-FileCopyrightText: 2008 Ménard Alexis <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef PLASMA_APPLET_H
10 #define PLASMA_APPLET_H
11 
12 #include <QKeySequence>
13 #include <QObject>
14 #include <QUrl>
15 
16 #include <KConfigGroup>
17 #include <plasma/plasma_export.h>
18 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 94)
19 #include <KPluginInfo>
20 #endif
21 
22 #include <plasma/framesvg.h>
23 #include <plasma/plasma.h>
24 
25 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 100)
26 #include <KPackage/Package>
27 #else
28 namespace KPackage
29 {
30 class Package;
31 }
32 #endif
33 namespace PlasmaQuick
34 {
35 class AppletQuickItem;
36 class ConfigViewPrivate;
37 class ConfigModelPrivate;
38 class ConfigModel;
39 };
40 class DeclarativeAppletScript;
41 #include <KPluginFactory>
42 
43 class KActionCollection;
44 class KConfigLoader;
45 
46 namespace Plasma
47 {
48 class AppletPrivate;
49 class Containment;
50 class DataEngine;
51 class Package;
52 
53 /**
54  * @class Applet plasma/applet.h <Plasma/Applet>
55  *
56  * @short The base Applet class
57  *
58  * Applet provides several important roles for add-ons widgets in Plasma.
59  *
60  * First, it is the base class for the plugin system and therefore is the
61  * interface to applets for host applications. It also handles the life time
62  * management of data engines (e.g. all data engines accessed via
63  * Applet::dataEngine(const QString&) are properly deref'd on Applet
64  * destruction), background painting (allowing for consistent and complex
65  * look and feel in just one line of code for applets), loading and starting
66  * of scripting support for each applet, providing access to the associated
67  * plasmoid package (if any) and access to configuration data.
68  *
69  * See techbase.kde.org for tutorials on writing Applets using this class.
70  */
71 class PLASMA_EXPORT Applet : public QObject
72 {
73  Q_OBJECT
74  Q_PROPERTY(Plasma::Types::ItemStatus status READ status WRITE setStatus NOTIFY statusChanged)
75  Q_PROPERTY(Plasma::Types::ImmutabilityType immutability READ immutability WRITE setImmutability NOTIFY immutabilityChanged)
76  Q_PROPERTY(Plasma::Types::FormFactor formFactor READ formFactor NOTIFY formFactorChanged)
77  Q_PROPERTY(Plasma::Types::Location location READ location NOTIFY locationChanged)
78  Q_PROPERTY(Plasma::Types::ContainmentDisplayHints containmentDisplayHints READ containmentDisplayHints NOTIFY containmentDisplayHintsChanged)
79  Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged FINAL)
80  Q_PROPERTY(QString icon READ icon WRITE setIcon NOTIFY iconChanged FINAL)
81  Q_PROPERTY(bool busy READ isBusy WRITE setBusy NOTIFY busyChanged FINAL)
82 
83  /**
84  * How the applet wants its background to be drawn. The containment may chose to ignore this hint.
85  */
86  Q_PROPERTY(Plasma::Types::BackgroundHints backgroundHints WRITE setBackgroundHints READ backgroundHints NOTIFY backgroundHintsChanged FINAL)
87 
88  /**
89  * The containment (and/or the user) may decide to use another kind of background instead (if supported by the applet)
90  */
91  Q_PROPERTY(Plasma::Types::BackgroundHints userBackgroundHints WRITE setUserBackgroundHints READ userBackgroundHints NOTIFY userBackgroundHintsChanged FINAL)
92 
93  /**
94  * The effective background hints the applet has, internally decided how to mix with userBackgroundHints
95  */
96  Q_PROPERTY(Plasma::Types::BackgroundHints effectiveBackgroundHints READ effectiveBackgroundHints NOTIFY effectiveBackgroundHintsChanged FINAL)
97 
98 public:
99  // CONSTRUCTORS
100 
101  /**
102  * This constructor can be used with the KCoreAddons plugin loading system.
103  * The argument list is expected to have contain the KPackage of the applet,
104  * the meta data file path (for compatibility) and an applet ID which must be a base 10 number.
105  *
106  * @param parent a QObject parent; you probably want to pass in 0
107  * @param data, KPluginMetaData used to create this plugin
108  * @param args a list of strings containing the applet id
109  * @Since 5.86
110  */
111  Applet(QObject *parentObject, const KPluginMetaData &data, const QVariantList &args);
112 
113 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 86)
114  /**
115  * @param parent the QObject this applet is parented to
116  * @param serviceId the name of the .desktop file containing the
117  * information about the widget
118  * @param appletId a unique id used to differentiate between multiple
119  * instances of the same Applet type
120  * @deprecated Since 5.86, use Applet(QObject *, KPluginMetaData, QVariantList) instead
121  */
122  PLASMA_DEPRECATED_VERSION(5, 86, "use Applet(QObject *, KPluginMetaData, QVariantList) instead")
123  explicit Applet(QObject *parent = nullptr, const QString &serviceId = QString(), uint appletId = 0);
124 #endif
125 
126 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 28)
127  /**
128  * @param parent the QObject this applet is parented to
129  * @param info the plugin information object for this Applet
130  * @param appletId a unique id used to differentiate between multiple
131  * instances of the same Applet type
132  * @since 4.6
133  *
134  * @deprecated Since 5.28, prefer using KPluginMetaData
135  */
136  PLASMA_DEPRECATED_VERSION(5, 28, "Use Applet(const KPluginMetaData &, QObject *, uint")
137  explicit Applet(const KPluginInfo &info, QObject *parent = nullptr, uint appletId = 0);
138 #endif
139 
140 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 86)
141  /**
142  * @param parent the QObject this applet is parented to
143  * @param metadata the plugin information object for this Applet
144  * @param appletId a unique id used to differentiate between multiple
145  * instances of the same Applet type
146  * @since 5.27
147  * @deprecated Since 5.86, use Applet(QObject *, KPluginMetaData, QVariantList) instead
148  */
149  PLASMA_DEPRECATED_VERSION(5, 86, "use Applet(QObject *, KPluginMetaData, QVariantList) instead")
150  explicit Applet(const KPluginMetaData &metadata, QObject *parent = nullptr, uint appletId = 0);
151 #endif
152 
153  ~Applet() override;
154 
155  // BOOKKEEPING
156  /**
157  * @return the id of this applet
158  */
159  uint id() const;
160 
161  /**
162  * @return The type of immutability of this applet
163  */
164  Types::ImmutabilityType immutability() const;
165 
166  /**
167  * If for some reason, the applet fails to get up on its feet (the
168  * library couldn't be loaded, necessary hardware support wasn't found,
169  * etc..) this method returns the reason why, in an user-readable way.
170  * @since 5.0
171  **/
172  QString launchErrorMessage() const;
173 
174  /**
175  * If for some reason, the applet fails to get up on its feet (the
176  * library couldn't be loaded, necessary hardware support wasn't found,
177  * etc..) this method returns true.
178  **/
179  bool failedToLaunch() const;
180 
181  /**
182  * @return true if destroy() was called; useful for Applets which should avoid
183  * certain tasks if they are about to be deleted permanently
184  */
185  bool destroyed() const;
186 
187  /**
188  * @return the Containment, if any, this applet belongs to
189  **/
190  Containment *containment() const;
191 
192  /**
193  * @return true if this Applet is currently being used as a Containment, false otherwise
194  */
195  bool isContainment() const;
196 
197  /**
198  * @return the status of the applet
199  * @since 4.4
200  */
201  Types::ItemStatus status() const;
202 
203  /**
204  * Returns the current form factor the applet is being displayed in.
205  *
206  * @see Plasma::FormFactor
207  */
208  Types::FormFactor formFactor() const;
209 
210  /**
211  * Returns the location of the scene which is displaying applet.
212  *
213  * @see Plasma::Types::Location
214  */
215  Types::Location location() const;
216 
217  /**
218  * @return Display hints that come from the containment that suggest the applet how to look and behave.
219  * @since 5.77
220  */
221  Types::ContainmentDisplayHints containmentDisplayHints() const;
222 
223  // CONFIGURATION
224  /**
225  * Returns the KConfigGroup to access the applets configuration.
226  *
227  * This config object will write to an instance
228  * specific config file named <appletname><instanceid>rc
229  * in the Plasma appdata directory.
230  **/
231  KConfigGroup config() const;
232 
233  /**
234  * Returns a KConfigGroup object to be shared by all applets of this
235  * type.
236  *
237  * This config object will write to an applet-specific config object
238  * named plasma_<appletname>rc in the local config directory.
239  */
240  KConfigGroup globalConfig() const;
241 
242  /**
243  * Returns the config skeleton object from this applet's package,
244  * if any.
245  *
246  * @return config skeleton object, or 0 if none
247  **/
248  KConfigLoader *configScheme() const;
249 
250  /**
251  * Saves state information about this applet that will
252  * be accessed when next instantiated in the restore(KConfigGroup&) method.
253  *
254  * This method does not need to be reimplemented by Applet
255  * subclasses, but can be useful for Applet specializations
256  * (such as Containment) to do so.
257  *
258  * Applet subclasses may instead want to reimplement saveState().
259  **/
260  virtual void save(KConfigGroup &group) const;
261 
262  /**
263  * Restores state information about this applet saved previously
264  * in save(KConfigGroup&).
265  *
266  * This method does not need to be reimplemented by Applet
267  * subclasses, but can be useful for Applet specializations
268  * (such as Containment) to do so.
269  **/
270  virtual void restore(KConfigGroup &group);
271 
272  /**
273  * @return true if the applet currently needs to be configured,
274  * otherwise, false
275  */
276  bool configurationRequired() const;
277 
278  /**
279  * @return A translated message for the user explaining that the
280  * applet needs configuring; this should note what needs
281  * to be configured
282  *
283  * @see setConfigurationRequired
284  * @since 5.20
285  */
286  QString configurationRequiredReason() const;
287 
288  /**
289  * @return true when the configuration interface is being shown
290  * @since 4.5
291  */
292  bool isUserConfiguring() const;
293 
294  /**
295  * Tells the applet the user is configuring
296  * @param configuring true if the configuration ui is showing
297  */
298  void setUserConfiguring(bool configuring);
299 
300 // UTILS
301 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 6)
302  /**
303  * Accessor for the associated Package object if any.
304  * Generally, only Plasmoids come in a Package.
305  *
306  * @return the Package object, or an invalid one if none
307  * @deprecated Since 5.6, use kPackage() instead
308  **/
309  PLASMA_DEPRECATED_VERSION(5, 6, "Use Applet::kPackage()")
310  Package package() const;
311 #endif
312 
313 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 100)
314  /**
315  * Accessor for the associated Package object if any.
316  * Generally, only Plasmoids come in a Package.
317  *
318  * @return the Package object, or an invalid one if none
319  * @since 5.6
320  * @deprecated Since 5.100, accessing an applets KPackage is deprecated. For using the metadata, use @p pluginMetaData instead.
321  **/
322  KPackage::Package kPackage() const;
323 #endif
324 
325  /**
326  * Called when any of the geometry constraints have been updated.
327  * This method calls constraintsEvent, which may be reimplemented,
328  * once the Applet has been prepared for updating the constraints.
329  *
330  * @param constraints the type of constraints that were updated
331  */
332  void updateConstraints(Plasma::Types::Constraints constraints = Plasma::Types::AllConstraints);
333 
334 // METADATA
335 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 28)
336  /**
337  * @return metadata information about this plugin
338  * @see KPluginInfo, pluginMetaData
339  * @since 5.0
340  * @deprecated Since 5.28, use pluginMetaData instead
341  */
342  PLASMA_DEPRECATED_VERSION(5, 28, "Use Applet::pluginMetaData()")
343  KPluginInfo pluginInfo() const;
344 #endif
345 
346  /**
347  * @return metadata information about this plugin
348  *
349  * @since 5.27
350  */
351  KPluginMetaData pluginMetaData() const;
352 
353  /**
354  * Returns the user-visible title for the applet, as specified in the
355  * Name field of the .desktop file. Can be changed with @see setTitle
356  *
357  * @since 5.0
358  * @return the user-visible title for the applet.
359  **/
360  QString title() const;
361 
362  /**
363  * Sets a custom title for this instance of the applet. E.g. a clock might
364  * use the timezone as its name rather than the .desktop file
365  *
366  * @since 5.0
367  * @param title the user-visible title for the applet.
368  */
369  void setTitle(const QString &title);
370 
371 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 19)
372  /**
373  * Attempts to load an applet from a package
374  *
375  * Returns a pointer to the applet if successful.
376  * The caller takes responsibility for the applet, including
377  * deleting it when no longer needed.
378  * If you instance a plasmoid with this deprecated API, the
379  * automated default setup scripts won't be executed for that plasmoid
380  *
381  * @param path the path to the package
382  * @param appletId unique ID to assign the applet, or zero to have one
383  * assigned automatically.
384  * @return a pointer to the loaded applet, or 0 on load failure
385  * @since 4.3
386  *
387  * @deprecated Since 5.19, use Containment::createApplet() instead, you are not
388  * supposed to have applets without containments
389  **/
390  PLASMA_DEPRECATED_VERSION(5, 19, "Use Containment::createApplet(...)")
391  static Applet *loadPlasmoid(const QString &path, uint appletId = 0);
392 #endif
393 
394  /**
395  * @returns The icon name related to this applet
396  * By default is the one in the plasmoid desktop file
397  **/
398  QString icon() const;
399 
400  /**
401  * Sets an icon name for this applet
402  * @param icon Freedesktop compatible icon name
403  */
404  void setIcon(const QString &icon);
405 
406  /**
407  * @returns true if the applet should show a busy status, for instance doing
408  * some network operation
409  * @since 5.21
410  */
411  bool isBusy() const;
412 
413  /**
414  * Sets the Applet to have a busy status hint, for instance the applet doing
415  * some network operation.
416  * The graphical representation of the busy status depends completely from
417  * the visualization.
418  * @param busy true if the applet is busy
419  * @since 5.21
420  */
421  void setBusy(bool busy);
422 
423  /**
424  * How the applet wants its background to be drawn. The containment may chose to ignore this hint.
425  * @since 5.65
426  */
427  Plasma::Types::BackgroundHints backgroundHints() const;
428 
429  /**
430  * Sets the applet background hints. Only Applet implementations should write this property
431  * @since 5.65
432  */
433  void setBackgroundHints(Plasma::Types::BackgroundHints hint);
434 
435  /**
436  * The containment (and/or the user) may decide to use another kind of background instead if supported by the applet.
437  * In order for an applet to support user configuration of the
438  * background, it needs to have the Plasma::Types::ConfigurableBackground flag set in its backgroundHints
439  * @since 5.65
440  */
441  Plasma::Types::BackgroundHints userBackgroundHints() const;
442 
443  /**
444  * Sets the hints the user wished the background style for the applet to be.
445  * @since 5.65
446  */
447  void setUserBackgroundHints(Plasma::Types::BackgroundHints hint);
448 
449  /**
450  * The effective background hints the applet will have: it will follow userBackgroundHints only if backgroundHints has the
451  * Plasma::Types::ConfigurableBackground flag set
452  * @since 5.65
453  */
454  Plasma::Types::BackgroundHints effectiveBackgroundHints() const;
455 
456  // ACTIONS
457  /**
458  * Returns a list of context-related QAction instances.
459  *
460  * This is used e.g. within the \a DesktopView to display a
461  * contextmenu.
462  *
463  * @return A list of actions. The default implementation returns an
464  * empty list.
465  **/
466  virtual QList<QAction *> contextualActions();
467 
468  /**
469  * Returns the collection of actions for this Applet
470  */
471  KActionCollection *actions() const;
472 
473  /**
474  * Sets the global shortcut to associate with this widget.
475  */
476  void setGlobalShortcut(const QKeySequence &shortcut);
477 
478  /**
479  * @return the global shortcut associated with this widget, or
480  * an empty shortcut if no global shortcut is associated.
481  */
482  QKeySequence globalShortcut() const;
483 
484  // ASSOCIATED APPLICATION
485  /**
486  * Sets an application associated to this applet, that will be
487  * regarded as a full view of what is represented in the applet
488  *
489  * @param string the name of the application. it can be
490  * \li a name understood by KService::serviceByDesktopName
491  * (e.g. "konqueror")
492  * \li a command in $PATH
493  * \li or an absolute path to an executable
494  * @since 4.4
495  */
496  void setAssociatedApplication(const QString &string);
497 
498  /**
499  * Sets a list of urls associated to this application,
500  * they will be used as parameters for the associated application
501  * @see setAssociatedApplication()
502  *
503  * @param urls
504  */
505  void setAssociatedApplicationUrls(const QList<QUrl> &urls);
506 
507  /**
508  * @return the application associated to this applet
509  * @since 4.4
510  */
511  QString associatedApplication() const;
512 
513  /**
514  * @return the urls associated to this applet
515  * @since 4.4
516  */
517  QList<QUrl> associatedApplicationUrls() const;
518 
519  /**
520  * @return true if the applet has a valid associated application or urls
521  * @since 4.4
522  */
523  bool hasValidAssociatedApplication() const;
524 
525  // Completely UI-specific, remove or move to scriptengine
526  /**
527  * @return true if this plasmoid provides a GUI configuration
528  **/
529  bool hasConfigurationInterface() const;
530 
531 Q_SIGNALS:
532  // BOOKKEEPING
533  /**
534  * Emitted when the immutability changes
535  * @since 4.4
536  */
537  void immutabilityChanged(Plasma::Types::ImmutabilityType immutable);
538 
539  /**
540  * Emitted when the applet status changes
541  * @since 4.4
542  */
543  void statusChanged(Plasma::Types::ItemStatus status);
544 
545  /**
546  * Emitted when the applet has been scheduled for destruction
547  * or the destruction has been undone
548  * @since 5.4
549  */
550  void destroyedChanged(bool destroyed);
551 
552  /**
553  * Emitted when the title has changed
554  * @since 5.20
555  */
556  void titleChanged(const QString &title);
557 
558  /**
559  * Emitted when the icon name for the applet has changed
560  * @since 5.20
561  */
562  void iconChanged(const QString &icon);
563 
564  /**
565  * Emitted when the busy status has changed
566  * @since 5.21
567  */
568  void busyChanged(bool busy);
569 
570  /**
571  * Emitted when the background hints have changed
572  * @since 5.65
573  */
574  void backgroundHintsChanged();
575 
576  /**
577  * Emitted when the user background hints have changed
578  * @since 5.65
579  */
580  void userBackgroundHintsChanged();
581 
582  /**
583  * Emitted when the effective background hints have changed
584  * @since 5.65
585  */
586  void effectiveBackgroundHintsChanged();
587 
588  // CONFIGURATION
589  /**
590  * Emitted when an applet has changed values in its configuration
591  * and wishes for them to be saved at the next save point. As this implies
592  * disk activity, this signal should be used with care.
593  *
594  * @note This does not need to be emitted from saveState by individual
595  * applets.
596  */
597  void configNeedsSaving();
598 
599  /**
600  * emitted when the config ui appears or disappears
601  */
602  void userConfiguringChanged(bool configuring);
603 
604  // ACTIONS
605  /**
606  * Emitted just before the contextual actions are about to show
607  * For instance just before the context menu containing the actions
608  * added with setAction() is shown
609  */
610  void contextualActionsAboutToShow();
611 
612  /**
613  * Emitted when activation is requested due to, for example, a global
614  * keyboard shortcut. By default the widget is given focus.
615  */
616  void activated();
617 
618  // TODO: fix usage in containment, port to QObject::destroyed
619  /**
620  * Emitted when the applet is deleted
621  */
622  void appletDeleted(Plasma::Applet *applet);
623 
624  /**
625  * Emitted when the formfactor changes
626  */
627  void formFactorChanged(Plasma::Types::FormFactor formFactor);
628 
629  /**
630  * Emitted when the location changes
631  */
632  void locationChanged(Plasma::Types::Location location);
633 
634  void containmentDisplayHintsChanged(Plasma::Types::ContainmentDisplayHints hints);
635 
636  /**
637  * Emitted when setConfigurationRequired was called
638  * @see setConfigurationRequired
639  * @since 5.20
640  */
641  void configurationRequiredChanged(bool needsConfig, const QString &reason);
642 
643 public Q_SLOTS:
644  // BOOKKEEPING
645  /**
646  * Call this method when the applet fails to launch properly. An
647  * optional reason can be provided.
648  *
649  * Not that all children items will be deleted when this method is
650  * called. If you have pointers to these items, you will need to
651  * reset them after calling this method.
652  *
653  * @param failed true when the applet failed, false when it succeeded
654  * @param reason an optional reason to show the user why the applet
655  * failed to launch
656  * @since 5.0
657  **/
658  void setLaunchErrorMessage(const QString &reason = QString());
659 
660  /**
661  * Sets the immutability type for this applet (not immutable,
662  * user immutable or system immutable)
663  * @param immutable the new immutability type of this applet
664  */
665  void setImmutability(const Types::ImmutabilityType immutable);
666 
667  /**
668  * Destroys the applet; it will be removed nicely and deleted.
669  * Its configuration will also be deleted.
670  * If you want to remove the Applet configuration, use this, don't just delete the Applet *
671  */
672  void destroy();
673 
674  /**
675  * sets the status for this applet
676  * @since 4.4
677  */
678  void setStatus(const Types::ItemStatus stat);
679 
680  // CONFIGURATION
681  /**
682  * Called when applet configuration values have changed.
683  */
684  // TODO KF6: make it not a slot anymore and protected
685  virtual void configChanged();
686 
687  // UTILS
688  /**
689  * Sends all pending constraints updates to the applet. Will usually
690  * be called automatically, but can also be called manually if needed.
691  */
692  void flushPendingConstraintsEvents();
693 
694  /**
695  * This method is called once the applet is loaded and added to a Corona.
696  * If the applet requires a Scene or has an particularly intensive
697  * set of initialization routines to go through, consider implementing it
698  * in this method instead of the constructor.
699  *
700  * Note: paintInterface may get called before init() depending on initialization
701  * order. Painting is managed by the canvas (QGraphisScene), and may schedule a
702  * paint event prior to init() being called.
703  **/
704  virtual void init();
705 
706  // ASSOCIATED APPLICATION
707  /**
708  * Open the application associated to this applet, if it's not set
709  * but some urls are, open those urls with the proper application
710  * for their mimetype
711  * @see setAssociatedApplication()
712  * @see setAssociatedApplicationUrls()
713  * @since 4.4
714  */
715  void runAssociatedApplication();
716 
717 protected:
718 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 86)
719  /**
720  * This constructor is to be used with the plugin loading systems
721  * found in KPluginInfo and KService. The argument list is expected
722  * to have two elements: the KService service ID for the desktop entry
723  * and an applet ID which must be a base 10 number.
724  *
725  * @param parent a QObject parent; you probably want to pass in 0
726  * @param args a list of strings containing two entries: the service id
727  * and the applet id
728  * @deprecated Since 5.86, use Applet(QObject *, KPluginMetaData, QVariantList) instead
729  */
730  PLASMA_DEPRECATED_VERSION(5, 86, "use Applet(QObject *, KPluginMetaData, QVariantList) instead")
731  Applet(QObject *parent, const QVariantList &args);
732 #endif
733 
734  // CONFIGURATION
735  /**
736  * When called, the Applet should write any information needed as part
737  * of the Applet's running state to the configuration object in config()
738  * and/or globalConfig().
739  *
740  * Applets that always sync their settings/state with the config
741  * objects when these settings/states change do not need to reimplement
742  * this method.
743  **/
744  virtual void saveState(KConfigGroup &config) const;
745 
746  /**
747  * Sets whether or not this applet provides a user interface for
748  * configuring the applet.
749  *
750  * It defaults to false, and if true is passed in you should
751  * also reimplement createConfigurationInterface()
752  *
753  * @param hasInterface whether or not there is a user interface available
754  **/
755  void setHasConfigurationInterface(bool hasInterface);
756 
757  /**
758  * When the applet needs to be configured before being usable, this
759  * method can be called to show a standard interface prompting the user
760  * to configure the applet
761  *
762  * @param needsConfiguring true if the applet needs to be configured,
763  * or false if it doesn't
764  * @param reason a translated message for the user explaining that the
765  * applet needs configuring; this should note what needs
766  * to be configured
767  */
768  void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());
769 
770  // UTILS
771  /**
772  * Called when any of the constraints for the applet have been updated. These constraints
773  * range from notifying when the applet has officially "started up" to when geometry changes
774  * to when the form factor changes.
775  *
776  * Each constraint that has been changed is passed in the constraints flag.
777  * All of the constraints and how they work is documented in the @see Plasma::Constraints
778  * enumeration.
779  *
780  * On applet creation, this is always called prior to painting and can be used as an
781  * opportunity to layout the widget, calculate sizings, etc.
782  *
783  * Do not call update() from this method; an update() will be triggered
784  * at the appropriate time for the applet.
785  *
786  * @param constraints the type of constraints that were updated
787  * @property constraint
788  */
789  virtual void constraintsEvent(Plasma::Types::Constraints constraints);
790 
791  // TODO: timerEvent should go into AppletPrivate
792  /**
793  * Reimplemented from QObject
794  */
795  void timerEvent(QTimerEvent *event) override;
796 
797 private:
798  QString filePath(const QByteArray &key, const QString &filename = QString()) const;
799 #if !PLASMA_ENABLE_DEPRECATED_SINCE(5, 100)
800  KPackage::Package kPackage() const;
801 #endif
802  /**
803  * @internal This constructor is to be used with the Package loading system.
804  *
805  * @param parent a QObject parent; you probably want to pass in 0
806  * @param args a list of strings containing two entries: the service id
807  * and the applet id
808  * @since 4.3
809  */
810  Applet(const QString &packagePath, uint appletId);
811 
812  Q_PRIVATE_SLOT(d, void cleanUpAndDelete())
813  Q_PRIVATE_SLOT(d, void askDestroy())
814  Q_PRIVATE_SLOT(d, void updateShortcuts())
815  Q_PRIVATE_SLOT(d, void globalShortcutChanged())
816  Q_PRIVATE_SLOT(d, void propagateConfigChanged())
817  Q_PRIVATE_SLOT(d, void requestConfiguration())
818 
819  AppletPrivate *const d;
820 
821  // Corona needs to access setLaunchErrorMessage and init
822  friend class Corona;
823  friend class CoronaPrivate;
824  friend class Containment;
825  friend class ContainmentPrivate;
826  friend class AppletScript;
827  friend class AppletPrivate;
828  friend class AccessAppletJobPrivate;
829  friend class GraphicsViewAppletPrivate;
830  friend class PluginLoader;
831  friend class AssociatedApplicationManager;
832  friend class SvgPrivate;
833  friend class PlasmaQuick::AppletQuickItem;
834  friend class PlasmaQuick::ConfigModel;
835  friend class PlasmaQuick::ConfigModelPrivate;
836  friend class PlasmaQuick::ConfigViewPrivate;
837  friend DeclarativeAppletScript;
838 };
839 
840 } // Plasma namespace
841 
842 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 88)
843 
844 /**
845  * Register an applet when it is contained in a loadable module
846  * @deprecated Since 5.88, use K_PLUGIN_CLASS_WITH_JSON instead
847  */
848 /* clang-format off */
849 #define K_EXPORT_PLASMA_APPLET(libname, classname) \
850  K_PLUGIN_FACTORY(factory, registerPlugin<classname>();)
851 
852 /// @deprecated Since 5.88, use K_PLUGIN_CLASS_WITH_JSON instead
853 #define K_EXPORT_PLASMA_APPLET_WITH_JSON(libname, classname, jsonFile) \
854  K_PLUGIN_FACTORY_WITH_JSON(factory, jsonFile, registerPlugin<classname>();)
855 /* clang-format on */
856 #endif
857 
858 #endif // multiple inclusion guard
Enums and constants used in Plasma.
Definition: plasma.h:28
ItemStatus
Status of an applet.
Definition: plasma.h:270
Namespace for everything in libplasma.
Definition: datamodel.cpp:14
BackgroundHints
Description on how draw a background for the applet.
Definition: plasma.h:298
QCA_EXPORT void init()
FormFactor
The FormFactor enumeration describes how a Plasma::Applet should arrange itself.
Definition: plasma.h:72
Provides a restricted interface for scripted applets.
Definition: appletscript.h:35
A bookkeeping Scene for Plasma::Applets.
Definition: corona.h:27
Q_SCRIPTABLE CaptureState status()
Location
The Location enumeration describes where on screen an element, such as an Applet or its managing cont...
Definition: plasma.h:158
ImmutabilityType
Defines the immutability of items like applets, corona and containments they can be free to modify,...
Definition: plasma.h:235
object representing an installed Plasma package
Definition: package.h:76
The base class for plugins that provide backgrounds and applet grouping containers.
Definition: containment.h:45
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.