1/*
2 * Copyright 2006-2007 by Aaron Seigo <aseigo@kde.org>
3 * Copyright 2007 by Riccardo Iaconelli <riccardo@kde.org>
4 * Copyright 2008 by Ménard Alexis <darktears31@gmail.com>
5
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU Library General Public License as
8 * published by the Free Software Foundation; either version 2, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this program; if not, write to the
18 * Free Software Foundation, Inc.,
19 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20 */
21
22#ifndef PLASMA_APPLET_H
23#define PLASMA_APPLET_H
24
25#include <QtGui/QGraphicsItem>
26#include <QtGui/QGraphicsWidget>
27#include <QtGui/QIcon>
28
29#include <kconfiggroup.h>
30#include <kgenericfactory.h>
31#include <kplugininfo.h>
32#include <kshortcut.h>
33
34#include <plasma/configloader.h>
35#include <plasma/packagestructure.h>
36#include <plasma/plasma.h>
37#include <plasma/animator.h>
38#include <plasma/version.h>
39#include <plasma/framesvg.h>
40
41class QWidget;
42
43class KConfigDialog;
44class QGraphicsView;
45class KActionCollection;
46
47namespace Plasma
48{
49
50class AppletPrivate;
51class Containment;
52class Context;
53class DataEngine;
54class Extender;
55class ExtenderItem;
56class Package;
57
58
59/**
60 * @class Applet plasma/applet.h <Plasma/Applet>
61 *
62 * @short The base Applet class
63 *
64 * Applet provides several important roles for add-ons widgets in Plasma.
65 *
66 * First, it is the base class for the plugin system and therefore is the
67 * interface to applets for host applications. It also handles the life time
68 * management of data engines (e.g. all data engines accessed via
69 * Applet::dataEngine(const QString&) are properly deref'd on Applet
70 * destruction), background painting (allowing for consistent and complex
71 * look and feel in just one line of code for applets), loading and starting
72 * of scripting support for each applet, providing access to the associated
73 * plasmoid package (if any) and access to configuration data.
74 *
75 * See techbase.kde.org for tutorials on writing Applets using this class.
76 */
77class PLASMA_EXPORT Applet : public QGraphicsWidget
78{
79 Q_OBJECT
80 Q_PROPERTY(bool hasConfigurationInterface READ hasConfigurationInterface)
81 Q_PROPERTY(QString name READ name CONSTANT)
82 Q_PROPERTY(QString pluginName READ pluginName CONSTANT)
83 Q_PROPERTY(QString category READ category CONSTANT)
84 Q_PROPERTY(ImmutabilityType immutability READ immutability WRITE setImmutability)
85 Q_PROPERTY(bool hasFailedToLaunch READ hasFailedToLaunch WRITE setFailedToLaunch)
86 Q_PROPERTY(bool isBusy READ isBusy WRITE setBusy) //KDE5: remove
87 Q_PROPERTY(bool busy READ isBusy WRITE setBusy)
88 Q_PROPERTY(bool configurationRequired READ configurationRequired WRITE setConfigurationRequired)
89 Q_PROPERTY(QRectF geometry READ geometry WRITE setGeometry)
90 Q_PROPERTY(bool shouldConserveResources READ shouldConserveResources)
91 Q_PROPERTY(uint id READ id CONSTANT)
92 Q_PROPERTY(bool userConfiguring READ isUserConfiguring)
93 Q_PROPERTY(BackgroundHints backgroundHints READ backgroundHints WRITE setBackgroundHints)
94 Q_ENUMS(BackgroundHints)
95
96 public:
97 typedef QList<Applet*> List;
98 typedef QHash<QString, Applet*> Dict;
99
100 /**
101 * Description on how draw a background for the applet
102 */
103 enum BackgroundHint {
104 NoBackground = 0, /**< Not drawing a background under the
105 applet, the applet has its own implementation */
106 StandardBackground = 1, /**< The standard background from the theme is drawn */
107 TranslucentBackground = 2, /**< An alternate version of the background is drawn,
108 usually more translucent */
109 DefaultBackground = StandardBackground /**< Default settings:
110 both standard background */
111 };
112 Q_DECLARE_FLAGS(BackgroundHints, BackgroundHint)
113
114 ~Applet();
115
116 /**
117 * @return a package structure representing an Applet
118 */
119 static PackageStructure::Ptr packageStructure();
120
121 /**
122 * @return the id of this applet
123 */
124 uint id() const;
125
126 /**
127 * Returns the KConfigGroup to access the applets configuration.
128 *
129 * This config object will write to an instance
130 * specific config file named \<appletname\>\<instanceid\>rc
131 * in the Plasma appdata directory.
132 **/
133 KConfigGroup config() const;
134
135 /**
136 * Returns a config group with the name provided. This ensures
137 * that the group name is properly namespaced to avoid collision
138 * with other applets that may be sharing this config file
139 *
140 * @param group the name of the group to access
141 **/
142 KConfigGroup config(const QString &group) const;
143
144 /**
145 * Saves state information about this applet that will
146 * be accessed when next instantiated in the restore(KConfigGroup&) method.
147 *
148 * This method does not need to be reimplmented by Applet
149 * subclasses, but can be useful for Applet specializations
150 * (such as Containment) to do so.
151 *
152 * Applet subclasses may instead want to reimplement saveState().
153 **/
154 virtual void save(KConfigGroup &group) const;
155
156 /**
157 * Restores state information about this applet saved previously
158 * in save(KConfigGroup&).
159 *
160 * This method does not need to be reimplmented by Applet
161 * subclasses, but can be useful for Applet specializations
162 * (such as Containment) to do so.
163 **/
164 virtual void restore(KConfigGroup &group);
165
166 /**
167 * Returns a KConfigGroup object to be shared by all applets of this
168 * type.
169 *
170 * This config object will write to an applet-specific config object
171 * named plasma_\<appletname\>rc in the local config directory.
172 */
173 KConfigGroup globalConfig() const;
174
175 /**
176 * Returns the config skeleton object from this applet's package,
177 * if any.
178 *
179 * @return config skeleton object, or 0 if none
180 **/
181 ConfigLoader *configScheme() const;
182
183 /**
184 * Loads the given DataEngine
185 *
186 * Tries to load the data engine given by @p name. Each engine is
187 * only loaded once, and that instance is re-used on all subsequent
188 * requests.
189 *
190 * If the data engine was not found, an invalid data engine is returned
191 * (see DataEngine::isValid()).
192 *
193 * Note that you should <em>not</em> delete the returned engine.
194 *
195 * @param name Name of the data engine to load
196 * @return pointer to the data engine if it was loaded,
197 * or an invalid data engine if the requested engine
198 * could not be loaded
199 */
200 Q_INVOKABLE DataEngine *dataEngine(const QString &name) const;
201
202 /**
203 * Accessor for the associated Package object if any.
204 * Generally, only Plasmoids come in a Package.
205 *
206 * @return the Package object, or 0 if none
207 **/
208 const Package *package() const;
209
210 /**
211 * Returns the view this widget is visible on, or 0 if none can be found.
212 * @warning do NOT assume this will always return a view!
213 * a null view probably means that either plasma isn't finished loading, or your applet is
214 * on an activity that's not being shown anywhere.
215 */
216 QGraphicsView *view() const;
217
218 /**
219 * Maps a QRect from a view's coordinates to local coordinates.
220 * @param view the view from which rect should be mapped
221 * @param rect the rect to be mapped
222 */
223 QRectF mapFromView(const QGraphicsView *view, const QRect &rect) const;
224
225 /**
226 * Maps a QRectF from local coordinates to a view's coordinates.
227 * @param view the view to which rect should be mapped
228 * @param rect the rect to be mapped
229 */
230 QRect mapToView(const QGraphicsView *view, const QRectF &rect) const;
231
232 /**
233 * Reccomended position for a popup window like a menu or a tooltip
234 * given its size
235 * @param s size of the popup
236 * @returns reccomended position
237 */
238 QPoint popupPosition(const QSize &s) const;
239
240 /**
241 * @since 4.4
242 * Reccomended position for a popup window like a menu or a tooltip
243 * given its size
244 * @param s size of the popup
245 * @param alignment alignment of the popup, valid flags are Qt::AlignLeft, Qt::AlignRight and Qt::AlignCenter
246 * @returns reccomended position
247 */
248 QPoint popupPosition(const QSize &s, Qt::AlignmentFlag alignment) const;
249
250 /**
251 * Called when any of the geometry constraints have been updated.
252 * This method calls constraintsEvent, which may be reimplemented,
253 * once the Applet has been prepared for updating the constraints.
254 *
255 * @param constraints the type of constraints that were updated
256 */
257 void updateConstraints(Plasma::Constraints constraints = Plasma::AllConstraints);
258
259 /**
260 * Returns the current form factor the applet is being displayed in.
261 *
262 * @see Plasma::FormFactor
263 */
264 virtual FormFactor formFactor() const;
265
266 /**
267 * Returns the location of the scene which is displaying applet.
268 *
269 * @see Plasma::Location
270 */
271 virtual Location location() const;
272
273 /**
274 * Returns the workspace context which the applet is operating in
275 */
276 Context *context() const;
277
278 /**
279 * @return the preferred aspect ratio mode for placement and resizing
280 */
281 Plasma::AspectRatioMode aspectRatioMode() const;
282
283 /**
284 * Sets the preferred aspect ratio mode for placement and resizing
285 */
286 void setAspectRatioMode(Plasma::AspectRatioMode);
287
288 /**
289 * Returns a list of all known applets.
290 * This may skip applets based on security settings and ExcludeCategories in the application's config.
291 *
292 * @param category Only applets matchin this category will be returned.
293 * Useful in conjunction with knownCategories.
294 * If "Misc" is passed in, then applets without a
295 * Categories= entry are also returned.
296 * If an empty string is passed in, all applets are
297 * returned.
298 * @param parentApp the application to filter applets on. Uses the
299 * X-KDE-ParentApp entry (if any) in the plugin info.
300 * The default value of QString() will result in a
301 * list containing only applets not specifically
302 * registered to an application.
303 * @return list of applets
304 **/
305 static KPluginInfo::List listAppletInfo(const QString &category = QString(),
306 const QString &parentApp = QString());
307
308 /**
309 * Returns a list of all known applets associated with a certain mimetype.
310 *
311 * @return list of applets
312 **/
313 static KPluginInfo::List listAppletInfoForMimetype(const QString &mimetype);
314
315 /**
316 * Returns a list of all known applets associated with a certain URL.
317 *
318 * @since 4.4
319 * @return list of applets
320 **/
321 static KPluginInfo::List listAppletInfoForUrl(const QUrl &url);
322
323 /**
324 * Returns a list of all the categories used by installed applets.
325 *
326 * @param parentApp the application to filter applets on. Uses the
327 * X-KDE-ParentApp entry (if any) in the plugin info.
328 * The default value of QString() will result in a
329 * list containing only applets not specifically
330 * registered to an application.
331 * @return list of categories
332 * @param visibleOnly true if it should only return applets that are marked as visible
333 */
334 static QStringList listCategories(const QString &parentApp = QString(),
335 bool visibleOnly = true);
336
337 /**
338 * Sets the list of custom categories that are used in addition to the default
339 * set of categories known to libplasma for Applets.
340 * @param categories a list of categories
341 * @since 4.3
342 */
343 void setCustomCategories(const QStringList &categories);
344
345 /**
346 * @return the list of custom categories known to libplasma
347 * @since 4.3
348 */
349 QStringList customCategories();
350
351 /**
352 * Attempts to load an applet from a package
353 *
354 * Returns a pointer to the applet if successful.
355 * The caller takes responsibility for the applet, including
356 * deleting it when no longer needed.
357 *
358 * @param path the path to the package
359 * @param appletId unique ID to assign the applet, or zero to have one
360 * assigned automatically.
361 * @param args to send the applet extra arguments
362 * @return a pointer to the loaded applet, or 0 on load failure
363 * @since 4.3
364 **/
365 static Applet *loadPlasmoid(const QString &path, uint appletId = 0,
366 const QVariantList &args = QVariantList());
367
368 /**
369 * Attempts to load an applet
370 *
371 * Returns a pointer to the applet if successful.
372 * The caller takes responsibility for the applet, including
373 * deleting it when no longer needed.
374 *
375 * @param name the plugin name, as returned by KPluginInfo::pluginName()
376 * @param appletId unique ID to assign the applet, or zero to have one
377 * assigned automatically.
378 * @param args to send the applet extra arguments
379 * @return a pointer to the loaded applet, or 0 on load failure
380 **/
381 static Applet *load(const QString &name, uint appletId = 0,
382 const QVariantList &args = QVariantList());
383
384 /**
385 * Attempts to load an applet
386 *
387 * Returns a pointer to the applet if successful.
388 * The caller takes responsibility for the applet, including
389 * deleting it when no longer needed.
390 *
391 * @param info KPluginInfo object for the desired applet
392 * @param appletId unique ID to assign the applet, or zero to have one
393 * assigned automatically.
394 * @param args to send the applet extra arguments
395 * @return a pointer to the loaded applet, or 0 on load failure
396 **/
397 static Applet *load(const KPluginInfo &info, uint appletId = 0,
398 const QVariantList &args = QVariantList());
399
400 /**
401 * Get the category of the given applet
402 *
403 * @param applet a KPluginInfo object for the applet
404 */
405 static QString category(const KPluginInfo &applet);
406
407 /**
408 * Get the category of the given applet
409 *
410 * @param appletName the name of the applet
411 */
412 static QString category(const QString &appletName);
413
414 /**
415 * This method is called when the interface should be painted.
416 *
417 * @param painter the QPainter to use to do the paintiner
418 * @param option the style options object
419 * @param contentsRect the rect to paint within; automatically adjusted for
420 * the background, if any
421 **/
422 virtual void paintInterface(QPainter *painter,
423 const QStyleOptionGraphicsItem *option,
424 const QRect &contentsRect);
425
426 /**
427 * Returns the user-visible name for the applet, as specified in the
428 * .desktop file.
429 *
430 * @return the user-visible name for the applet.
431 **/
432 QString name() const;
433
434 /**
435 * @return the font currently set for this widget
436 **/
437 QFont font() const;
438
439 /**
440 * Returns the plugin name for the applet
441 */
442 QString pluginName() const;
443
444 /**
445 * Whether the applet should conserve resources. If true, try to avoid doing stuff which
446 * is computationally heavy. Try to conserve power and resources.
447 *
448 * @return true if it should conserve resources, false if it does not.
449 */
450 bool shouldConserveResources() const;
451
452 /**
453 * Returns the icon related to this applet
454 **/
455 QString icon() const;
456
457 /**
458 * Returns the category the applet is in, as specified in the
459 * .desktop file.
460 */
461 QString category() const;
462
463 /**
464 * @return The type of immutability of this applet
465 */
466 ImmutabilityType immutability() const;
467
468 void paintWindowFrame(QPainter *painter,
469 const QStyleOptionGraphicsItem *option, QWidget *widget);
470
471 /**
472 * If for some reason, the applet fails to get up on its feet (the
473 * library couldn't be loaded, necessary hardware support wasn't found,
474 * etc..) this method returns true
475 **/
476 bool hasFailedToLaunch() const;
477
478 /**
479 * @return true if the applet is busy and is showing an indicator widget for that
480 */
481 bool isBusy() const;
482
483 /**
484 * @return true if the applet currently needs to be configured,
485 * otherwise, false
486 */
487 bool configurationRequired() const;
488
489 /**
490 * @return true if this plasmoid provides a GUI configuration
491 **/
492 bool hasConfigurationInterface() const;
493
494 /**
495 * Returns a list of context-related QAction instances.
496 *
497 * This is used e.g. within the \a DesktopView to display a
498 * contextmenu.
499 *
500 * @return A list of actions. The default implementation returns an
501 * empty list.
502 **/
503 virtual QList<QAction*> contextualActions();
504
505 /**
506 * Returns the QAction with the given name from our collection
507 */
508 Q_INVOKABLE QAction *action(QString name) const;
509
510 /**
511 * Adds the action to our collection under the given name
512 */
513 void addAction(QString name, QAction *action);
514
515 /**
516 * Sets the BackgroundHints for this applet @see BackgroundHint
517 *
518 * @param hints the BackgroundHint combination for this applet
519 */
520 void setBackgroundHints(const BackgroundHints hints);
521
522 /**
523 * @return BackgroundHints flags combination telling if the standard background is shown
524 * and if it has a drop shadow
525 */
526 BackgroundHints backgroundHints() const;
527
528 /**
529 * @return true if this Applet is currently being used as a Containment, false otherwise
530 */
531 bool isContainment() const;
532
533 /**
534 * This method returns screen coordinates for the widget; this method can be somewhat
535 * expensive and should ONLY be called when screen coordinates are required. For
536 * example when positioning top level widgets on top of the view to create the
537 * appearance of unit. This should NOT be used for popups (@see popupPosition) or
538 * for normal widget use (use Plasma:: widgets or QGraphicsProxyWidget instead).
539 *
540 * @return a rect of the applet in screen coordinates.
541 */
542 QRect screenRect() const;
543
544 /**
545 * Reimplemented from QGraphicsItem
546 **/
547 int type() const;
548 enum {
549 Type = Plasma::AppletType
550 };
551
552 /**
553 * @return the Containment, if any, this applet belongs to
554 **/
555 Containment *containment() const;
556
557 /**
558 * Sets the global shorcut to associate with this widget.
559 */
560 void setGlobalShortcut(const KShortcut &shortcut);
561
562 /**
563 * @return the global shortcut associated with this wiget, or
564 * an empty shortcut if no global shortcut is associated.
565 */
566 KShortcut globalShortcut() const;
567
568 /**
569 * @return true is there is a popup assoiated with this Applet
570 * showing, such as the dialog of a PopupApplet. May be reimplemented
571 * for custom popup implementations.
572 */
573 virtual bool isPopupShowing() const;
574
575 /**
576 * associate actions with this widget, including ones added after this call.
577 * needed to make keyboard shortcuts work.
578 */
579 virtual void addAssociatedWidget(QWidget *widget);
580
581 /**
582 * un-associate actions from this widget, including ones added after this call.
583 * needed to make keyboard shortcuts work.
584 */
585 virtual void removeAssociatedWidget(QWidget *widget);
586
587 /**
588 * Gets called when an extender item has to be initialized after a plasma restart. If you
589 * create ExtenderItems in your applet, you should implement this function to again create
590 * the widget that should be shown in this extender item. This function might look something
591 * like this:
592 *
593 * @code
594 * SuperCoolWidget *widget = new SuperCoolWidget();
595 * dataEngine("engine")->connectSource(item->config("dataSourceName"), widget);
596 * item->setWidget(widget);
597 * @endcode
598 *
599 * You can also add one or more custom qactions to this extender item in this function.
600 *
601 * Note that by default, not all ExtenderItems are persistent. Only items that are detached,
602 * will have their configuration stored when plasma exits.
603 */
604 virtual void initExtenderItem(ExtenderItem *item);
605
606 /**
607 * @param parent the QGraphicsItem this applet is parented to
608 * @param serviceId the name of the .desktop file containing the
609 * information about the widget
610 * @param appletId a unique id used to differentiate between multiple
611 * instances of the same Applet type
612 */
613 explicit Applet(QGraphicsItem *parent = 0,
614 const QString &serviceId = QString(),
615 uint appletId = 0);
616
617 /**
618 * @param parent the QGraphicsItem this applet is parented to
619 * @param info the plugin information object for this Applet
620 * @param appletId a unique id used to differentiate between multiple
621 * instances of the same Applet type
622 * @since 4.6
623 */
624 explicit Applet(const KPluginInfo &info, QGraphicsItem *parent = 0, uint appletId = 0);
625
626 /**
627 * @param parent the QGraphicsItem this applet is parented to
628 * @param serviceId the name of the .desktop file containing the
629 * information about the widget
630 * @param appletId a unique id used to differentiate between multiple
631 * instances of the same Applet type
632 * @param args a list of strings containing two entries: the service id
633 * and the applet id
634 * @since 4.3
635 */
636 explicit Applet(QGraphicsItem *parent,
637 const QString &serviceId,
638 uint appletId,
639 const QVariantList &args);
640
641
642 /**
643 * @return true if destroy() was called; useful for Applets which should avoid
644 * certain tasks if they are about to be deleted permanently
645 */
646 bool destroyed() const;
647
648 /**
649 * Reimplement this method so provide a configuration interface,
650 * parented to the supplied widget. Ownership of the widgets is passed
651 * to the parent widget.
652 *
653 * Typically one would add custom pages to the config dialog @p parent
654 * and then connect to the applyClicked() and okClicked() signals
655 * or @p parent to react on config changes:
656 *
657 * @code
658 * connect(parent, SIGNAL(applyClicked()), this, SLOT(myConfigAccepted()));
659 * connect(parent, SIGNAL(okClicked()), this, SLOT(myConfigAccepted()));
660 * @endcode
661 *
662 * With this approach it makes sense to store the custom pages in member
663 * variables to make their fields accessible from the myConfigAccepted()
664 * slot.
665 *
666 * Use config() to store your configuration.
667 *
668 * @param parent the dialog which is the parent of the configuration
669 * widgets
670 */
671 virtual void createConfigurationInterface(KConfigDialog *parent);
672
673 /**
674 * Returns true if the applet is allowed to perform functions covered by the given constraint
675 * eg. hasAuthorization("FileDialog") returns true if applets are allowed to show filedialogs.
676 * @since 4.3
677 */
678 bool hasAuthorization(const QString &constraint) const;
679
680 /**
681 * Sets an application associated to this applet, that will be
682 * regarded as a full view of what is represented in the applet
683 *
684 * @param string the name of the application. it can be
685 * \li a name understood by KService::serviceByDesktopName
686 * (e.g. "konqueror")
687 * \li a command in $PATH
688 * \li or an absolute path to an executable
689 * @since 4.4
690 */
691 void setAssociatedApplication(const QString &string);
692
693 /**
694 * Sets a list of urls associated to this application,
695 * they will be used as parameters for the associated application
696 * @see setAssociatedApplication()
697 *
698 * @param urls
699 */
700 void setAssociatedApplicationUrls(const KUrl::List &urls);
701
702 /**
703 * @return the application associated to this applet
704 * @since 4.4
705 */
706 QString associatedApplication() const;
707
708 /**
709 * @return the urls associated to this applet
710 * @since 4.4
711 */
712 KUrl::List associatedApplicationUrls() const;
713
714 /**
715 * @return true if the applet has a valid associated application or urls
716 * @since 4.4
717 */
718 bool hasValidAssociatedApplication() const;
719
720 Q_SIGNALS:
721 /**
722 * This signal indicates that an application launch, window
723 * creation or window focus event was triggered. This is used, for instance,
724 * to ensure that the Dashboard view in Plasma Desktop hides when such an event is
725 * triggered by an item it is displaying.
726 */
727 void releaseVisualFocus();
728
729#if QT_VERSION >= 0x040700
730 protected:
731 void geometryChanged(); // in QGraphicsWidget now; preserve BC
732#else
733 /**
734 * Emitted whenever the applet makes a geometry change, so that views
735 * can coordinate themselves with these changes if they desire.
736 */
737 void geometryChanged();
738#endif
739
740 Q_SIGNALS:
741 /**
742 * Emitted when the user completes a transformation of the applet.
743 */
744 void appletTransformedByUser();
745
746 /**
747 * Emitted when the applet changes its own geometry or transform.
748 */
749 void appletTransformedItself();
750
751 /**
752 * Emitted by Applet subclasses when they change a sizeHint and wants to announce the change
753 */
754 void sizeHintChanged(Qt::SizeHint which);
755
756 /**
757 * Emitted when an applet has changed values in its configuration
758 * and wishes for them to be saved at the next save point. As this implies
759 * disk activity, this signal should be used with care.
760 *
761 * @note This does not need to be emitted from saveState by individual
762 * applets.
763 */
764 void configNeedsSaving();
765
766 /**
767 * Emitted when activation is requested due to, for example, a global
768 * keyboard shortcut. By default the wiget is given focus.
769 */
770 void activate();
771
772 /**
773 * Emitted when the user clicked on a button of the message overlay
774 *
775 * @see showMessage
776 * @see Plasma::MessageButton
777 * @since 4.3
778 */
779 void messageButtonPressed(const Plasma::MessageButton button);
780
781 /**
782 * Emitted when the applet is deleted
783 */
784 void appletDestroyed(Plasma::Applet *applet);
785
786 /**
787 * Emitted when the applet status changes
788 * @since 4.4
789 */
790 void newStatus(Plasma::ItemStatus status);
791
792 /**
793 * Emitted when an ExtenderItem in a scripting applet needs to be initialized
794 */
795 void extenderItemRestored(Plasma::ExtenderItem *item);
796
797 /**
798 * Emitted when the immutability changes
799 * @since 4.4
800 */
801 void immutabilityChanged(Plasma::ImmutabilityType immutable);
802
803 public Q_SLOTS:
804 /**
805 * Sets the immutability type for this applet (not immutable,
806 * user immutable or system immutable)
807 * @param immutable the new immutability type of this applet
808 */
809 void setImmutability(const ImmutabilityType immutable);
810
811 /**
812 * Destroys the applet; it will be removed nicely and deleted.
813 * Its configuration will also be deleted.
814 */
815 virtual void destroy();
816
817 /**
818 * Lets the user interact with the plasmoid options.
819 * Called when the user selects the configure entry
820 * from the context menu.
821 *
822 * Unless there is good reason for overriding this method,
823 * Applet subclasses should actually override createConfigurationInterface
824 * instead. A good example of when this isn't plausible is
825 * when using a dialog prepared by another library, such
826 * as KPropertiesDialog from libkfile.
827 * You probably want to call showConfigurationInterface(QWidget*)
828 * with the custom widget you created to actually show your interface
829 */
830 virtual void showConfigurationInterface();
831
832 /**
833 * Actually show your custom configuration interface
834 * Use this only if you reimplemented showConfigurationInterface()
835 *
836 * @param widget the widget representing your configuration interface
837 *
838 * @since 4.5
839 */
840 void showConfigurationInterface(QWidget *widget);
841
842 /**
843 * @return true when the configuration interface is being shown
844 * @since 4.5
845 */
846 bool isUserConfiguring() const;
847
848 /**
849 * Causes this applet to raise above all other applets.
850 */
851 void raise();
852
853 /**
854 * Causes this applet to lower below all the other applets.
855 */
856 void lower();
857
858 /**
859 * Sends all pending contraints updates to the applet. Will usually
860 * be called automatically, but can also be called manually if needed.
861 */
862 void flushPendingConstraintsEvents();
863
864 /**
865 * This method is called once the applet is loaded and added to a Corona.
866 * If the applet requires a QGraphicsScene or has an particularly intensive
867 * set of initialization routines to go through, consider implementing it
868 * in this method instead of the constructor.
869 *
870 * Note: paintInterface may get called before init() depending on initialization
871 * order. Painting is managed by the canvas (QGraphisScene), and may schedule a
872 * paint event prior to init() being called.
873 **/
874 virtual void init();
875
876 /**
877 * Called when applet configuration values have changed.
878 */
879 virtual void configChanged();
880
881 /**
882 * Shows a busy indicator that overlays the applet
883 * @param busy show or hide the busy indicator
884 */
885 void setBusy(bool busy);
886
887 /**
888 * @return the list of arguments which the applet was called with
889 * @since KDE4.3
890 */
891 QVariantList startupArguments() const;
892
893 /**
894 * @return the status of the applet
895 * @since 4.4
896 */
897 ItemStatus status() const;
898
899 /**
900 * sets the status for this applet
901 * @since 4.4
902 */
903 void setStatus(const ItemStatus stat);
904
905 /**
906 * Publishes and optionally announces this applet on the network for remote access.
907 * @param methods the methods to use for announcing this applet.
908 * @param resourceName the name under which this applet will be published (has to be unique
909 * for each machine)
910 */
911 void publish(Plasma::AnnouncementMethods methods, const QString &resourceName);
912
913 void unpublish();
914
915 bool isPublished() const;
916
917 /**
918 * Open the application associated to this applet, if it's not set
919 * but some urls are, open those urls with the proper application
920 * for their mimetype
921 * @see setAssociatedApplication()
922 * @see setAssociatedApplicationUrls()
923 * @since 4.4
924 */
925 void runAssociatedApplication();
926
927 protected:
928 /**
929 * This constructor is to be used with the plugin loading systems
930 * found in KPluginInfo and KService. The argument list is expected
931 * to have two elements: the KService service ID for the desktop entry
932 * and an applet ID which must be a base 10 number.
933 *
934 * @param parent a QObject parent; you probably want to pass in 0
935 * @param args a list of strings containing two entries: the service id
936 * and the applet id
937 */
938 Applet(QObject *parent, const QVariantList &args);
939
940 /**
941 * Call this method when the applet fails to launch properly. An
942 * optional reason can be provided.
943 *
944 * Not that all children items will be deleted when this method is
945 * called. If you have pointers to these items, you will need to
946 * reset them after calling this method.
947 *
948 * @param failed true when the applet failed, false when it succeeded
949 * @param reason an optional reason to show the user why the applet
950 * failed to launch
951 **/
952 void setFailedToLaunch(bool failed, const QString &reason = QString());
953
954 /**
955 * When called, the Applet should write any information needed as part
956 * of the Applet's running state to the configuration object in config()
957 * and/or globalConfig().
958 *
959 * Applets that always sync their settings/state with the config
960 * objects when these settings/states change do not need to reimplement
961 * this method.
962 **/
963 virtual void saveState(KConfigGroup &config) const;
964
965 /**
966 * Sets whether or not this applet provides a user interface for
967 * configuring the applet.
968 *
969 * It defaults to false, and if true is passed in you should
970 * also reimplement createConfigurationInterface()
971 *
972 * @param hasInterface whether or not there is a user interface available
973 **/
974 void setHasConfigurationInterface(bool hasInterface);
975
976 /**
977 * When the applet needs to be configured before being usable, this
978 * method can be called to show a standard interface prompting the user
979 * to configure the applet
980 *
981 * @param needsConfiguring true if the applet needs to be configured,
982 * or false if it doesn't
983 * @param reason a translated message for the user explaining that the
984 * applet needs configuring; this should note what needs
985 * to be configured
986 */
987 void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());
988
989 /**
990 * Shows a message as an overlay of the applet: the message has an
991 * icon, text and (optional) buttons
992 *
993 * @param icon the icon that will be shown
994 * @param message the message string that will be shown.
995 * If the message is empty nothng will be shown
996 * and if there was a message already it will be hidden
997 * @param buttons an OR combination of all the buttons needed
998 *
999 * @see Plasma::MessageButtons
1000 * @see messageButtonPressed
1001 * @since 4.3
1002 */
1003 void showMessage(const QIcon &icon, const QString &message, const Plasma::MessageButtons buttons);
1004
1005 /**
1006 * Called when any of the constraints for the applet have been updated. These constraints
1007 * range from notifying when the applet has officially "started up" to when geometry changes
1008 * to when the form factor changes.
1009 *
1010 * Each constraint that has been changed is passed in the constraints flag.
1011 * All of the constraints and how they work is documented in the @see Plasma::Constraints
1012 * enumeration.
1013 *
1014 * On applet creation, this is always called prior to painting and can be used as an
1015 * opportunity to layout the widget, calculate sizings, etc.
1016 *
1017 * Do not call update() from this method; an update() will be triggered
1018 * at the appropriate time for the applet.
1019 *
1020 * @param constraints the type of constraints that were updated
1021 * @property constraint
1022 */
1023 virtual void constraintsEvent(Plasma::Constraints constraints);
1024
1025 /**
1026 * Register the widgets that manage mouse clicks but you still want
1027 * to be able to drag the applet around when holding the mouse pointer
1028 * on that widget.
1029 *
1030 * Calling this results in an eventFilter being places on the widget.
1031 *
1032 * @param item the item to watch for mouse move
1033 */
1034 void registerAsDragHandle(QGraphicsItem *item);
1035
1036 /**
1037 * Unregister a widget registered with registerAsDragHandle.
1038 *
1039 * @param item the item to unregister
1040 */
1041 void unregisterAsDragHandle(QGraphicsItem *item);
1042
1043 /**
1044 * @param item the item to look for if it is registered or not
1045 * @return true if it is registered, false otherwise
1046 */
1047 bool isRegisteredAsDragHandle(QGraphicsItem *item);
1048
1049 /**
1050 * @return the extender of this applet.
1051 */
1052 Extender *extender() const;
1053
1054 /**
1055 * @internal event filter; used for focus watching
1056 **/
1057 bool eventFilter(QObject *o, QEvent *e);
1058
1059 /**
1060 * @internal scene event filter; used to manage applet dragging
1061 */
1062 bool sceneEventFilter (QGraphicsItem *watched, QEvent *event);
1063
1064 /**
1065 * @internal manage the mouse movement to drag the applet around
1066 */
1067 void mouseMoveEvent(QGraphicsSceneMouseEvent *event);
1068
1069 /**
1070 * Reimplemented from QGraphicsItem
1071 */
1072 void focusInEvent(QFocusEvent *event);
1073
1074 /**
1075 * Reimplemented from QGraphicsItem
1076 */
1077 void resizeEvent(QGraphicsSceneResizeEvent *event);
1078
1079 /**
1080 * Reimplemented from QGraphicsItem
1081 */
1082 QVariant itemChange(GraphicsItemChange change, const QVariant &value);
1083
1084 /**
1085 * Reimplemented from QGraphicsItem
1086 */
1087 QPainterPath shape() const;
1088
1089 /**
1090 * Reimplemented from QGraphicsLayoutItem
1091 */
1092 QSizeF sizeHint(Qt::SizeHint which, const QSizeF & constraint = QSizeF()) const;
1093
1094 /**
1095 * Reimplemented from QGraphicsLayoutItem
1096 */
1097 void hoverEnterEvent(QGraphicsSceneHoverEvent *event);
1098
1099 /**
1100 * Reimplemented from QGraphicsLayoutItem
1101 */
1102 void hoverLeaveEvent(QGraphicsSceneHoverEvent *event);
1103
1104 /**
1105 * Reimplemented from QObject
1106 */
1107 void timerEvent (QTimerEvent *event);
1108
1109
1110 private:
1111 /**
1112 * @internal This constructor is to be used with the Package loading system.
1113 *
1114 * @param parent a QObject parent; you probably want to pass in 0
1115 * @param args a list of strings containing two entries: the service id
1116 * and the applet id
1117 * @since 4.3
1118 */
1119 Applet(const QString &packagePath, uint appletId, const QVariantList &args);
1120
1121 Q_PRIVATE_SLOT(d, void setFocus())
1122 Q_PRIVATE_SLOT(d, void themeChanged())
1123 Q_PRIVATE_SLOT(d, void cleanUpAndDelete())
1124 Q_PRIVATE_SLOT(d, void selectItemToDestroy())
1125 Q_PRIVATE_SLOT(d, void updateRect(const QRectF& rect))
1126 Q_PRIVATE_SLOT(d, void destroyMessageOverlay())
1127 Q_PRIVATE_SLOT(d, void configDialogFinished())
1128 Q_PRIVATE_SLOT(d, void updateShortcuts())
1129 Q_PRIVATE_SLOT(d, void publishCheckboxStateChanged(int state))
1130 Q_PRIVATE_SLOT(d, void globalShortcutChanged())
1131 Q_PRIVATE_SLOT(d, void propagateConfigChanged())
1132 Q_PRIVATE_SLOT(d, void handleDisappeared(AppletHandle *handle))
1133
1134 /**
1135 * Reimplemented from QGraphicsItem
1136 **/
1137 void paint(QPainter *painter, const QStyleOptionGraphicsItem *option, QWidget *widget = 0);
1138
1139 AppletPrivate *const d;
1140
1141 //Corona needs to access setFailedToLaunch and init
1142 friend class Corona;
1143 friend class CoronaPrivate;
1144 friend class Containment;
1145 friend class ContainmentPrivate;
1146 friend class AppletScript;
1147 friend class AppletHandle;
1148 friend class AppletPrivate;
1149 friend class AccessAppletJobPrivate;
1150 friend class PluginLoader;
1151 friend class PopupApplet;
1152 friend class PopupAppletPrivate;
1153 friend class AssociatedApplicationManager;
1154
1155 friend class Extender;
1156 friend class ExtenderGroup;
1157 friend class ExtenderGroupPrivate;
1158 friend class ExtenderPrivate;
1159 friend class ExtenderItem;
1160};
1161
1162} // Plasma namespace
1163
1164Q_DECLARE_OPERATORS_FOR_FLAGS(Plasma::Applet::BackgroundHints)
1165
1166/**
1167 * Register an applet when it is contained in a loadable module
1168 */
1169#define K_EXPORT_PLASMA_APPLET(libname, classname) \
1170K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \
1171K_EXPORT_PLUGIN(factory("plasma_applet_" #libname)) \
1172K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION)
1173
1174#endif // multiple inclusion guard
1175