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