KWayland

compositor.h
1 /*
2  SPDX-FileCopyrightText: 2014 Martin Gräßlin <[email protected]>
3 
4  SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
5 */
6 #ifndef WAYLAND_COMPOSITOR_H
7 #define WAYLAND_COMPOSITOR_H
8 
9 #include <QObject>
10 
11 #include <memory>
12 
13 #include <KWayland/Client/kwaylandclient_export.h>
14 
15 struct wl_compositor;
16 
17 namespace KWayland
18 {
19 namespace Client
20 {
21 class EventQueue;
22 class Region;
23 class Surface;
24 
25 /**
26  * @short Wrapper for the wl_compositor interface.
27  *
28  * This class provides a convenient wrapper for the wl_compositor interface.
29  * It's main purpose is to create a Surface.
30  *
31  * To use this class one needs to interact with the Registry. There are two
32  * possible ways to create the Compositor interface:
33  * @code
34  * Compositor *c = registry->createCompositor(name, version);
35  * @endcode
36  *
37  * This creates the Compositor and sets it up directly. As an alternative this
38  * can also be done in a more low level way:
39  * @code
40  * Compositor *c = new Compositor;
41  * c->setup(registry->bindCompositor(name, version));
42  * @endcode
43  *
44  * The Compositor can be used as a drop-in replacement for any wl_compositor
45  * pointer as it provides matching cast operators.
46  *
47  * @see Registry
48  **/
49 class KWAYLANDCLIENT_EXPORT Compositor : public QObject
50 {
51  Q_OBJECT
52 public:
53  /**
54  * Creates a new Compositor.
55  * Note: after constructing the Compositor it is not yet valid and one needs
56  * to call setup. In order to get a ready to use Compositor prefer using
57  * Registry::createCompositor.
58  **/
59  explicit Compositor(QObject *parent = nullptr);
60  virtual ~Compositor();
61 
62  /**
63  * Creates a Compositor for the used QGuiApplication.
64  * This is an integration feature for QtWayland. On non-wayland platforms this method returns
65  * @c nullptr.
66  *
67  * The returned Compositor will be fully setup, which means it manages a wl_compositor.
68  * When the created Compositor gets destroyed the managed wl_compositor won't be disconnected
69  * as that's managed by Qt.
70  * @since 5.4
71  **/
72  static Compositor *fromApplication(QObject *parent = nullptr);
73 
74  /**
75  * @returns @c true if managing a wl_compositor.
76  **/
77  bool isValid() const;
78  /**
79  * Setup this Compositor to manage the @p compositor.
80  * When using Registry::createCompositor there is no need to call this
81  * method.
82  **/
83  void setup(wl_compositor *compositor);
84  /**
85  * Releases the wl_compositor interface.
86  * After the interface has been released the Compositor instance is no
87  * longer valid and can be setup with another wl_compositor interface.
88  **/
89  void release();
90  /**
91  * Destroys the data held by this Compositor.
92  * This method is supposed to be used when the connection to the Wayland
93  * server goes away. If the connection is not valid anymore, it's not
94  * possible to call release anymore as that calls into the Wayland
95  * connection and the call would fail. This method cleans up the data, so
96  * that the instance can be deleted or set up to a new wl_compositor interface
97  * once there is a new connection available.
98  *
99  * It is suggested to connect this method to ConnectionThread::connectionDied:
100  * @code
101  * connect(connection, &ConnectionThread::connectionDied, compositor, &Compositor::destroy);
102  * @endcode
103  *
104  * @see release
105  **/
106  void destroy();
107 
108  /**
109  * Sets the @p queue to use for creating a Surface.
110  **/
111  void setEventQueue(EventQueue *queue);
112  /**
113  * @returns The event queue to use for creating a Surface.
114  **/
115  EventQueue *eventQueue();
116 
117  /**
118  * Creates and setup a new Surface with @p parent.
119  * @param parent The parent to pass to the Surface.
120  * @returns The new created Surface
121  **/
122  Surface *createSurface(QObject *parent = nullptr);
123 
124  /**
125  * Creates and setup a new Region with @p parent.
126  * @param parent The parent to pass to the Region.
127  * @returns The new created Region
128  **/
129  Region *createRegion(QObject *parent = nullptr);
130  /**
131  * Creates and setup a new Region with @p parent.
132  *
133  * The @p region is directly added to the created Region.
134  * @param parent The parent to pass to the Region.
135  * @param region The region to install on the newly created Region
136  * @returns The new created Region
137  **/
138  Region *createRegion(const QRegion &region, QObject *parent);
139  /**
140  * Creates and setup a new Region with @p region installed.
141  *
142  * This overloaded convenience method is intended to be used in the
143  * case that the Region is only needed to setup e.g. input region on
144  * a Surface and is afterwards no longer needed. Setting the input
145  * region has copy semantics and the Region can be destroyed afterwards.
146  * This allows to simplify setting the input region to:
147  *
148  * @code
149  * Surface *s = compositor->createSurface();
150  * s->setInputRegion(compositor->createRegion(QRegion(0, 0, 10, 10)).get());
151  * @endcode
152  *
153  * @param region The region to install on the newly created Region
154  * @returns The new created Region
155  **/
156  std::unique_ptr<Region> createRegion(const QRegion &region);
157 
158  operator wl_compositor *();
159  operator wl_compositor *() const;
160 
161 Q_SIGNALS:
162  /**
163  * The corresponding global for this interface on the Registry got removed.
164  *
165  * This signal gets only emitted if the Compositor got created by
166  * Registry::createCompositor
167  *
168  * @since 5.5
169  **/
170  void removed();
171 
172 private:
173  class Private;
175 };
176 
177 }
178 }
179 
180 #endif
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:54
Wrapper for the wl_compositor interface.
Definition: compositor.h:49
Wrapper for the wl_surface interface.
Definition: surface.h:43
Wrapper for the wl_region interface.
Definition: region.h:31
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Oct 16 2021 22:52:00 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.