KWaylandServer

textinput_v2_interface.h
1 /*
2  SPDX-FileCopyrightText: 2016 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 #pragma once
7 
8 #include <QObject>
9 
10 #include <KWaylandServer/kwaylandserver_export.h>
11 
12 #include "textinput.h"
13 
14 struct wl_resource;
15 namespace KWaylandServer
16 {
17 class Display;
18 class SeatInterface;
19 class SurfaceInterface;
20 class TextInputV2Interface;
21 class TextInputV2InterfacePrivate;
22 class TextInputManagerV2InterfacePrivate;
23 
24 /**
25  * @brief Represent the Global for the interface.
26  *
27  * The class can represent different interfaces. Which concrete interface is represented
28  * can be determined through {@link interfaceVersion}.
29  *
30  * To create a TextInputManagerV2Interface use {@link Display::createTextInputManager}
31  */
32 class KWAYLANDSERVER_EXPORT TextInputManagerV2Interface : public QObject
33 {
34  Q_OBJECT
35 public:
36  explicit TextInputManagerV2Interface(Display *display, QObject *parent = nullptr);
37  ~TextInputManagerV2Interface() override;
38 
39 private:
41 };
42 
43 /**
44  * @brief Represents a generic Resource for a text input object.
45  *
46  * This class does not directly correspond to a Wayland resource, but is a generic contract
47  * for any interface which implements a text input, e.g. the unstable wl_text_input interface.
48  *
49  * It does not expose the actual interface to cover up the fact that the interface is unstable
50  * and might change. If one needs to know the actual used protocol, use the method {@link interfaceVersion}.
51  *
52  * A TextInputV2Interface gets created by the {@link TextInputManagerV2Interface}. The individual
53  * instances are not exposed directly. The SeatInterface provides access to the currently active
54  * TextInputV2Interface. This is evaluated automatically based on which SurfaceInterface has
55  * keyboard focus.
56  *
57  * @see TextInputManagerV2Interface
58  * @see SeatInterface
59  */
60 class KWAYLANDSERVER_EXPORT TextInputV2Interface : public QObject
61 {
62  Q_OBJECT
63 public:
64  ~TextInputV2Interface() override;
65 
66  enum class UpdateReason : uint32_t {
67  StateChange = 0, // updated state because it changed
68  StateFull = 1, // full state after enter or input_method_changed event
69  StateReset = 2, // full state after reset
70  StateEnter = 3, // full state after switching focus to a different widget on client side
71  };
72  Q_ENUM(UpdateReason);
73  /**
74  * The preferred language as a RFC-3066 format language tag.
75  *
76  * This can be used by the server to show a language specific virtual keyboard layout.
77  * @see preferredLanguageChanged
78  */
79  QString preferredLanguage() const;
80 
81  /**
82  * @see cursorRectangleChanged
83  */
84  QRect cursorRectangle() const;
85 
86  /**
87  * @see contentTypeChanged
88  */
89  TextInputContentPurpose contentPurpose() const;
90 
91  /**
92  *@see contentTypeChanged
93  */
94  TextInputContentHints contentHints() const;
95 
96  /**
97  * @returns The plain surrounding text around the input position.
98  * @see surroundingTextChanged
99  * @see surroundingTextCursorPosition
100  * @see surroundingTextSelectionAnchor
101  */
102  QString surroundingText() const;
103  /**
104  * @returns The byte offset of current cursor position within the {@link surroundingText}
105  * @see surroundingText
106  * @see surroundingTextChanged
107  */
108  qint32 surroundingTextCursorPosition() const;
109  /**
110  * The byte offset of the selection anchor within the {@link surroundingText}.
111  *
112  * If there is no selected text this is the same as cursor.
113  * @return The byte offset of the selection anchor
114  * @see surroundingText
115  * @see surroundingTextChanged
116  */
117  qint32 surroundingTextSelectionAnchor() const;
118 
119  /**
120  * @return The surface the TextInputV2Interface is enabled on
121  * @see isEnabled
122  * @see enabledChanged
123  */
124  QPointer<SurfaceInterface> surface() const;
125 
126  /**
127  * @return Whether the TextInputV2Interface is currently enabled for a SurfaceInterface.
128  * @see surface
129  * @see enabledChanged
130  */
131  bool isEnabled() const;
132 
133  /**
134  * Notify when a new composing @p text (pre-edit) should be set around the
135  * current cursor position. Any previously set composing text should
136  * be removed.
137  *
138  * The @p commitText can be used to replace the preedit text on reset
139  * (for example on unfocus).
140  *
141  * @param text The new utf8-encoded pre-edit text
142  * @param commitText Utf8-encoded text to replace preedit text on reset
143  * @see commit
144  * @see preEditCursor
145  */
146  void preEdit(const QString &text, const QString &commitText);
147 
148  /**
149  * Notify when @p text should be inserted into the editor widget.
150  * The text to commit could be either just a single character after a key press or the
151  * result of some composing ({@link preEdit}). It could be also an empty text
152  * when some text should be removed (see {@link deleteSurroundingText}) or when
153  * the input cursor should be moved (see {@link cursorPosition}).
154  *
155  * Any previously set composing text should be removed.
156  * @param text The utf8-encoded text to be inserted into the editor widget
157  * @see preEdit
158  * @see deleteSurroundingText
159  */
160  void commitString(const QString &text);
161 
162  /**
163  * Sets the cursor position inside the composing text (as byte offset) relative to the
164  * start of the composing text. When @p index is a negative number no cursor is shown.
165  *
166  * The Client applies the @p index together with {@link preEdit}.
167  * @param index The cursor position relative to the start of the composing text
168  * @see preEdit
169  */
170  void setPreEditCursor(qint32 index);
171 
172  /**
173  * Notify when the text around the current cursor position should be deleted.
174  *
175  * The Client processes this event together with the commit string
176  *
177  * @param beforeLength length of text before current cursor position.
178  * @param afterLength length of text after current cursor position.
179  * @see commit
180  */
181  void deleteSurroundingText(quint32 beforeLength, quint32 afterLength);
182 
183  /**
184  * Notify when the cursor @p index or @p anchor position should be modified.
185  *
186  * The Client applies this together with the commit string.
187  */
188  void setCursorPosition(qint32 index, qint32 anchor);
189 
190  /**
191  * Sets the text @p direction of input text.
192  */
193  void setTextDirection(Qt::LayoutDirection direction);
194 
195  void keysymPressed(quint32 keysym, quint32 modifiers = 0);
196  void keysymReleased(quint32 keysym, quint32 modifiers = 0);
197 
198  /**
199  * Informs the client about changes in the visibility of the input panel (virtual keyboard).
200  *
201  * The @p overlappedSurfaceArea defines the area overlapped by the input panel (virtual keyboard)
202  * on the SurfaceInterface having the text focus in surface local coordinates.
203  *
204  * @param visible Whether the input panel is currently visible
205  * @param overlappedSurfaceArea The overlapping area in surface local coordinates
206  */
207  void setInputPanelState(bool visible, const QRect &overlappedSurfaceArea);
208 
209  /**
210  * Sets the language of the input text. The @p languageTag is a RFC-3066 format language tag.
211  */
212  void setLanguage(const QString &languageTag);
213 
214  /**
215  * Sets the modifiers map to use when modifiers are included in a key event.
216  */
217  void setModifiersMap(const QByteArray &modifiersMap);
218 
219 Q_SIGNALS:
220  /**
221  * Requests input panels (virtual keyboard) to show.
222  * @see requestHideInputPanel
223  */
224  void requestShowInputPanel();
225  /**
226  * Requests input panels (virtual keyboard) to hide.
227  * @see requestShowInputPanel
228  */
229  void requestHideInputPanel();
230  /**
231  * Emitted whenever the preferred @p language changes.
232  * @see preferredLanguage
233  */
234  void preferredLanguageChanged(const QString &language);
235  /**
236  * @see cursorRectangle
237  */
238  void cursorRectangleChanged(const QRect &rect);
239  /**
240  * Emitted when the {@link contentPurpose} and/or {@link contentHints} changes.
241  * @see contentPurpose
242  * @see contentHints
243  */
244  void contentTypeChanged();
245  /**
246  * Emitted when the {@link surroundingText}, {@link surroundingTextCursorPosition}
247  * and/or {@link surroundingTextSelectionAnchor} changed.
248  * @see surroundingText
249  * @see surroundingTextCursorPosition
250  * @see surroundingTextSelectionAnchor
251  */
252  void surroundingTextChanged();
253  /**
254  * Emitted whenever this TextInputV2Interface gets enabled or disabled for a SurfaceInterface.
255  * @see isEnabled
256  * @see surface
257  */
258  void enabledChanged();
259  /**
260  * Emitted whenever TextInputInterface should update the current state.
261  */
262  void stateUpdated(uint32_t serial, UpdateReason reason);
263 
264 private:
265  friend class TextInputManagerV2InterfacePrivate;
266  friend class SeatInterface;
267  friend class SeatInterfacePrivate;
268  friend class TextInputV2InterfacePrivate;
269  explicit TextInputV2Interface(SeatInterface *seat);
270 
272 };
273 
274 }
275 
276 Q_DECLARE_METATYPE(KWaylandServer::TextInputV2Interface *)
277 Q_DECLARE_METATYPE(KWaylandServer::TextInputV2Interface::UpdateReason)
Represents a Seat on the Wayland Display.
Class holding the Wayland server display loop.
Definition: display.h:47
LayoutDirection
Represent the Global for the interface.
Represents a generic Resource for a text input object.
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Sat Oct 23 2021 23:08:28 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.