KWayland

textinput_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 #ifndef KWAYLAND_SERVER_TEXTINPUT_INTERFACE_H
7 #define KWAYLAND_SERVER_TEXTINPUT_INTERFACE_H
8 
9 #include "global.h"
10 #include "resource.h"
11 
12 #include <KWayland/Server/kwaylandserver_export.h>
13 
14 namespace KWayland
15 {
16 namespace Server
17 {
18 class Display;
19 class SeatInterface;
20 class SurfaceInterface;
21 class TextInputInterface;
22 
23 /**
24  * Enum describing the different InterfaceVersion encapsulated in this implementation
25  *
26  * @since 5.23
27  **/
29  /**
30  * wl_text_input as the non-standardized version
31  **/
32  UnstableV0,
33  /**
34  * not supported version
35  **/
36  UnstableV1,
37  /**
38  * zwp_text_input_v2 as used by Qt 5.7
39  **/
40  UnstableV2,
41 };
42 
43 /**
44  * @brief Represent the Global for the interface.
45  *
46  * The class can represent different interfaces. Which concrete interface is represented
47  * can be determined through {@link interfaceVersion}.
48  *
49  * To create a TextInputManagerInterface use {@link Display::createTextInputManager}
50  *
51  * @since 5.23
52  **/
53 class KWAYLANDSERVER_EXPORT TextInputManagerInterface : public Global
54 {
55  Q_OBJECT
56 public:
57  virtual ~TextInputManagerInterface();
58 
59  /**
60  * @returns The interface version used by this TextInputManagerInterface
61  **/
62  TextInputInterfaceVersion interfaceVersion() const;
63 
64 protected:
65  class Private;
66  explicit TextInputManagerInterface(Private *d, QObject *parent = nullptr);
67 
68 private:
69  Private *d_func() const;
70 };
71 
72 /**
73  * @brief Represents a generic Resource for a text input object.
74  *
75  * This class does not directly correspond to a Wayland resource, but is a generic contract
76  * for any interface which implements a text input, e.g. the unstable wl_text_input interface.
77  *
78  * It does not expose the actual interface to cover up the fact that the interface is unstable
79  * and might change. If one needs to know the actual used protocol, use the method {@link interfaceVersion}.
80  *
81  * A TextInputInterface gets created by the {@link TextInputManagerInterface}. The individual
82  * instances are not exposed directly. The SeatInterface provides access to the currently active
83  * TextInputInterface. This is evaluated automatically based on which SurfaceInterface has
84  * keyboard focus.
85  *
86  * @see TextInputManagerInterface
87  * @see SeatInterface
88  * @since 5.23
89  **/
90 class KWAYLANDSERVER_EXPORT TextInputInterface : public Resource
91 {
92  Q_OBJECT
93 public:
94  virtual ~TextInputInterface();
95 
96  /**
97  * ContentHint allows to modify the behavior of the text input.
98  **/
99  enum class ContentHint : uint32_t {
100  /**
101  * no special behaviour
102  */
103  None = 0,
104  /**
105  * suggest word completions
106  */
107  AutoCompletion = 1 << 0,
108  /**
109  * suggest word corrections
110  */
111  AutoCorrection = 1 << 1,
112  /**
113  * switch to uppercase letters at the start of a sentence
114  */
115  AutoCapitalization = 1 << 2,
116  /**
117  * prefer lowercase letters
118  */
119  LowerCase = 1 << 3,
120  /**
121  * prefer uppercase letters
122  */
123  UpperCase = 1 << 4,
124  /**
125  * prefer casing for titles and headings (can be language dependent)
126  */
127  TitleCase = 1 << 5,
128  /**
129  * characters should be hidden
130  */
131  HiddenText = 1 << 6,
132  /**
133  * typed text should not be stored
134  */
135  SensitiveData = 1 << 7,
136  /**
137  * just latin characters should be entered
138  */
139  Latin = 1 << 8,
140  /**
141  * the text input is multi line
142  */
143  MultiLine = 1 << 9,
144  };
145  Q_DECLARE_FLAGS(ContentHints, ContentHint)
146 
147  /**
148  * The ContentPurpose allows to specify the primary purpose of a text input.
149  *
150  * This allows an input method to show special purpose input panels with
151  * extra characters or to disallow some characters.
152  */
153  enum class ContentPurpose : uint32_t {
154  /**
155  * default input, allowing all characters
156  */
157  Normal,
158  /**
159  * allow only alphabetic characters
160  **/
161  Alpha,
162  /**
163  * allow only digits
164  */
165  Digits,
166  /**
167  * input a number (including decimal separator and sign)
168  */
169  Number,
170  /**
171  * input a phone number
172  */
173  Phone,
174  /**
175  * input an URL
176  */
177  Url,
178  /**
179  * input an email address
180  **/
181  Email,
182  /**
183  * input a name of a person
184  */
185  Name,
186  /**
187  * input a password
188  */
189  Password,
190  /**
191  * input a date
192  */
193  Date,
194  /**
195  * input a time
196  */
197  Time,
198  /**
199  * input a date and time
200  */
201  DateTime,
202  /**
203  * input for a terminal
204  */
205  Terminal,
206  };
207 
208  /**
209  * @returns The interface version used by this TextInputInterface
210  **/
211  TextInputInterfaceVersion interfaceVersion() const;
212 
213  /**
214  * The preferred language as a RFC-3066 format language tag.
215  *
216  * This can be used by the server to show a language specific virtual keyboard layout.
217  * @see preferredLanguageChanged
218  **/
219  QByteArray preferredLanguage() const;
220 
221  /**
222  * @see cursorRectangleChanged
223  **/
224  QRect cursorRectangle() const;
225 
226  /**
227  * @see contentTypeChanged
228  **/
229  ContentPurpose contentPurpose() const;
230 
231  /**
232  *@see contentTypeChanged
233  **/
234  ContentHints contentHints() const;
235 
236  /**
237  * @returns The plain surrounding text around the input position.
238  * @see surroundingTextChanged
239  * @see surroundingTextCursorPosition
240  * @see surroundingTextSelectionAnchor
241  **/
242  QByteArray surroundingText() const;
243  /**
244  * @returns The byte offset of current cursor position within the {@link surroundingText}
245  * @see surroundingText
246  * @see surroundingTextChanged
247  **/
248  qint32 surroundingTextCursorPosition() const;
249  /**
250  * The byte offset of the selection anchor within the {@link surroundingText}.
251  *
252  * If there is no selected text this is the same as cursor.
253  * @return The byte offset of the selection anchor
254  * @see surroundingText
255  * @see surroundingTextChanged
256  **/
257  qint32 surroundingTextSelectionAnchor() const;
258 
259  /**
260  * @return The surface the TextInputInterface is enabled on
261  * @see isEnabled
262  * @see enabledChanged
263  **/
264  QPointer<SurfaceInterface> surface() const;
265 
266  /**
267  * @return Whether the TextInputInterface is currently enabled for a SurfaceInterface.
268  * @see surface
269  * @see enabledChanged
270  **/
271  bool isEnabled() const;
272 
273  /**
274  * Notify when a new composing @p text (pre-edit) should be set around the
275  * current cursor position. Any previously set composing text should
276  * be removed.
277  *
278  * The @p commitText can be used to replace the preedit text on reset
279  * (for example on unfocus).
280  *
281  * @param text The new utf8-encoded pre-edit text
282  * @param commitText Utf8-encoded text to replace preedit text on reset
283  * @see commit
284  * @see preEditCursor
285  **/
286  void preEdit(const QByteArray &text, const QByteArray &commitText);
287 
288  /**
289  * Notify when @p text should be inserted into the editor widget.
290  * The text to commit could be either just a single character after a key press or the
291  * result of some composing ({@link preEdit}). It could be also an empty text
292  * when some text should be removed (see {@link deleteSurroundingText}) or when
293  * the input cursor should be moved (see {@link cursorPosition}).
294  *
295  * Any previously set composing text should be removed.
296  * @param text The utf8-encoded text to be inserted into the editor widget
297  * @see preEdit
298  * @see deleteSurroundingText
299  **/
300  void commit(const QByteArray &text);
301 
302  /**
303  * Sets the cursor position inside the composing text (as byte offset) relative to the
304  * start of the composing text. When @p index is a negative number no cursor is shown.
305  *
306  * The Client applies the @p index together with {@link preEdit}.
307  * @param index The cursor position relative to the start of the composing text
308  * @see preEdit
309  **/
310  void setPreEditCursor(qint32 index);
311 
312  /**
313  * Notify when the text around the current cursor position should be deleted.
314  *
315  * The Client processes this event together with the commit string
316  *
317  * @param beforeLength length of text before current cursor position.
318  * @param afterLength length of text after current cursor position.
319  * @see commit
320  **/
321  void deleteSurroundingText(quint32 beforeLength, quint32 afterLength);
322 
323  /**
324  * Notify when the cursor @p index or @p anchor position should be modified.
325  *
326  * The Client applies this together with the commit string.
327  **/
328  void setCursorPosition(qint32 index, qint32 anchor);
329 
330  /**
331  * Sets the text @p direction of input text.
332  **/
333  void setTextDirection(Qt::LayoutDirection direction);
334 
335  void keysymPressed(quint32 keysym, Qt::KeyboardModifiers modifiers = Qt::NoModifier);
336  void keysymReleased(quint32 keysym, Qt::KeyboardModifiers modifiers = Qt::NoModifier);
337 
338  /**
339  * Informs the client about changes in the visibility of the input panel (virtual keyboard).
340  *
341  * The @p overlappedSurfaceArea defines the area overlapped by the input panel (virtual keyboard)
342  * on the SurfaceInterface having the text focus in surface local coordinates.
343  *
344  * @param visible Whether the input panel is currently visible
345  * @param overlappedSurfaceArea The overlapping area in surface local coordinates
346  **/
347  void setInputPanelState(bool visible, const QRect &overlappedSurfaceArea);
348 
349  /**
350  * Sets the language of the input text. The @p languageTag is a RFC-3066 format language tag.
351  **/
352  void setLanguage(const QByteArray &languageTag);
353 
354 Q_SIGNALS:
355  /**
356  * Requests input panels (virtual keyboard) to show.
357  * @see requestHideInputPanel
358  **/
359  void requestShowInputPanel();
360  /**
361  * Requests input panels (virtual keyboard) to hide.
362  * @see requestShowInputPanel
363  **/
364  void requestHideInputPanel();
365  /**
366  * Invoked by the client when the input state should be
367  * reset, for example after the text was changed outside of the normal
368  * input method flow.
369  **/
370  void requestReset();
371  /**
372  * Emitted whenever the preferred @p language changes.
373  * @see preferredLanguage
374  **/
375  void preferredLanguageChanged(const QByteArray &language);
376  /**
377  * @see cursorRectangle
378  **/
379  void cursorRectangleChanged(const QRect &rect);
380  /**
381  * Emitted when the {@link contentPurpose} and/or {@link contentHints} changes.
382  * @see contentPurpose
383  * @see contentHints
384  **/
385  void contentTypeChanged();
386  /**
387  * Emitted when the {@link surroundingText}, {@link surroundingTextCursorPosition}
388  * and/or {@link surroundingTextSelectionAnchor} changed.
389  * @see surroundingText
390  * @see surroundingTextCursorPosition
391  * @see surroundingTextSelectionAnchor
392  **/
393  void surroundingTextChanged();
394  /**
395  * Emitted whenever this TextInputInterface gets enabled or disabled for a SurfaceInterface.
396  * @see isEnabled
397  * @see surface
398  **/
399  void enabledChanged();
400 
401 protected:
402  class Private;
403  explicit TextInputInterface(Private *p, QObject *parent = nullptr);
404 
405 private:
406  friend class TextInputManagerUnstableV0Interface;
407  friend class TextInputManagerUnstableV2Interface;
408  friend class SeatInterface;
409 
410  Private *d_func() const;
411 };
412 
413 Q_DECLARE_OPERATORS_FOR_FLAGS(TextInputInterface::ContentHints)
414 
415 }
416 }
417 
419 Q_DECLARE_METATYPE(KWayland::Server::TextInputInterface *)
423 
424 #endif
typedef KeyboardModifiers
ContentPurpose
The ContentPurpose allows to specify the primary purpose of a text input.
ContentHint
ContentHint allows to modify the behavior of the text input.
Represents a generic Resource for a text input object.
LayoutDirection
TextInputInterfaceVersion
Enum describing the different InterfaceVersion encapsulated in this implementation.
Represents a Seat on the Wayland Display.
wl_text_input as the non-standardized version
Base class for all Globals.
Definition: global.h:46
Email
Represent the Global for the interface.
Represents a bound Resource.
Definition: resource.h:31
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Thu Sep 23 2021 22:51:10 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.