Plasma

containment.h
1 /*
2  SPDX-FileCopyrightText: 2007 Aaron Seigo <[email protected]>
3  SPDX-FileCopyrightText: 2008 Ménard Alexis <[email protected]>
4  SPDX-FileCopyrightText: 2009 Chani Armitage <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef PLASMA_CONTAINMENT_H
10 #define PLASMA_CONTAINMENT_H
11 
12 #include <KPluginFactory>
13 #include <KSharedConfig>
14 #include <plasma/applet.h>
15 
16 namespace Plasma
17 {
18 class DataEngine;
19 class Package;
20 class Corona;
21 class ContainmentActions;
22 class ContainmentPrivate;
23 
24 /**
25  * @class Containment plasma/containment.h <Plasma/Containment>
26  *
27  * @short The base class for plugins that provide backgrounds and applet grouping containers
28  *
29  * Containment objects provide the means to group applets into functional sets.
30  * They also provide the following:
31  *
32  * creation of focusing event
33  * - drawing of the background image (which can be interactive)
34  * - form factors (e.g. panel, desktop, full screen, etc)
35  * - applet layout management
36  *
37  * Since containment is actually just a Plasma::Applet, all the techniques used
38  * for writing the visual presentation of Applets is applicable to Containtments.
39  * Containments are differentiated from Applets by being marked with the ServiceType
40  * of Plasma/Containment. Plugins registered with both the Applet and the Containment
41  * ServiceTypes can be loaded for us in either situation.
42  *
43  * See techbase.kde.org for a tutorial on writing Containments using this class.
44  */
45 class PLASMA_EXPORT Containment : public Applet
46 {
47  Q_OBJECT
48  Q_PROPERTY(QString wallpaper READ wallpaper WRITE setWallpaper NOTIFY wallpaperChanged)
49  Q_PROPERTY(bool isUiReady READ isUiReady NOTIFY uiReadyChanged)
50 
51 public:
52  /**
53  * This constructor can be used with the KCoreAddons plugin loading system.
54  * The argument list is expected to have contain the KPackage of the applet,
55  * the meta data file path (for compatibility) and an applet ID which must be a base 10 number.
56  *
57  * @param parent a QObject parent; you probably want to pass in 0
58  * @param data, KPluginMetaData used to create this plugin
59  * @param args a list of strings containing the applet id
60  * @since 5.86
61  */
62  explicit Containment(QObject *parentObject, const KPluginMetaData &data, const QVariantList &args);
63 
64 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 86)
65  /**
66  * @param parent the QObject this applet is parented to
67  * @param serviceId the name of the .desktop file containing the
68  * information about the widget
69  * @param containmentId a unique id used to differentiate between multiple
70  * instances of the same Applet type
71  * @deprecated Since 5.86, use Containment(QObject *, KPluginMetaData, QVariantList) instead
72  */
73  PLASMA_DEPRECATED_VERSION(5, 86, "use Containment(QObject *, KPluginMetaData, QVariantList) instead")
74  explicit Containment(QObject *parent = nullptr, const QString &serviceId = QString(), uint containmentId = 0);
75 #endif
76 
77 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 86)
78  /**
79  * This constructor is to be used with the plugin loading systems
80  * found in KPluginInfo and KService. The argument list is expected
81  * to have two elements: the KService service ID for the desktop entry
82  * and an applet ID which must be a base 10 number.
83  *
84  * @param parent a QObject parent; you probably want to pass in 0
85  * @param args a list of strings containing two entries: the service id
86  * and the applet id
87  * @deprecated Since 5.86, use Containment(QObject *, KPluginMetaData, QVariantList) instead
88  */
89  PLASMA_DEPRECATED_VERSION(5, 86, "use Containment(QObject *, KPluginMetaData, QVariantList) instead")
90  Containment(QObject *parent, const QVariantList &args);
91 #endif
92 
93  ~Containment() override;
94 
95  /**
96  * Reimplemented from Applet
97  */
98  void init() override;
99 
100  /**
101  * Returns the type of containment
102  */
103  Plasma::Types::ContainmentType containmentType() const;
104 
105  /**
106  * Returns the Corona (if any) that this Containment is hosted by
107  */
108  Corona *corona() const;
109 
110  /**
111  * Adds an applet to this Containment
112  *
113  * @param name the plugin name for the applet, as given by
114  * KPluginInfo::pluginName()
115  * @param args argument list to pass to the plasmoid
116  * @param geometry where to place the applet, or to auto-place it if an invalid
117  * is provided
118  *
119  * @return a pointer to the applet on success, or 0 on failure
120  */
121  Applet *createApplet(const QString &name, const QVariantList &args = QVariantList());
122 
123  /**
124  * Add an existing applet to this Containment
125  *
126  * @param applet the applet that should be added
127  * @param pos the containment-relative position
128  */
129  void addApplet(Applet *applet);
130 
131  /**
132  * @return the applets currently in this Containment
133  */
134  QList<Applet *> applets() const;
135 
136  /**
137  * @return the screen number this containment is serving as the desktop for
138  * or -1 if none
139  */
140  int screen() const;
141 
142  /**
143  * @return the last screen number this containment had
144  * only returns -1 if it's never ever been on a screen
145  * @since 4.5
146  */
147  int lastScreen() const;
148 
149  /**
150  * @reimp
151  * @sa Applet::save(KConfigGroup &)
152  */
153  void save(KConfigGroup &group) const override;
154 
155  /**
156  * @reimp
157  * @sa Applet::restore(KConfigGroup &)
158  */
159  void restore(KConfigGroup &group) override;
160 
161  /**
162  * Sets wallpaper plugin.
163  *
164  * @param pluginName the name of the wallpaper to attempt to load
165  */
166  void setWallpaper(const QString &pluginName);
167 
168  /**
169  * Return wallpaper plugin.
170  */
171  QString wallpaper() const;
172 
173  /**
174  * Sets the current activity by id
175  *
176  * @param activity the id of the activity
177  */
178  void setActivity(const QString &activityId);
179 
180  /**
181  * @return the current activity id associated with this containment
182  */
183  QString activity() const;
184 
185  /**
186  * Sets a containmentactions plugin.
187  *
188  * @param trigger the mouse button (and optional modifier) to associate the plugin with
189  * @param pluginName the name of the plugin to attempt to load. blank = set no plugin.
190  * @since 4.4
191  */
192  void setContainmentActions(const QString &trigger, const QString &pluginName);
193 
194  /**
195  * @return All the loaded containment action plugins, indexed by trigger name
196  * @since 5.0
197  */
198  QHash<QString, ContainmentActions *> &containmentActions();
199 
200  /**
201  * @returns true when the ui of this containment is fully loaded, as well the ui of every applet in it
202  */
203  bool isUiReady() const;
204 
205 Q_SIGNALS:
206  /**
207  * This signal is emitted when a new applet is added in the containment
208  * It may happen in the following situations:
209  * * The user created the applet
210  * * The applet was moved in from another containment
211  * * The applet got restored at startup
212  */
213  void appletAdded(Plasma::Applet *applet);
214 
215  /**
216  * This signal is emitted when an applet is destroyed
217  */
218  void appletRemoved(Plasma::Applet *applet);
219 
220  /**
221  * This signal is emitted when a new applet is created by the containment.
222  * Compared to appletAdded, this gets emitted only when the user explicitly
223  * creates a new applet, either via the widget explorer or the scripting
224  * environment.
225  * @see appletAdded
226  * @since 5.16
227  */
228  void appletCreated(Plasma::Applet *applet);
229 
230  /**
231  * Emitted when the activity id has changed
232  */
233  void activityChanged(const QString &activity);
234 
235  /**
236  * Emitted when the containment requests an add widgets dialog is shown.
237  * Usually only used for desktop containments.
238  *
239  * @param pos where in the containment this request was made from, or
240  * an invalid position (QPointF()) is not location specific
241  */
242  void showAddWidgetsInterface(const QPointF &pos);
243 
244  /**
245  * This signal indicates that a containment has been
246  * associated (or dissociated) with a physical screen.
247  *
248  * @param newScreen the screen it is now associated with
249  */
250  void screenChanged(int newScreen);
251 
252  /**
253  * Emitted when the user wants to configure/change the containment, or an applet inside it.
254  */
255  void configureRequested(Plasma::Applet *applet);
256 
257  /**
258  * Emitted when the user wants to chose an alternative for this applet or containment.
259  */
260  void appletAlternativesRequested(Plasma::Applet *applet);
261 
262  /**
263  * Emitted when the wallpaper plugin is changed
264  */
265  void wallpaperChanged();
266 
267  /**
268  * Emitted when the location has changed
269  * @since 5.0
270  */
271  void locationChanged(Plasma::Types::Location location);
272 
273  /**
274  * Emitted when the formFactor has changed
275  * @since 5.0
276  */
277  void formFactorChanged(Plasma::Types::FormFactor formFactor);
278 
279  /**
280  * Emitted when the ui has been fully loaded and is fully working
281  * @param uiReady true when the ui of the containment is ready, as well the ui of each applet in it
282  */
283  void uiReadyChanged(bool uiReady);
284 
285  /**
286  * emitted when the containment type changed
287  */
288  void containmentTypeChanged();
289 
290 public Q_SLOTS:
291  /**
292  * Informs the Corona as to what position it is in. This is informational
293  * only, as the Corona doesn't change its actual location. This is,
294  * however, passed on to Applets that may be managed by this Corona.
295  *
296  * @param location the new location of this Corona
297  */
298  void setLocation(Plasma::Types::Location location);
299 
300  /**
301  * Sets the form factor for this Containment. This may cause changes in both
302  * the arrangement of Applets as well as the display choices of individual
303  * Applets.
304  */
305  void setFormFactor(Plasma::Types::FormFactor formFactor);
306 
307  /**
308  * Set Display hints that come from the containment that suggest the applet how to look and behave.
309  *
310  * @param hints the new hints, as bitwise OR
311  * @since 5.77
312  */
313  void setContainmentDisplayHints(Plasma::Types::ContainmentDisplayHints hints);
314 
315  /**
316  * Sets the type of this containment.
317  */
318  void setContainmentType(Plasma::Types::ContainmentType type);
319 
320  void reactToScreenChange();
321 
322 protected:
323  /**
324  * Called when the contents of the containment should be saved. By default this saves
325  * all loaded Applets
326  *
327  * @param group the KConfigGroup to save settings under
328  */
329  virtual void saveContents(KConfigGroup &group) const;
330 
331  /**
332  * Called when the contents of the containment should be loaded. By default this loads
333  * all previously saved Applets
334  *
335  * @param group the KConfigGroup to save settings under
336  */
337  virtual void restoreContents(KConfigGroup &group);
338 
339 private:
340  /**
341  * @internal This constructor is to be used with the Package loading system.
342  *
343  * @param parent a QObject parent; you probably want to pass in 0
344  * @since 4.3
345  */
346  Containment(const KPluginMetaData &md, uint appletId);
347 
348  Q_PRIVATE_SLOT(d, void appletDeleted(Plasma::Applet *))
349  Q_PRIVATE_SLOT(d, void triggerShowAddWidgets())
350  Q_PRIVATE_SLOT(d, void checkStatus(Plasma::Types::ItemStatus))
351 
352  friend class Applet;
353  friend class AppletPrivate;
354  friend class CoronaPrivate;
355  friend class ContainmentPrivate;
356  friend class ContainmentActions;
357  ContainmentPrivate *const d;
358 };
359 
360 } // Plasma namespace
361 
362 #endif // multiple inclusion guard
ItemStatus
Status of an applet.
Definition: plasma.h:270
Namespace for everything in libplasma.
Definition: datamodel.cpp:14
QCA_EXPORT void init()
FormFactor
The FormFactor enumeration describes how a Plasma::Applet should arrange itself.
Definition: plasma.h:72
The base ContainmentActions class.
A bookkeeping Scene for Plasma::Applets.
Definition: corona.h:27
ContainmentType
This enumeration describes the type of the Containment.
Definition: plasma.h:114
Location
The Location enumeration describes where on screen an element, such as an Applet or its managing cont...
Definition: plasma.h:158
The base class for plugins that provide backgrounds and applet grouping containers.
Definition: containment.h:45
The base Applet class.
Definition: applet.h:71
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Mon Feb 6 2023 04:13:43 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.