Libplasma

applet.h
1/*
2 SPDX-FileCopyrightText: 2006-2007 Aaron Seigo <:wqaseigo@kde.org>
3 SPDX-FileCopyrightText: 2007 Riccardo Iaconelli <riccardo@kde.org>
4 SPDX-FileCopyrightText: 2008 Ménard Alexis <darktears31@gmail.com>
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 <QAction>
13#include <QKeySequence>
14#include <QObject>
15#include <QQmlListProperty>
16#include <QUrl>
17
18#include <KConfigGroup>
19#include <plasma/plasma_export.h>
20
21#include <Plasma/Plasma>
22
23namespace KPackage
24{
25class Package;
26}
27namespace PlasmaQuick
28{
29class AppletQuickItem;
30class ConfigViewPrivate;
31class ConfigModelPrivate;
32class ConfigModel;
33class ConfigView;
34};
35class DeclarativeAppletScript;
36#include <KPluginFactory>
37
38class KConfigLoader;
40
41namespace Plasma
42{
43class AppletPrivate;
44class Containment;
45class Package;
46
47/**
48 * @class Applet plasma/applet.h <Plasma/Applet>
49 *
50 * @short The base Applet class
51 *
52 * Applet provides several important roles for add-ons widgets in Plasma.
53 *
54 * First, it is the base class for the plugin system and therefore is the
55 * interface to applets for host applications.
56 * Background painting (allowing for consistent and complex
57 * look and feel in just one line of code for applets), loading and starting
58 * of scripting support for each applet, providing access to the associated
59 * plasmoid package (if any) and access to configuration data.
60 *
61 * See techbase.kde.org for tutorials on writing Applets using this class.
62 */
63class PLASMA_EXPORT Applet : public QObject
64{
65 Q_OBJECT
66 /**
67 * Applet id: is unique in the whole Plasma session and will never change across restarts
68 */
69 Q_PROPERTY(uint id READ id CONSTANT FINAL)
70
71 /**
72 * User friendly title for the plasmoid: it's the localized applet name by default
73 */
74 Q_PROPERTY(QString title READ title WRITE setTitle NOTIFY titleChanged FINAL)
75
76 /**
77 * Icon to represent the plasmoid
78 */
79 Q_PROPERTY(QString icon READ icon WRITE setIcon NOTIFY iconChanged FINAL)
80
81 // TODO KF6 toolTipMainText toolTipSubText toolTipTextFormat toolTipItem: need to either be here or some other kind of attached property
82
83 /**
84 * The current form factor the applet is being displayed in.
85 *
86 * @see Plasma::FormFactor
87 */
88 Q_PROPERTY(Plasma::Types::FormFactor formFactor READ formFactor NOTIFY formFactorChanged)
89
90 /**
91 * The location of the scene which is displaying applet.
92 *
93 * @see Plasma::Types::Location
94 */
95 Q_PROPERTY(Plasma::Types::Location location READ location NOTIFY locationChanged)
96
97 /**
98 * Status of the plasmoid: useful to instruct the shell if this plasmoid is requesting attention, if is accepting input, or if is in an idle, inactive state
99 */
100 Q_PROPERTY(Plasma::Types::ItemStatus status READ status WRITE setStatus NOTIFY statusChanged)
101
102 /**
103 * The immutability of the Corona.
104 * Tells the applet whether it should allow for any modification by the user.
105 */
106 Q_PROPERTY(Plasma::Types::ImmutabilityType immutability READ immutability WRITE setImmutability NOTIFY immutabilityChanged)
107
108 /**
109 * Whether the Corona is immutable. The plasmoid implementation should avoid allowing "dangerous" modifications from the user when in an immutable mode
110 *
111 * This is true when immutability is not Mutable
112 */
113 Q_PROPERTY(bool immutable READ immutable NOTIFY immutabilityChanged)
114
115 /**
116 * Display hints that come from the containment that suggest the applet how to look and behave.
117 * TODO: only in containment?
118 */
119 Q_PROPERTY(Plasma::Types::ContainmentDisplayHints containmentDisplayHints READ containmentDisplayHints NOTIFY containmentDisplayHintsChanged)
120
121 /**
122 * True if the applet should show a busy status, for instance doing
123 * some network operation
124 */
125 Q_PROPERTY(bool busy READ isBusy WRITE setBusy NOTIFY busyChanged FINAL)
126
127 /**
128 * True when the user is configuring, for instance when the configuration dialog is open.
129 */
130 Q_PROPERTY(bool userConfiguring READ isUserConfiguring NOTIFY userConfiguringChanged)
131
132 /**
133 * How the applet wants its background to be drawn. The containment may chose to ignore this hint.
134 */
135 Q_PROPERTY(Plasma::Types::BackgroundHints backgroundHints WRITE setBackgroundHints READ backgroundHints NOTIFY backgroundHintsChanged FINAL)
136
137 /**
138 * The containment (and/or the user) may decide to use another kind of background instead (if supported by the applet)
139 */
140 Q_PROPERTY(Plasma::Types::BackgroundHints userBackgroundHints WRITE setUserBackgroundHints READ userBackgroundHints NOTIFY userBackgroundHintsChanged FINAL)
141
142 /**
143 * The effective background hints the applet has, internally decided how to mix with userBackgroundHints
144 */
145 Q_PROPERTY(Plasma::Types::BackgroundHints effectiveBackgroundHints READ effectiveBackgroundHints NOTIFY effectiveBackgroundHintsChanged FINAL)
146
147 // TODO KF6: activity, screen, screenGeometry, availableScreenRect, availableScreenRegion: should we instead make the containment accessible from qml
148 // plasmoids and ask from there?
149
150 /**
151 * A KConfigPropertyMap instance that represents the configuration
152 * which is usable from QML to read and write settings like any JavaScript Object
153 */
154 Q_PROPERTY(KConfigPropertyMap *configuration READ configuration CONSTANT FINAL)
155
156 /**
157 * The global shortcut to activate the plasmoid
158 *
159 * This is typically only used by the default configuration module
160 *
161 */
162 Q_PROPERTY(QKeySequence globalShortcut READ globalShortcut WRITE setGlobalShortcut RESET setGlobalShortcut NOTIFY globalShortcutChanged)
163
164 /**
165 * If true the applet requires manual configuration from the user
166 * TODO KF6: having just a reson property and required would be string not empty? Uglier from c++ pov but more straight forward from qml pov
167 */
168 Q_PROPERTY(bool configurationRequired READ configurationRequired WRITE setConfigurationRequired NOTIFY configurationRequiredChanged)
169
170 /**
171 * True if this applet will provide a UI for its configuration
172 */
173 Q_PROPERTY(bool hasConfigurationInterface READ hasConfigurationInterface WRITE setHasConfigurationInterface NOTIFY hasConfigurationInterfaceChanged)
174
175 /**
176 * The hints that the applet gives to its constraint,
177 * such as asking to fill all the available space ignoring margins.
178 */
179 Q_PROPERTY(Applet::ConstraintHints constraintHints READ constraintHints WRITE setConstraintHints NOTIFY constraintHintsChanged FINAL)
180
181 /**
182 * The metadata of the applet.
183 */
184 Q_PROPERTY(KPluginMetaData metaData READ pluginMetaData CONSTANT)
185
186 /**
187 * The Containment managing this applet
188 */
189 Q_PROPERTY(Plasma::Containment *containment READ containment NOTIFY containmentChanged)
190
191 /**
192 * Actions to be added in the plasmoid context menu. To instantiate QActions in a declarative way,
193 * PlasmaCore.Action {} can be used
194 */
195 Q_PROPERTY(QQmlListProperty<QAction> contextualActions READ qmlContextualActions NOTIFY contextualActionsChanged)
196
197 /**
198 * True if this applet is a Containment and is acting as one, such as a desktop or a panel
199 */
200 Q_PROPERTY(bool isContainment READ isContainment CONSTANT)
201
202 /**
203 * Plugin name for the applet
204 */
205 Q_PROPERTY(QString pluginName READ pluginName CONSTANT FINAL)
206
207public:
208 /**
209 * The Constraint enumeration lists the various constraints that Plasma
210 * objects have managed for them and which they may wish to react to,
211 * for instance in Applet::constraintsUpdated
212 */
214 NoConstraint = 0, /**< No constraint; never passed in to Applet::constraintsEvent on its own */
215 FormFactorConstraint = 1, /**< The FormFactor for an object */
216 LocationConstraint = 2, /**< The Location of an object */
217 ScreenConstraint = 4, /**< Which screen an object is on */
218 ImmutableConstraint = 8, /**< the immutability (locked) nature of the applet changed */
219 StartupCompletedConstraint = 16, /**< application startup has completed */
220 UiReadyConstraint = 32,
221 /**< The ui has been completely loaded */ // (FIXME: merged with StartupCompletedConstraint?)
222 AllConstraints = FormFactorConstraint | LocationConstraint | ScreenConstraint | ImmutableConstraint,
223 };
224 Q_ENUM(Constraint)
225 Q_DECLARE_FLAGS(Constraints, Constraint)
226
227 /**
228 * This enumeration lists the various hints that an applet can pass to its
229 * constraint regarding the way that it is represented
230 */
232 NoHint = 0,
233 CanFillArea = 1,
234 /**< The CompactRepresentation can fill the area and ignore constraint margins*/ // (TODO: KF6 CanFillArea -> CompactRepresentationFillArea)
235 MarginAreasSeparator = CanFillArea | 2, /**< The applet acts as a separator between the standard and slim panel margin areas*/
236 };
237 Q_DECLARE_FLAGS(ConstraintHints, ConstraintHint)
238 Q_FLAG(ConstraintHints)
239
240 // CONSTRUCTORS
241
242 /**
243 * This constructor can be used with the KCoreAddons plugin loading system.
244 * The argument list is expected to have contain the KPackage of the applet,
245 * the meta data file path (for compatibility) and an applet ID which must be a base 10 number.
246 *
247 * @param parent a QObject parent; you probably want to pass in 0
248 * @param data, KPluginMetaData used to create this plugin
249 * @param args a list of strings containing the applet id
250 * @Since 5.86
251 */
252 Applet(QObject *parentObject, const KPluginMetaData &data, const QVariantList &args);
253
254 ~Applet() override;
255
256 // BOOKKEEPING
257 /**
258 * @return the id of this applet
259 */
260 uint id() const;
261
262 /**
263 * @return the arguments this applet was started with.
264 * Some applets support arguments, for instance the notes applet supports to be
265 * instantiated with a given text already passed as paramenter
266 */
267 QVariantList startupArguments() const;
268
269 /**
270 * @return The type of immutability of this applet
271 */
272 Types::ImmutabilityType immutability() const;
273
274 /**
275 * @return true if immutability() is not Types::Mutable
276 */
277 bool immutable() const;
278
279 /**
280 * If for some reason, the applet fails to get up on its feet (the
281 * library couldn't be loaded, necessary hardware support wasn't found,
282 * etc..) this method returns the reason why, in an user-readable way.
283 * @since 5.0
284 **/
285 QString launchErrorMessage() const;
286
287 /**
288 * If for some reason, the applet fails to get up on its feet (the
289 * library couldn't be loaded, necessary hardware support wasn't found,
290 * etc..) this method returns true.
291 **/
292 bool failedToLaunch() const;
293
294 /**
295 * @return true if destroy() was called; useful for Applets which should avoid
296 * certain tasks if they are about to be deleted permanently
297 */
298 bool destroyed() const;
299
300 /**
301 * @return the Containment, if any, this applet belongs to
302 **/
303 Containment *containment() const;
304
305 /**
306 * @return true if this Applet is currently being used as a Containment, false otherwise
307 */
308 bool isContainment() const;
309
310 /**
311 * @return the status of the applet
312 * @since 4.4
313 */
315
316 /**
317 * Returns the current form factor the applet is being displayed in.
318 *
319 * @see Plasma::FormFactor
320 */
321 Types::FormFactor formFactor() const;
322
323 /**
324 * Returns the location of the scene which is displaying applet.
325 *
326 * @see Plasma::Types::Location
327 */
328 Types::Location location() const;
329
330 /**
331 * @return Display hints that come from the containment that suggest the applet how to look and behave.
332 * @since 5.77
333 */
334 Types::ContainmentDisplayHints containmentDisplayHints() const;
335
336 // CONFIGURATION
337 /**
338 * Returns the KConfigGroup to access the applets configuration.
339 *
340 * This config object will write to an instance
341 * specific config file named <appletname><instanceid>rc
342 * in the Plasma appdata directory.
343 **/
344 KConfigGroup config() const;
345
346 /**
347 * Returns a KConfigGroup object to be shared by all applets of this
348 * type.
349 *
350 * This config object will write to an applet-specific config object
351 * named plasma_<appletname>rc in the local config directory.
352 */
353 KConfigGroup globalConfig() const;
354
355 /**
356 * Returns the config skeleton object from this applet's package,
357 * if any.
358 *
359 * @return config skeleton object, or 0 if none
360 **/
361 KConfigLoader *configScheme() const;
362
363 /**
364 * @return a KConfigPropertyMap instance that represents the configuration
365 * which is usable from QML to read and write settings like any JavaScript Object
366 */
368
369 /**
370 * Saves state information about this applet that will
371 * be accessed when next instantiated in the restore(KConfigGroup&) method.
372 *
373 * This method does not need to be reimplemented by Applet
374 * subclasses, but can be useful for Applet specializations
375 * (such as Containment) to do so.
376 *
377 * Applet subclasses may instead want to reimplement saveState().
378 **/
379 virtual void save(KConfigGroup &group) const;
380
381 /**
382 * Restores state information about this applet saved previously
383 * in save(KConfigGroup&).
384 *
385 * This method does not need to be reimplemented by Applet
386 * subclasses, but can be useful for Applet specializations
387 * (such as Containment) to do so.
388 **/
389 virtual void restore(KConfigGroup &group);
390
391 /**
392 * When the applet needs to be configured before being usable, this
393 * method can be called to show a standard interface prompting the user
394 * to configure the applet
395 *
396 * @param needsConfiguring true if the applet needs to be configured,
397 * or false if it doesn't
398 * @param reason a translated message for the user explaining that the
399 * applet needs configuring; this should note what needs
400 * to be configured
401 */
402 void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());
403
404 /**
405 * @return true if the applet currently needs to be configured,
406 * otherwise, false
407 */
408 bool configurationRequired() const;
409
410 /**
411 * @return A translated message for the user explaining that the
412 * applet needs configuring; this should note what needs
413 * to be configured
414 *
415 * @see setConfigurationRequired
416 * @since 5.20
417 */
418 QString configurationRequiredReason() const;
419
420 /**
421 * Sets the constraint hits which give a more granular control over sizing in
422 * constrained layouts such as panels
423 *
424 * @param constraintHints such as CanFillArea or MarginAreasSeparator,
425 * they can be in bitwise OR
426 */
427 void setConstraintHints(ConstraintHints constraintHints);
428
429 /**
430 * @return The constraint hints such as CanFillArea or MarginAreasSeparator,
431 * they can be in bitwise OR
432 */
433 ConstraintHints constraintHints() const;
434
435 /**
436 * @return true when the configuration interface is being shown
437 * @since 4.5
438 */
439 bool isUserConfiguring() const;
440
441 /**
442 * Tells the applet the user is configuring
443 * @param configuring true if the configuration ui is showing
444 */
445 void setUserConfiguring(bool configuring);
446
447 // UTILS
448 /**
449 * Called when any of the geometry constraints have been updated.
450 * This method calls constraintsEvent, which may be reimplemented,
451 * once the Applet has been prepared for updating the constraints.
452 *
453 * @param constraints the type of constraints that were updated
454 */
455 void updateConstraints(Constraints constraints = AllConstraints);
456
457 // METADATA
458
459 /**
460 * @return metadata information about this plugin
461 *
462 * @since 5.27
463 */
464 KPluginMetaData pluginMetaData() const;
465
466 /**
467 * @return the plugin name form KPluginMetaData
468 */
469 QString pluginName() const;
470
471 /**
472 * Returns the user-visible title for the applet, as specified in the
473 * Name field of the .desktop file. Can be changed with @see setTitle
474 *
475 * @since 5.0
476 * @return the user-visible title for the applet.
477 **/
478 QString title() const;
479
480 /**
481 * Sets a custom title for this instance of the applet. E.g. a clock might
482 * use the timezone as its name rather than the .desktop file
483 *
484 * @since 5.0
485 * @param title the user-visible title for the applet.
486 */
487 void setTitle(const QString &title);
488
489 /**
490 * @returns The icon name related to this applet
491 * By default is the one in the plasmoid desktop file
492 **/
493 QString icon() const;
494
495 /**
496 * Sets an icon name for this applet
497 * @param icon Freedesktop compatible icon name
498 */
499 void setIcon(const QString &icon);
500
501 /**
502 * @returns true if the applet should show a busy status, for instance doing
503 * some network operation
504 * @since 5.21
505 */
506 bool isBusy() const;
507
508 /**
509 * Sets the Applet to have a busy status hint, for instance the applet doing
510 * some network operation.
511 * The graphical representation of the busy status depends completely from
512 * the visualization.
513 * @param busy true if the applet is busy
514 * @since 5.21
515 */
516 void setBusy(bool busy);
517
518 /**
519 * How the applet wants its background to be drawn. The containment may chose to ignore this hint.
520 * @since 5.65
521 */
522 Plasma::Types::BackgroundHints backgroundHints() const;
523
524 /**
525 * Sets the applet background hints. Only Applet implementations should write this property
526 * @since 5.65
527 */
528 void setBackgroundHints(Plasma::Types::BackgroundHints hint);
529
530 /**
531 * The containment (and/or the user) may decide to use another kind of background instead if supported by the applet.
532 * In order for an applet to support user configuration of the
533 * background, it needs to have the Plasma::Types::ConfigurableBackground flag set in its backgroundHints
534 * @since 5.65
535 */
536 Plasma::Types::BackgroundHints userBackgroundHints() const;
537
538 /**
539 * Sets the hints the user wished the background style for the applet to be.
540 * @since 5.65
541 */
542 void setUserBackgroundHints(Plasma::Types::BackgroundHints hint);
543
544 /**
545 * The effective background hints the applet will have: it will follow userBackgroundHints only if backgroundHints has the
546 * Plasma::Types::ConfigurableBackground flag set
547 * @since 5.65
548 */
549 Plasma::Types::BackgroundHints effectiveBackgroundHints() const;
550
551 // ACTIONS
552 /**
553 * Returns a list of context-related QAction instances.
554 *
555 * This is used e.g. within the \a DesktopView to display a
556 * contextmenu.
557 *
558 * @return A list of actions. The default implementation returns an
559 * empty list.
560 **/
562
563 QML_LIST_PROPERTY_ASSIGN_BEHAVIOR_REPLACE
564 QQmlListProperty<QAction> qmlContextualActions();
565
566 /**
567 * Add a new internal action. if an internal action with the same name already exists, it
568 * will be replaced with this new one.
569 * Those are usually actions defined by the system, such as "configure" and "remove"
570 *
571 * @param name The unique name for the action
572 * @param action The new QAction to be added
573 */
574 Q_INVOKABLE void setInternalAction(const QString &name, QAction *action);
575
576 /**
577 * @returns the internal action with the given name if available
578 * @param name the unique name of the action we want
579 */
580 Q_INVOKABLE QAction *internalAction(const QString &name) const;
581
582 /**
583 * Removes an action from the internal actions
584 * @param name the action to be removed
585 */
586 Q_INVOKABLE void removeInternalAction(const QString &name);
587
588 /**
589 * @returns All the internal actions such as configure, remove, alternatives etc
590 */
591 QList<QAction *> internalActions() const;
592
593 /**
594 * Sets the global shortcut to associate with this widget.
595 */
596 void setGlobalShortcut(const QKeySequence &shortcut = QKeySequence());
597
598 /**
599 * @return the global shortcut associated with this widget, or
600 * an empty shortcut if no global shortcut is associated.
601 */
602 QKeySequence globalShortcut() const;
603
604 /**
605 * Sets whether or not this applet provides a user interface for
606 * configuring the applet.
607 *
608 * It defaults to false, and if true is passed in you should
609 * also reimplement createConfigurationInterface()
610 *
611 * @param hasInterface whether or not there is a user interface available
612 **/
613 void setHasConfigurationInterface(bool hasInterface);
614
615 // Completely UI-specific, remove or move to scriptengine
616 /**
617 * @return true if this plasmoid provides a GUI configuration
618 **/
619 bool hasConfigurationInterface() const;
620
621 /**
622 * The translation domain for this applet
623 *
624 * @since 6.1
625 */
626 QString translationDomain() const;
627
628Q_SIGNALS:
629 // BOOKKEEPING
630 /**
631 * Emitted when the immutability changes
632 * @since 4.4
633 */
635
636 /**
637 * Emitted when the applet status changes
638 * @since 4.4
639 */
641
642 /**
643 * Emitted when the applet has been scheduled for destruction
644 * or the destruction has been undone
645 * @since 5.4
646 */
647 void destroyedChanged(bool destroyed);
648
649 /**
650 * Emitted when the title has changed
651 * @since 5.20
652 */
653 void titleChanged(const QString &title);
654
655 /**
656 * Emitted when the icon name for the applet has changed
657 * @since 5.20
658 */
659 void iconChanged(const QString &icon);
660
661 /**
662 * Emitted when the busy status has changed
663 * @since 5.21
664 */
665 void busyChanged(bool busy);
666
667 /**
668 * Emitted when the background hints have changed
669 * @since 5.65
670 */
672
673 /**
674 * Emitted when the user background hints have changed
675 * @since 5.65
676 */
678
679 /**
680 * Emitted when the effective background hints have changed
681 * @since 5.65
682 */
684
685 /**
686 * Emitted when the global shortcut to activate this applet has chanaged
687 */
688 void globalShortcutChanged(const QKeySequence &sequence);
689
690 // CONFIGURATION
691 /**
692 * Emitted when an applet has changed values in its configuration
693 * and wishes for them to be saved at the next save point. As this implies
694 * disk activity, this signal should be used with care.
695 *
696 * @note This does not need to be emitted from saveState by individual
697 * applets.
698 */
700
701 /**
702 * emitted when the config ui appears or disappears
703 */
704 void userConfiguringChanged(bool configuring);
705
706 // ACTIONS
707 /**
708 * Emitted just before the contextual actions are about to show
709 * For instance just before the context menu containing the actions
710 * added with setAction() is shown
711 */
713
714 /**
715 * Emitted when activation is requested due to, for example, a global
716 * keyboard shortcut. By default the widget is given focus.
717 */
718 void activated();
719
720 /**
721 * Emitted when activation is requested due to, for example, middle
722 * click.
723 * @since 6.3
724 */
726
727 // TODO: fix usage in containment, port to QObject::destroyed
728 /**
729 * Emitted when the applet is deleted
730 */
732
733 /**
734 * Emitted when the formfactor changes
735 */
737
738 /**
739 * Emitted when the location changes
740 */
742
743 /**
744 * Emitted when the containment display hints change
745 */
747
748 /**
749 * Emitted when setConfigurationRequired was called
750 * @see setConfigurationRequired
751 * @since 5.20
752 */
753 void configurationRequiredChanged(bool needsConfig, const QString &reason);
754
755 /**
756 * Emitted when the applet gains or loses the ability to show a configuration interface
757 * @see hasConfigurationInterface
758 * @since 6.0
759 */
760 void hasConfigurationInterfaceChanged(bool hasConfiguration);
761
762 /**
763 * Emitted when the constraint hints changed
764 * @see setConstraintHints
765 */
767
768 /**
769 * Emitted when the containment changes
770 */
772
773 /**
774 * Emitted when the list of contextual actions has changed
775 */
777
778 /**
779 * Emitted when the list of internal actions has changed
780 */
782
783 // TODO KF6 keep as Q_SLOT only stuff that needsto be manually invokable from qml
784public Q_SLOTS:
785 // BOOKKEEPING
786 /**
787 * Call this method when the applet fails to launch properly. An
788 * optional reason can be provided.
789 *
790 * Not that all children items will be deleted when this method is
791 * called. If you have pointers to these items, you will need to
792 * reset them after calling this method.
793 *
794 * @param failed true when the applet failed, false when it succeeded
795 * @param reason an optional reason to show the user why the applet
796 * failed to launch
797 * @since 5.0
798 **/
799 void setLaunchErrorMessage(const QString &reason = QString());
800
801 /**
802 * Sets the immutability type for this applet (not immutable,
803 * user immutable or system immutable)
804 * @param immutable the new immutability type of this applet
805 */
806 void setImmutability(const Types::ImmutabilityType immutable);
807
808 /**
809 * Destroys the applet; it will be removed nicely and deleted.
810 * Its configuration will also be deleted.
811 * If you want to remove the Applet configuration, use this, don't just delete the Applet *
812 */
813 void destroy();
814
815 /**
816 * sets the status for this applet
817 * @since 4.4
818 */
819 void setStatus(const Types::ItemStatus stat);
820
821 // CONFIGURATION
822 /**
823 * Called when applet configuration values have changed.
824 */
825 // TODO KF6: make it not a slot anymore and protected
826 virtual void configChanged();
827
828 // UTILS
829 /**
830 * Sends all pending constraints updates to the applet. Will usually
831 * be called automatically, but can also be called manually if needed.
832 */
833 void flushPendingConstraintsEvents();
834
835 /**
836 * This method is called once the applet is loaded and added to a Corona.
837 * If the applet requires a Scene or has an particularly intensive
838 * set of initialization routines to go through, consider implementing it
839 * in this method instead of the constructor.
840 *
841 * Note: paintInterface may get called before init() depending on initialization
842 * order. Painting is managed by the canvas (QGraphisScene), and may schedule a
843 * paint event prior to init() being called.
844 **/
845 virtual void init();
846
847protected:
848 // CONFIGURATION
849 /**
850 * When called, the Applet should write any information needed as part
851 * of the Applet's running state to the configuration object in config()
852 * and/or globalConfig().
853 *
854 * Applets that always sync their settings/state with the config
855 * objects when these settings/states change do not need to reimplement
856 * this method.
857 **/
858 virtual void saveState(KConfigGroup &config) const;
859
860 // UTILS
861 /**
862 * Called when any of the constraints for the applet have been updated. These constraints
863 * range from notifying when the applet has officially "started up" to when geometry changes
864 * to when the form factor changes.
865 *
866 * Each constraint that has been changed is passed in the constraints flag.
867 * All of the constraints and how they work is documented in the @see Plasma::Constraints
868 * enumeration.
869 *
870 * On applet creation, this is always called prior to painting and can be used as an
871 * opportunity to layout the widget, calculate sizings, etc.
872 *
873 * Do not call update() from this method; an update() will be triggered
874 * at the appropriate time for the applet.
875 *
876 * @param constraints the type of constraints that were updated
877 * @property constraint
878 */
879 virtual void constraintsEvent(Constraints constraints);
880
881 // TODO: timerEvent should go into AppletPrivate
882 /**
883 * Reimplemented from QObject
884 */
885 void timerEvent(QTimerEvent *event) override;
886
887private:
888 QUrl fileUrl(const QByteArray &key, const QString &filename) const;
889 QUrl mainScript() const;
890 QUrl configModel() const;
891 bool sourceValid() const;
892 /**
893 * @internal This constructor is to be used with the Package loading system.
894 *
895 * @param parent a QObject parent; you probably want to pass in 0
896 * @param args a list of strings containing two entries: the service id
897 * and the applet id
898 * @since 4.3
899 */
900 Applet(const QString &packagePath, uint appletId);
901
902 // TODO KF6: drop Q_PRIVATE_SLOT
903 Q_PRIVATE_SLOT(d, void cleanUpAndDelete())
904 Q_PRIVATE_SLOT(d, void askDestroy())
905 Q_PRIVATE_SLOT(d, void globalShortcutChanged())
906 Q_PRIVATE_SLOT(d, void propagateConfigChanged())
907 Q_PRIVATE_SLOT(d, void requestConfiguration())
908
909 AppletPrivate *const d;
910
911 // Corona needs to access setLaunchErrorMessage and init
912 friend class Corona;
913 friend class CoronaPrivate;
914 friend class Containment;
915 friend class ContainmentPrivate;
916 friend class AppletScript;
917 friend class AppletPrivate;
918 friend class AccessAppletJobPrivate;
919 friend class GraphicsViewAppletPrivate;
920 friend class PluginLoader;
921 friend class SvgPrivate;
922 friend class PlasmaQuick::AppletQuickItem;
923 friend class PlasmaQuick::ConfigModel;
924 friend class PlasmaQuick::ConfigModelPrivate;
925 friend class PlasmaQuick::ConfigViewPrivate;
926 friend class PlasmaQuick::ConfigView;
927 friend DeclarativeAppletScript;
928};
929
930Q_DECLARE_OPERATORS_FOR_FLAGS(Applet::Constraints)
931Q_DECLARE_OPERATORS_FOR_FLAGS(Applet::ConstraintHints)
932
933} // Plasma namespace
934
935#endif // multiple inclusion guard
The base Applet class.
Definition applet.h:64
void secondaryActivated()
Emitted when activation is requested due to, for example, middle click.
void contextualActionsChanged(const QList< QAction * > &actions)
Emitted when the list of contextual actions has changed.
void titleChanged(const QString &title)
Emitted when the title has changed.
void constraintHintsChanged(Plasma::Applet::ConstraintHints constraintHints)
Emitted when the constraint hints changed.
void internalActionsChanged(const QList< QAction * > &actions)
Emitted when the list of internal actions has changed.
Constraint
The Constraint enumeration lists the various constraints that Plasma objects have managed for them an...
Definition applet.h:213
void globalShortcutChanged(const QKeySequence &sequence)
Emitted when the global shortcut to activate this applet has chanaged.
void containmentChanged(Plasma::Containment *containment)
Emitted when the containment changes.
void effectiveBackgroundHintsChanged()
Emitted when the effective background hints have changed.
ConstraintHint
This enumeration lists the various hints that an applet can pass to its constraint regarding the way ...
Definition applet.h:231
void configNeedsSaving()
Emitted when an applet has changed values in its configuration and wishes for them to be saved at the...
void activated()
Emitted when activation is requested due to, for example, a global keyboard shortcut.
void appletDeleted(Plasma::Applet *applet)
Emitted when the applet is deleted.
void hasConfigurationInterfaceChanged(bool hasConfiguration)
Emitted when the applet gains or loses the ability to show a configuration interface.
void statusChanged(Plasma::Types::ItemStatus status)
Emitted when the applet status changes.
void containmentDisplayHintsChanged(Plasma::Types::ContainmentDisplayHints hints)
Emitted when the containment display hints change.
virtual QList< QAction * > contextualActions()
Returns a list of context-related QAction instances.
void iconChanged(const QString &icon)
Emitted when the icon name for the applet has changed.
void busyChanged(bool busy)
Emitted when the busy status has changed.
void destroyedChanged(bool destroyed)
Emitted when the applet has been scheduled for destruction or the destruction has been undone.
KConfigPropertyMap * configuration()
void immutabilityChanged(Plasma::Types::ImmutabilityType immutable)
Emitted when the immutability changes.
void backgroundHintsChanged()
Emitted when the background hints have changed.
void configurationRequiredChanged(bool needsConfig, const QString &reason)
Emitted when setConfigurationRequired was called.
void formFactorChanged(Plasma::Types::FormFactor formFactor)
Emitted when the formfactor changes.
void locationChanged(Plasma::Types::Location location)
Emitted when the location changes.
void userConfiguringChanged(bool configuring)
emitted when the config ui appears or disappears
void contextualActionsAboutToShow()
Emitted just before the contextual actions are about to show For instance just before the context men...
void userBackgroundHintsChanged()
Emitted when the user background hints have changed.
The base class for plugins that provide backgrounds and applet grouping containers.
Definition containment.h:47
A bookkeeping Scene for Plasma::Applets.
Definition corona.h:28
This is an abstract base class which defines an interface to which Plasma's Applet Loading logic can ...
Enums and constants used in Plasma.
Definition plasma.h:29
ImmutabilityType
Defines the immutability of items like applets, corona and containments they can be free to modify,...
Definition plasma.h:99
ItemStatus
Status of an applet.
Definition plasma.h:112
BackgroundHints
Description on how draw a background for the applet.
Definition plasma.h:127
Location
The Location enumeration describes where on screen an element, such as an Applet or its managing cont...
Definition plasma.h:81
FormFactor
The FormFactor enumeration describes how a Plasma::Applet should arrange itself.
Definition plasma.h:40
Q_SCRIPTABLE CaptureState status()
The EdgeEventForwarder class This class forwards edge events to be replayed within the given margin T...
Definition action.h:20
Namespace for everything in libplasma.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:04:40 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.