Plasma

corona.h
1 /*
2  SPDX-FileCopyrightText: 2007 Aaron Seigo <[email protected]>
3  SPDX-FileCopyrightText: 2007 Matt Broadstone <[email protected]>
4  SPDX-FileCopyrightText: 2012 Marco Martin <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef PLASMA_CORONA_H
10 #define PLASMA_CORONA_H
11 
12 #include <plasma/containment.h>
13 #include <plasma/plasma.h>
14 #include <plasma/plasma_export.h>
15 
16 class QAction;
17 
18 namespace Plasma
19 {
20 class CoronaPrivate;
21 
22 /**
23  * @class Corona plasma/Corona.h <Plasma/Corona>
24  *
25  * @short A bookkeeping Scene for Plasma::Applets
26  */
27 class PLASMA_EXPORT Corona : public QObject
28 {
29  Q_OBJECT
30  Q_PROPERTY(bool isStartupCompleted READ isStartupCompleted NOTIFY startupCompleted)
31  Q_PROPERTY(bool editMode READ isEditMode WRITE setEditMode NOTIFY editModeChanged)
32 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 83)
33  Q_PROPERTY(Package package READ package NOTIFY packageChanged)
34 #endif
35  Q_PROPERTY(KPackage::Package kPackage READ kPackage NOTIFY kPackageChanged)
36 
37 public:
38  explicit Corona(QObject *parent = nullptr);
39  ~Corona() override;
40 
41 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 6)
42  /**
43  * Accessor for the associated Package object if any.
44  * A Corona package defines how Containments are laid out in a View,
45  * ToolBoxes, default layout, error messages
46  * and in general all the furniture specific of a particular
47  * device form factor.
48  *
49  * @return the Package object, or an invalid one if none
50  * @since 5.0
51  * @deprecated Since 5.6, use kPackage instead
52  **/
53  PLASMA_DEPRECATED_VERSION(5, 6, "Use Corona::kPackage()")
54  Plasma::Package package() const;
55 #endif
56 
57 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 6)
58  /**
59  * Setting the package name
60  * @deprecated Since 5.6, use setKPackage instead
61  */
62  PLASMA_DEPRECATED_VERSION(5, 6, "Use Corona::setKPackage(const KPackage::Package &)")
63  void setPackage(const Plasma::Package &package);
64 #endif
65 
66  /**
67  * Accessor for the associated Package object if any.
68  * A Corona package defines how Containments are laid out in a View,
69  * ToolBoxes, default layout, error messages
70  * and in genelal all the furniture specific of a particular
71  * device form factor.
72  *
73  * @return the Package object, or an invalid one if none
74  * @since 5.5
75  **/
76  KPackage::Package kPackage() const;
77 
78  /**
79  * Setting the package for the corona
80  * @since 5.5
81  */
82  void setKPackage(const KPackage::Package &package);
83 
84  /**
85  * @return all containments on this Corona
86  */
87  QList<Containment *> containments() const;
88 
89  /**
90  * @returns true when the startup is over, and
91  * all the ui graphics has been instantiated
92  */
93  bool isStartupCompleted() const;
94 
95  /**
96  * Returns the config file used to store the configuration for this Corona
97  */
98  KSharedConfig::Ptr config() const;
99 
100  /**
101  * Adds a Containment to the Corona
102  *
103  * @param name the plugin name for the containment, as given by
104  * KPluginInfo::pluginName(). If an empty string is passed in, the default
105  * containment plugin will be used (usually DesktopContainment). If the
106  * string literal "null" is passed in, then no plugin will be loaded and
107  * a simple Containment object will be created instead.
108  * @param args argument list to pass to the containment
109  *
110  * @return a pointer to the containment on success, or 0 on failure. Failure can be
111  * caused by too restrictive of an Immutability type, as containments cannot be added
112  * when widgets are locked.
113  * If the requested containment plugin can not be located or successfully loaded, the Containment will have an invalid pluginInfo().
114  */
115  Containment *createContainment(const QString &name, const QVariantList &args = QVariantList());
116 
117  /**
118  * Returns the Containment for a given physical screen and desktop, creating one
119  * if none exists
120  *
121  * @param screen number of the physical screen to locate
122  * @param activity the activity id of the containment we want,
123  * and empty string if the activity is not important
124  * @param defaultPluginIfNonExistent the plugin to load by default; "null" won't
125  * create it and "default" creates the default plugin
126  * @param defaultArgs optional arguments to pass in when creating a Containment if needed
127  * @since 5.45
128  */
129  Containment *
130  containmentForScreen(int screen, const QString &activity, const QString &defaultPluginIfNonExistent, const QVariantList &defaultArgs = QVariantList());
131 
132  // TODO KF6: add activity here, can't be done now as the overload would get confused
133 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 46)
134  /**
135  * Returns the Containment, if any, for a given physical screen
136  *
137  * @param screen number of the physical screen to locate
138  * @deprecated Since 5.46, use containmentForScreen(int, const QString &, const QString &, const QVariantList &)
139  */
140  PLASMA_DEPRECATED_VERSION(5, 46, "Use Corona::containmentForScreen(int, const QString &, const QString &, const QVariantList &)")
141  Containment *containmentForScreen(int screen) const;
142 #endif
143 
144 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 46)
145  /**
146  * Returns the Containment for a given physical screen and desktop, creating one
147  * if none exists
148  *
149  * @param screen number of the physical screen to locate
150  * @param defaultPluginIfNonExistent the plugin to load by default; "null" is an empty
151  * Containment and "default" creates the default plugin
152  * @param defaultArgs optional arguments to pass in when creating a Containment if needed
153  * @deprecated Since 5.46, use containmentForScreen(int, const QString &, const QString &, const QVariantList &)
154  */
155  PLASMA_DEPRECATED_VERSION(5, 46, "Use Corona::containmentForScreen(int, const QString &, const QString &, const QVariantList &)")
156  Containment *containmentForScreen(int screen, const QString &defaultPluginIfNonExistent, const QVariantList &defaultArgs = QVariantList());
157 #endif
158 
159  /**
160  * Returns all containments which match a particular activity, for any screen
161  * @param activity the activity id we want
162  * @returns the list of matching containments if any, empty if activity is an empty string
163  * @since 5.45
164  */
165  QList<Containment *> containmentsForActivity(const QString &activity);
166 
167  /**
168  * Returns all containments which match a particular screen, for any activity
169  * @param screen the screen number we want
170  * @returns the list of matching containments if any, empty if screen is < 0
171  * @since 5.45
172  */
173  QList<Containment *> containmentsForScreen(int screen);
174 
175  /**
176  * Returns the number of screens available to plasma.
177  * Subclasses should override this method as the default
178  * implementation returns a meaningless value.
179  */
180  virtual int numScreens() const;
181 
182  /**
183  * Returns the geometry of a given screen.
184  * Valid screen ids are 0 to numScreen()-1, or -1 for the full desktop geometry.
185  * Subclasses should override this method as the default
186  * implementation returns a meaningless value.
187  */
188  virtual QRect screenGeometry(int id) const = 0;
189 
190  /**
191  * Returns the available region for a given screen.
192  * The available region excludes panels and similar windows.
193  * Valid screen ids are 0 to numScreens()-1.
194  * By default this method returns a rectangular region
195  * equal to screenGeometry(id); subclasses that need another
196  * behavior should override this method.
197  */
198  virtual QRegion availableScreenRegion(int id) const;
199 
200  /**
201  * Returns the available rect for a given screen.
202  * The difference between this and availableScreenRegion()
203  * is that this method returns only a rectangular
204  * available space (it doesn't care if your panel is not 100% width).
205  * The available rect excludes panels and similar windows.
206  * Valid screen ids are 0 to numScreens()-1.
207  * By default this method returns a rectangular region
208  * equal to screenGeometry(id); subclasses that need another
209  * behavior should override this method.
210  */
211  virtual QRect availableScreenRect(int id) const;
212 
213  /**
214  * This method is useful in order to retrieve the list of available
215  * screen edges for panel type containments.
216  * @param screen the id of the screen to look for free edges.
217  * @returns a list of free edges not filled with panel type containments.
218  */
219  QList<Plasma::Types::Location> freeEdges(int screen) const;
220 
221  /**
222  * The actions associated with this Corona
223  */
224  KActionCollection *actions() const;
225 
226  /**
227  * Imports an applet layout from a config file. The results will be added to the
228  * current set of Containments.
229  *
230  * @param config the name of the config file to load from,
231  * or the default config file if QString()
232  * @return the list of containments that were loaded
233  * @since 4.6
234  */
235  QList<Plasma::Containment *> importLayout(const KConfigGroup &config);
236 
237  /**
238  * Exports a set of containments to a config file.
239  *
240  * @param config the config group to save to
241  * @param containments the list of containments to save
242  * @since 4.6
243  */
244  void exportLayout(KConfigGroup &config, QList<Containment *> containments);
245 
246  /**
247  * @returns the id of the screen which is showing @p containment
248  * -1 is returned if the containment is not associated with a screen.
249  */
250  virtual int screenForContainment(const Containment *containment) const;
251 
252  /**
253  * @return The type of immutability of this Corona
254  */
255  Types::ImmutabilityType immutability() const;
256 
257  /**
258  * Set the Corona globally into "edit mode"
259  * Only when the corona is of mutable type can be set of edit mode.
260  * This indicates the UI to make easy for the user to manipulate applets.
261  * @param edit
262  * @since 5.63
263  */
264  void setEditMode(bool edit);
265 
266  /**
267  * @returns true if the corona is in edit mode
268  * @since 5.63
269  */
270  bool isEditMode() const;
271 
272 public Q_SLOTS:
273  /**
274  * Load applet layout from a config file. The results will be added to the
275  * current set of Containments.
276  *
277  * @param config the name of the config file to load from,
278  * or the default config file if QString()
279  */
280  void loadLayout(const QString &config = QString());
281 
282  /**
283  * Save applets layout to file
284  * @param config the file to save to, or the default config file if QString()
285  */
286  void saveLayout(const QString &config = QString()) const;
287 
288  /**
289  * Sets the immutability type for this Corona (not immutable,
290  * user immutable or system immutable)
291  * @param immutable the new immutability type of this applet
292  */
293  void setImmutability(const Types::ImmutabilityType immutable);
294 
295  /**
296  * Schedules a flush-to-disk synchronization of the configuration state
297  * at the next convenient moment.
298  */
299  void requestConfigSync();
300 
301  /**
302  * Schedules a time sensitive flush-to-disk synchronization of the
303  * configuration state. Since this method does not provide any sort of
304  * event compression, it should only be used when an *immediate* disk
305  * sync is *absolutely* required. Otherwise, use @see requestConfigSync()
306  * which does do event compression.
307  */
308  void requireConfigSync();
309 
310 Q_SIGNALS:
311  /**
312  * This signal indicates a new containment has been added to
313  * the Corona: it may occur after creation or restore from config
314  */
315  void containmentAdded(Plasma::Containment *containment);
316 
317  /**
318  * This signal indicates a new containment has been created
319  * in the Corona. Compared to containmentAdded it can only happen
320  * after the creation of a new containment.
321  *
322  * @see containmentAdded
323  * @since 5.16
324  */
325  void containmentCreated(Plasma::Containment *containment);
326 
327  /**
328  * This signal indicates that a containment has been newly
329  * associated (or dissociated) with a physical screen.
330  *
331  * @param isScreen the screen it is now associated with
332  */
333  void screenOwnerChanged(int isScreen);
334 
335  /**
336  * This signal indicates that the configuration file was flushed to disk.
337  */
338  void configSynced();
339 
340  /**
341  * This signal indicates that a change in available screen geometry occurred.
342  */
343  void availableScreenRegionChanged();
344 
345  /**
346  * This signal indicates that a change in available screen geometry occurred.
347  */
348  void availableScreenRectChanged();
349 
350  /**
351  * This signal indicates that a change in geometry for the screen occurred.
352  */
353  void screenGeometryChanged(int id);
354 
355  /**
356  * emitted when immutability changes.
357  * this is for use by things that don't get constraints events, like plasmaapp.
358  * it's NOT for containments or applets or any of the other stuff on the scene.
359  * if your code's not in shells/ it probably shouldn't be using it.
360  */
361  void immutabilityChanged(Plasma::Types::ImmutabilityType immutability);
362 
363  /** This signal indicates the screen with the specified id was removed.
364  * @since 5.40
365  */
366  void screenRemoved(int id);
367 
368  /** This signal indicates a new screen with the specified id was added.
369  * @since 5.40
370  */
371  void screenAdded(int id);
372 
373  /**
374  * emitted when the editMode state changes
375  * @see isEditMode()
376  * @since 5.63
377  */
378  void editModeChanged(bool edit);
379 
380 #if PLASMA_ENABLE_DEPRECATED_SINCE(5, 6)
381  /**
382  * Emitted when the package for this corona has been changed.
383  * Shells must support changing the shell package on the fly (for instance due to device form factor changing)
384  *
385  * @param package the new package that defines the Corona furniture and behavior
386  * @deprecated Since 5.6, use kPackageChanged instead
387  */
388  PLASMA_DEPRECATED_VERSION(5, 6, "Use Corona::kPackageChanged(const KPackage::Package &)")
389  void packageChanged(const Plasma::Package &package);
390 #endif
391 
392  /**
393  * Emitted when the package for this corona has been changed.
394  * Shells must support changing the shell package on the fly (for instance due to device form factor changing)
395  *
396  * @param package the new package that defines the Corona furniture and behavior
397  */
398  void kPackageChanged(const KPackage::Package &package);
399 
400  /**
401  * Emitted when the startup phase has been completed
402  */
403  void startupCompleted();
404 
405 protected:
406  /**
407  * Loads the default (system wide) layout for this user
408  **/
409  virtual void loadDefaultLayout();
410 
411  /**
412  * Loads a containment with delayed initialization, primarily useful
413  * for implementations of loadDefaultLayout. The caller is responsible
414  * for all initialization, saving and notification of a new containment.
415  *
416  * @param name the plugin name for the containment, as given by
417  * KPluginInfo::pluginName(). If an empty string is passed in, the default
418  * containment plugin will be used (usually DesktopContainment). If the
419  * string literal "null" is passed in, then no plugin will be loaded and
420  * a simple Containment object will be created instead.
421  * @param args argument list to pass to the containment
422  *
423  * @return a pointer to the containment on success, or 0 on failure. Failure can
424  * be caused by the Immutability type being too restrictive, as containments can't be added
425  * when widgets are locked, or if the requested containment plugin can not be located
426  * or successfully loaded.
427  * @see addContainment
428  **/
429  Containment *createContainmentDelayed(const QString &name, const QVariantList &args = QVariantList());
430 
431 private:
432  CoronaPrivate *const d;
433 
434  Q_PRIVATE_SLOT(d, void containmentDestroyed(QObject *))
435  Q_PRIVATE_SLOT(d, void syncConfig())
436  Q_PRIVATE_SLOT(d, void toggleImmutability())
437  Q_PRIVATE_SLOT(d, void containmentReady(bool))
438 
439  friend class CoronaPrivate;
440  friend class View;
441 };
442 
443 } // namespace Plasma
444 
445 #endif
Namespace for everything in libplasma.
Definition: datamodel.cpp:14
A bookkeeping Scene for Plasma::Applets.
Definition: corona.h:27
ImmutabilityType
Defines the immutability of items like applets, corona and containments they can be free to modify,...
Definition: plasma.h:235
object representing an installed Plasma package
Definition: package.h:76
The base class for plugins that provide backgrounds and applet grouping containers.
Definition: containment.h:45
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.