1 | /* |
2 | SPDX-FileCopyrightText: 2014 Martin Gräßlin <mgraesslin@kde.org> |
3 | |
4 | SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL |
5 | */ |
6 | #ifndef WAYLAND_DATADEVICE_H |
7 | #define WAYLAND_DATADEVICE_H |
8 | |
9 | #include "dataoffer.h" |
10 | |
11 | #include <QObject> |
12 | |
13 | #include "KWayland/Client/kwaylandclient_export.h" |
14 | |
15 | struct wl_data_device; |
16 | |
17 | namespace KWayland |
18 | { |
19 | namespace Client |
20 | { |
21 | class DataSource; |
22 | class Surface; |
23 | |
24 | /** |
25 | * @short DataDevice allows clients to share data by copy-and-paste and drag-and-drop. |
26 | * |
27 | * This class is a convenient wrapper for the wl_data_device interface. |
28 | * To create a DataDevice call DataDeviceManager::getDataDevice. |
29 | * |
30 | * @see DataDeviceManager |
31 | **/ |
32 | class KWAYLANDCLIENT_EXPORT DataDevice : public QObject |
33 | { |
34 | Q_OBJECT |
35 | public: |
36 | explicit DataDevice(QObject *parent = nullptr); |
37 | ~DataDevice() override; |
38 | |
39 | /** |
40 | * Setup this DataDevice to manage the @p dataDevice. |
41 | * When using DataDeviceManager::createDataDevice there is no need to call this |
42 | * method. |
43 | **/ |
44 | void setup(wl_data_device *dataDevice); |
45 | /** |
46 | * Releases the wl_data_device interface. |
47 | * After the interface has been released the DataDevice instance is no |
48 | * longer valid and can be setup with another wl_data_device interface. |
49 | **/ |
50 | void release(); |
51 | /** |
52 | * Destroys the data held by this DataDevice. |
53 | * This method is supposed to be used when the connection to the Wayland |
54 | * server goes away. If the connection is not valid anymore, it's not |
55 | * possible to call release anymore as that calls into the Wayland |
56 | * connection and the call would fail. This method cleans up the data, so |
57 | * that the instance can be deleted or set up to a new wl_data_device interface |
58 | * once there is a new connection available. |
59 | * |
60 | * This method is automatically invoked when the Registry which created this |
61 | * DataDevice gets destroyed. |
62 | * |
63 | * @see release |
64 | **/ |
65 | void destroy(); |
66 | /** |
67 | * @returns @c true if managing a wl_data_device. |
68 | **/ |
69 | bool isValid() const; |
70 | |
71 | void startDrag(quint32 serial, DataSource *source, Surface *origin, Surface *icon = nullptr); |
72 | void startDragInternally(quint32 serial, Surface *origin, Surface *icon = nullptr); |
73 | |
74 | void setSelection(quint32 serial, DataSource *source = nullptr); |
75 | void clearSelection(quint32 serial); |
76 | |
77 | DataOffer *offeredSelection() const; |
78 | |
79 | /** |
80 | * @returns the currently focused surface during drag'n'drop on this DataDevice. |
81 | * @since 5.22 |
82 | **/ |
83 | QPointer<Surface> dragSurface() const; |
84 | /** |
85 | * @returns the DataOffer during a drag'n'drop operation. |
86 | * @since 5.22 |
87 | **/ |
88 | DataOffer *dragOffer() const; |
89 | std::unique_ptr<DataOffer> takeDragOffer(); |
90 | |
91 | operator wl_data_device *(); |
92 | operator wl_data_device *() const; |
93 | |
94 | Q_SIGNALS: |
95 | void selectionOffered(KWayland::Client::DataOffer *); |
96 | void selectionCleared(); |
97 | /** |
98 | * Notification that a drag'n'drop operation entered a Surface on this DataDevice. |
99 | * |
100 | * @param serial The serial for this enter |
101 | * @param relativeToSurface Coordinates relative to the upper-left corner of the Surface. |
102 | * @see dragSurface |
103 | * @see dragOffer |
104 | * @see dragLeft |
105 | * @see dragMotion |
106 | * @since 5.22 |
107 | **/ |
108 | void dragEntered(quint32 serial, const QPointF &relativeToSurface); |
109 | /** |
110 | * Notification that the drag'n'drop operation left the Surface on this DataDevice. |
111 | * |
112 | * The leave notification is sent before the enter notification for the new focus. |
113 | * @see dragEnter |
114 | * @since 5.22 |
115 | **/ |
116 | void dragLeft(); |
117 | /** |
118 | * Notification of drag motion events on the current drag surface. |
119 | * |
120 | * @param relativeToSurface Coordinates relative to the upper-left corner of the entered Surface. |
121 | * @param time timestamp with millisecond granularity |
122 | * @see dragEntered |
123 | * @since 5.22 |
124 | **/ |
125 | void dragMotion(const QPointF &relativeToSurface, quint32 time); |
126 | /** |
127 | * Emitted when the implicit grab is removed and the drag'n'drop operation ended on this |
128 | * DataDevice. |
129 | * |
130 | * The client can now start a data transfer on the DataOffer. |
131 | * @see dragEntered |
132 | * @see dragOffer |
133 | * @since 5.22 |
134 | **/ |
135 | void dropped(); |
136 | |
137 | private: |
138 | class Private; |
139 | QScopedPointer<Private> d; |
140 | }; |
141 | |
142 | } |
143 | } |
144 | |
145 | #endif |
146 | |