KWayland

textinput.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_CLIENT_TEXTINPUT_H
7 #define KWAYLAND_CLIENT_TEXTINPUT_H
8 
9 #include <QObject>
10 
11 #include <KWayland/Client/kwaylandclient_export.h>
12 
13 struct wl_text_input;
14 struct wl_text_input_manager;
15 struct zwp_text_input_manager_v2;
16 
17 namespace KWayland
18 {
19 namespace Client
20 {
21 
22 class EventQueue;
23 class TextInputUnstableV0;
24 class Surface;
25 class Seat;
26 
27 /**
28  * @brief TextInput represents a Wayland interface for text input.
29  *
30  * The TextInput allows to have text composed by the Compositor and be sent to
31  * the client.
32  *
33  * Depending on the interface the TextInputManager got created for this class
34  * encapsulates one of the following interfaces:
35  * @li wl_text_input
36  * @li zwp_text_input_v2
37  *
38  * @since 5.23
39  **/
40 class KWAYLANDCLIENT_EXPORT TextInput : public QObject
41 {
42  Q_OBJECT
43 public:
44  virtual ~TextInput();
45  /**
46  * @returns @c true if managing a resource.
47  **/
48  bool isValid() const;
49 
50  /**
51  * @returns The Surface which has the text input focus on this TextInput.
52  * @see entered
53  * @see left
54  **/
55  Surface *enteredSurface() const;
56 
57  void setEventQueue(EventQueue *queue);
58  EventQueue *eventQueue() const;
59 
60  /**
61  * @returns whether the input panel (virtual keyboard) is currently visible on the screen
62  * @see inputPanelStateChanged
63  **/
64  bool isInputPanelVisible() const;
65 
66  /**
67  * Enable text input in a @p surface (usually when a text entry inside of it has focus).
68  *
69  * This can be called before or after a surface gets text (or keyboard) focus via the
70  * enter event. Text input to a surface is only active when it has the current
71  * text (or keyboard) focus and is enabled.
72  * @see deactivate
73  **/
74  void enable(Surface *surface);
75 
76  /**
77  * Disable text input in a @p surface (typically when there is no focus on any
78  * text entry inside the surface).
79  * @see enable
80  **/
81  void disable(Surface *surface);
82 
83  /**
84  * Requests input panels (virtual keyboard) to show.
85  * @see hideInputPanel
86  **/
87  void showInputPanel();
88 
89  /**
90  * Requests input panels (virtual keyboard) to hide.
91  * @see showInputPanel
92  **/
93  void hideInputPanel();
94 
95  /**
96  * Should be called by an editor widget when the input state should be
97  * reset, for example after the text was changed outside of the normal
98  * input method flow.
99  **/
100  void reset();
101 
102  /**
103  * Sets the plain surrounding text around the input position.
104  *
105  * @param text The text surrounding the cursor position
106  * @param cursor Index in the text describing the cursor position
107  * @param anchor Index of the selection anchor, if no selection same as cursor
108  **/
109  void setSurroundingText(const QString &text, quint32 cursor, quint32 anchor);
110 
111  /**
112  * The possible states for a keyEvent.
113  * @see keyEvent
114  **/
115  enum class KeyState {
116  Pressed,
117  Released
118  };
119 
120  /**
121  * ContentHint allows to modify the behavior of the text input.
122  **/
123  enum class ContentHint : uint32_t {
124  /**
125  * no special behaviour
126  */
127  None = 0,
128  /**
129  * suggest word completions
130  */
131  AutoCompletion = 1 << 0,
132  /**
133  * suggest word corrections
134  */
135  AutoCorrection = 1 << 1,
136  /**
137  * switch to uppercase letters at the start of a sentence
138  */
139  AutoCapitalization = 1 << 2,
140  /**
141  * prefer lowercase letters
142  */
143  LowerCase = 1 << 3,
144  /**
145  * prefer uppercase letters
146  */
147  UpperCase = 1 << 4,
148  /**
149  * prefer casing for titles and headings (can be language dependent)
150  */
151  TitleCase = 1 << 5,
152  /**
153  * characters should be hidden
154  */
155  HiddenText = 1 << 6,
156  /**
157  * typed text should not be stored
158  */
159  SensitiveData = 1 << 7,
160  /**
161  * just latin characters should be entered
162  */
163  Latin = 1 << 8,
164  /**
165  * the text input is multi line
166  */
167  MultiLine = 1 << 9
168  };
169  Q_DECLARE_FLAGS(ContentHints, ContentHint)
170 
171  /**
172  * The ContentPurpose allows to specify the primary purpose of a text input.
173  *
174  * This allows an input method to show special purpose input panels with
175  * extra characters or to disallow some characters.
176  */
177  enum class ContentPurpose : uint32_t {
178  /**
179  * default input, allowing all characters
180  */
181  Normal,
182  /**
183  * allow only alphabetic characters
184  **/
185  Alpha,
186  /**
187  * allow only digits
188  */
189  Digits,
190  /**
191  * input a number (including decimal separator and sign)
192  */
193  Number,
194  /**
195  * input a phone number
196  */
197  Phone,
198  /**
199  * input an URL
200  */
201  Url,
202  /**
203  * input an email address
204  **/
205  Email,
206  /**
207  * input a name of a person
208  */
209  Name,
210  /**
211  * input a password
212  */
213  Password,
214  /**
215  * input a date
216  */
217  Date,
218  /**
219  * input a time
220  */
221  Time,
222  /**
223  * input a date and time
224  */
225  DateTime,
226  /**
227  * input for a terminal
228  */
229  Terminal
230  };
231  /**
232  * Sets the content @p purpose and content @p hints.
233  * While the @p purpose is the basic purpose of an input field, the @p hints flags allow
234  * to modify some of the behavior.
235  **/
236  void setContentType(ContentHints hints, ContentPurpose purpose);
237 
238  /**
239  * Sets the cursor outline @p rect in surface local coordinates.
240  *
241  * Allows the compositor to e.g. put a window with word suggestions
242  * near the cursor.
243  **/
244  void setCursorRectangle(const QRect &rect);
245 
246  /**
247  * Sets a specific @p language.
248  *
249  * This allows for example a virtual keyboard to show a language specific layout.
250  * The @p language argument is a RFC-3066 format language tag.
251  **/
252  void setPreferredLanguage(const QString &language);
253 
254  /**
255  * The text direction of input text.
256  *
257  * It is mainly needed for showing input cursor on correct side of the
258  * editor when there is no input yet done and making sure neutral
259  * direction text is laid out properly.
260  * @see textDirectionChnaged
261  **/
262  Qt::LayoutDirection textDirection() const;
263 
264  /**
265  * The language of the input text.
266  *
267  * As long as the server has not emitted the language, the code will be empty.
268  *
269  * @returns a RFC-3066 format language tag in utf-8.
270  * @see languageChanged
271  **/
272  QByteArray language() const;
273 
274  /**
275  * The cursor position inside the {@link composingText} (as byte offset) relative
276  * to the start of the {@link composingText}.
277  * If index is a negative number no cursor is shown.
278  * @see composingText
279  * @see composingTextChanged
280  **/
281  qint32 composingTextCursorPosition() const;
282 
283  /**
284  * The currently being composed text around the {@link composingTextCursorPosition}.
285  * @see composingTextCursorPosition
286  * @see composingTextChanged
287  **/
288  QByteArray composingText() const;
289 
290  /**
291  * The fallback text can be used to replace the {@link composingText} in some cases
292  * (for example when losing focus).
293  *
294  * @see composingText
295  * @see composingTextChanged
296  **/
297  QByteArray composingFallbackText() const;
298 
299  /**
300  * The commit text to be inserted.
301  *
302  * The commit text might be empty if only text should be deleted or the cursor be moved.
303  * @see cursorPosition
304  * @see anchorPosition
305  * @see deleteSurroundingText
306  * @see committed
307  **/
308  QByteArray commitText() const;
309 
310  /**
311  * The cursor position in bytes at which the {@link commitText} should be inserted.
312  * @see committed
313  **/
314  qint32 cursorPosition() const;
315 
316  /**
317  * The text between anchorPosition and {@link cursorPosition} should be selected.
318  * @see cursorPosition
319  * @see committed
320  **/
321  qint32 anchorPosition() const;
322 
323  /**
324  * Holds the length before and after the cursor position to be deleted.
325  **/
327  quint32 beforeLength;
328  quint32 afterLength;
329  };
330  /**
331  * @returns The length in bytes which should be deleted around the cursor position
332  * @see committed
333  **/
334  DeleteSurroundingText deleteSurroundingText() const;
335 
336 Q_SIGNALS:
337  /**
338  * Emitted whenever a Surface is focused on this TextInput.
339  * @see enteredSurface
340  * @see left
341  **/
342  void entered();
343  /**
344  * Emitted whenever a Surface loses the focus on this TextInput.
345  * @see enteredSurface
346  * @see entered
347  **/
348  void left();
349  /**
350  * Emitted whenever the state of the input panel (virtual keyboard changes).
351  * @see isInputPanelVisible
352  **/
353  void inputPanelStateChanged();
354  /**
355  * Emitted whenver the text direction changes.
356  * @see textDirection
357  **/
358  void textDirectionChanged();
359  /**
360  * Emitted whenever the language changes.
361  * @see language
362  **/
363  void languageChanged();
364 
365  /**
366  * Emitted when a key event was sent.
367  * Key events are not used for normal text input operations, but for specific key symbols
368  * which are not composable through text.
369  *
370  * @param xkbKeySym The XKB key symbol, not a key code
371  * @param state Whether the event represents a press or release event
372  * @param modifiers The hold modifiers on this event
373  * @param time Timestamp of this event
374  **/
375  void keyEvent(quint32 xkbKeySym, KWayland::Client::TextInput::KeyState state, Qt::KeyboardModifiers modifiers, quint32 time);
376 
377  /**
378  * Emitted whenever the composing text and related states changed.
379  * @see composingText
380  * @see composingTextCursorPosition
381  * @see composingFallbackText
382  **/
383  void composingTextChanged();
384 
385  /**
386  * Emitted when the currently composing text got committed.
387  * The {@link commitText} should get inserted at the {@link cursorPosition} and
388  * the text around {@link deleteSurroundingText} should be deleted.
389  *
390  * @see commitText
391  * @see cursorPosition
392  * @see anchorPosition
393  * @see deleteSurroundingText
394  **/
395  void committed();
396 
397 protected:
398  class Private;
400  explicit TextInput(Private *p, QObject *parent = nullptr);
401 };
402 
403 /**
404  * @brief Manager class for the TextInputManager interfaces.
405  *
406  * The TextInputManager supports multiple interfaces:
407  * @li wl_text_input_manager
408  * @li zwp_text_input_manager_v2
409  *
410  * Due to that it is different to other manager classes. It can only be created through
411  * the corresponding factory method in Registry. A manual setup is not directly possible.
412  *
413  * The only task of a TextInputManager is to create TextInput for a given Seat.
414  *
415  * @since 5.23
416  **/
417 class KWAYLANDCLIENT_EXPORT TextInputManager : public QObject
418 {
419  Q_OBJECT
420 public:
421  virtual ~TextInputManager();
422 
423  /**
424  * Setup this TextInputManager to manage the @p textinputmanagerunstablev0.
425  * When using Registry::createTextInputManager there is no need to call this
426  * method.
427  **/
428  void setup(wl_text_input_manager *textinputmanagerunstablev0);
429  /**
430  * Setup this TextInputManager to manage the @p textinputmanagerunstablev0.
431  * When using Registry::createTextInputManager there is no need to call this
432  * method.
433  **/
434  void setup(zwp_text_input_manager_v2 *textinputmanagerunstablev2);
435  /**
436  * @returns @c true if managing a resource.
437  **/
438  bool isValid() const;
439  /**
440  * Releases the interface.
441  * After the interface has been released the TextInputManager instance is no
442  * longer valid and can be setup with another interface.
443  **/
444  void release();
445  /**
446  * Destroys the data held by this TextInputManager.
447  * This method is supposed to be used when the connection to the Wayland
448  * server goes away. If the connection is not valid anymore, it's not
449  * possible to call release anymore as that calls into the Wayland
450  * connection and the call would fail. This method cleans up the data, so
451  * that the instance can be deleted or set up to a new interface
452  * once there is a new connection available.
453  *
454  * This method is automatically invoked when the Registry which created this
455  * TextInput gets destroyed.
456  *
457  * @see release
458  **/
459  void destroy();
460 
461  /**
462  * Sets the @p queue to use for creating objects with this TextInputManager.
463  **/
464  void setEventQueue(EventQueue *queue);
465  /**
466  * @returns The event queue to use for creating objects with this TextInputManager.
467  **/
468  EventQueue *eventQueue();
469 
470  /**
471  * Creates a TextInput for the @p seat.
472  *
473  * @param seat The Seat to create the TextInput for
474  * @param parent The parent to use for the TextInput
475  **/
476  TextInput *createTextInput(Seat *seat, QObject *parent = nullptr);
477 
478  /**
479  * @returns @c null if not for a wl_text_input_manager
480  **/
481  operator wl_text_input_manager*();
482  /**
483  * @returns @c null if not for a wl_text_input_manager
484  **/
485  operator wl_text_input_manager*() const;
486  /**
487  * @returns @c null if not for a zwp_text_input_manager_v2
488  **/
489  operator zwp_text_input_manager_v2*();
490  /**
491  * @returns @c null if not for a zwp_text_input_manager_v2
492  **/
493  operator zwp_text_input_manager_v2*() const;
494 
495 Q_SIGNALS:
496  /**
497  * The corresponding global for this interface on the Registry got removed.
498  *
499  * This signal gets only emitted if the TextInputManager got created by
500  * Registry::createTextInputManager
501  **/
502  void removed();
503 
504 protected:
505  class Private;
506  explicit TextInputManager(Private *p, QObject *parent = nullptr);
507 
509 };
510 
511 Q_DECLARE_OPERATORS_FOR_FLAGS(TextInput::ContentHints)
512 
513 }
514 }
515 
516 Q_DECLARE_METATYPE(KWayland::Client::TextInput::KeyState)
520 
521 #endif
ContentHint
ContentHint allows to modify the behavior of the text input.
Definition: textinput.h:123
typedef KeyboardModifiers
ContentPurpose
The ContentPurpose allows to specify the primary purpose of a text input.
Definition: textinput.h:177
Holds the length before and after the cursor position to be deleted.
Definition: textinput.h:326
Manager class for the TextInputManager interfaces.
Definition: textinput.h:417
Wrapper class for wl_event_queue interface.
Definition: event_queue.h:55
Wrapper for the wl_seat interface.
Definition: seat.h:52
LayoutDirection
Wrapper for the wl_surface interface.
Definition: surface.h:44
TextInput represents a Wayland interface for text input.
Definition: textinput.h:40
KeyState
The possible states for a keyEvent.
Definition: textinput.h:115
This file is part of the KDE documentation.
Documentation copyright © 1996-2021 The KDE developers.
Generated on Mon Mar 8 2021 22:50:09 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.