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 | |
41 | class QWidget; |
42 | |
43 | class KConfigDialog; |
44 | class QGraphicsView; |
45 | class KActionCollection; |
46 | |
47 | namespace Plasma |
48 | { |
49 | |
50 | class AppletPrivate; |
51 | class Containment; |
52 | class Context; |
53 | class DataEngine; |
54 | class Extender; |
55 | class ExtenderItem; |
56 | class 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 | */ |
77 | class 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 (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 (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 () 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 | |
1164 | Q_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) \ |
1170 | K_PLUGIN_FACTORY(factory, registerPlugin<classname>();) \ |
1171 | K_EXPORT_PLUGIN(factory("plasma_applet_" #libname)) \ |
1172 | K_EXPORT_PLUGIN_VERSION(PLASMA_VERSION) |
1173 | |
1174 | #endif // multiple inclusion guard |
1175 | |