Fcitx
inputcontext.h
Go to the documentation of this file.
1 /*
2  * SPDX-FileCopyrightText: 2016-2016 CSSlayer <wengxt@gmail.com>
3  *
4  * SPDX-License-Identifier: LGPL-2.1-or-later
5  *
6  */
7 
8 #ifndef _FCITX_INPUTCONTEXT_H_
9 #define _FCITX_INPUTCONTEXT_H_
10 
11 #include <array>
12 #include <cstdint>
13 #include <functional>
14 #include <memory>
15 #include <string>
16 #include <string_view>
18 #include <fcitx-utils/macros.h>
19 #include <fcitx-utils/rect.h>
21 #include <fcitx/event.h>
22 #include <fcitx/fcitxcore_export.h>
24 #include <fcitx/surroundingtext.h>
25 
26 /// \addtogroup FcitxCore
27 /// \{
28 /// \file
29 /// \brief Input Context for Fcitx.
30 
31 namespace fcitx {
32 using ICUUID = std::array<uint8_t, 16>;
33 
34 class InputContextManager;
35 class FocusGroup;
36 class InputContextPrivate;
37 class InputContextProperty;
38 class InputPanel;
39 class StatusArea;
40 using InputContextVisitor = std::function<bool(InputContext *ic)>;
41 
42 /**
43  * An input context represents a client of Fcitx. It can be a Window, or a text
44  * field depending on the application.
45  *
46  */
47 class FCITXCORE_EXPORT InputContext : public TrackableObject<InputContext> {
48  friend class InputContextManagerPrivate;
49  friend class FocusGroup;
50  friend class UserInterfaceManager;
51  friend class UserInterfaceManagerPrivate;
52 
53 public:
54  InputContext(InputContextManager &manager, const std::string &program = {});
55  virtual ~InputContext();
56  InputContext(InputContext &&other) = delete;
57 
58  /// Returns the underlying implementation of Input Context.
59  virtual const char *frontend() const = 0;
60 
61  /**
62  * Return the frontend name.
63  *
64  * Helper function that simply calls InputContext::frontend, but returns a
65  * string_view.
66  *
67  * @since 5.0.22
68  */
69  std::string_view frontendName() const;
70 
71  /// Returns the uuid of this input context.
72  const ICUUID &uuid() const;
73 
74  /// Returns the program name of input context. It can be empty depending on
75  /// the application.
76  const std::string &program() const;
77 
78  /// Returns the display server of the client. In form of type:string, E.g.
79  /// client from X11 server of :0 will become x11::0.
80  std::string display() const;
81 
82  /// Returns the cursor position of the client.
83  const Rect &cursorRect() const;
84 
85  /// Return the client scale factor.
86  double scaleFactor() const;
87 
88  // Following functions should only be called by Frontend.
89  // Calling following most of following functions will generate a
90  // corresponding InputContextEvent.
91 
92  /// Called When input context gains the input focus.
93  void focusIn();
94 
95  /// Called when input context losts the input focus.
96  void focusOut();
97 
98  /**
99  * Set the focus group of this input context. group can be null if it does
100  * not belong to any group.
101  *
102  * @see FocusGroup
103  */
104  void setFocusGroup(FocusGroup *group);
105 
106  /// Returns the current focus group of input context.
107  FocusGroup *focusGroup() const;
108 
109  /// Called when input context state need to be reset.
110  FCITXCORE_DEPRECATED void reset(ResetReason reason);
111 
112  /// Called when input context state need to be reset. Input context need to
113  /// have focus.
114  void reset();
115 
116  /**
117  * Update the capability flags of the input context.
118  *
119  * @see CapabilityFlag
120  */
121  void setCapabilityFlags(CapabilityFlags flags);
122 
123  /**
124  * Returns the current capability flags
125  *
126  * @see CapabilityFlag
127  */
128  CapabilityFlags capabilityFlags() const;
129 
130  /// Override the preedit hint from client.
131  void setEnablePreedit(bool enable);
132 
133  /// Check if preedit is manually disabled.
134  bool isPreeditEnabled() const;
135 
136  /// Update the current cursor rect of the input context.
137  void setCursorRect(Rect rect);
138 
139  /// Update the client rect with scale factor.
140  void setCursorRect(Rect rect, double scale);
141 
142  /// Send a key event to current input context.
143  bool keyEvent(KeyEvent &event);
144 
145  /**
146  * Send a virtual keyboard event to current input context.
147  *
148  * @param event virtual keyboard event
149  * @return whether event is accepted.
150  * @since 5.1.0
151  */
152  bool virtualKeyboardEvent(VirtualKeyboardEvent &event);
153 
154  /// Returns whether the input context holds the input focus. Input context
155  /// need to have focus.
156  bool hasFocus() const;
157 
158  /// Invoke an action on the preedit
159  void invokeAction(InvokeActionEvent &event);
160 
161  /**
162  * Returns the mutable surrounding text of the input context.
163  *
164  * updateSurroundingText() need to be called after changes by frontend.
165  *
166  * @see InputContext::updateSurroundingText SurroundingText
167  */
168  SurroundingText &surroundingText();
169 
170  /// Returns the immutable surrounding text of the input context.
171  const SurroundingText &surroundingText() const;
172 
173  /// Notifies the surrounding text modification from the client.
174  void updateSurroundingText();
175 
176  // Following functions are invoked by input method or misc modules to send
177  // event to the corresponding client.
178  /// Commit a string to the client.
179  void commitString(const std::string &text);
180 
181  /**
182  * Commit a string to application with a cursor location after commit.
183  *
184  * @param text text to commit
185  * @param cursor cursor position after commit, the value should be within
186  * [0, utf8::length(text)].
187  * @see CapabilityFlag::CommitStringWithCursor
188  */
189  void commitStringWithCursor(const std::string &text, size_t cursor);
190 
191  /// Ask client to delete a range of surrounding text.
192  void deleteSurroundingText(int offset, unsigned int size);
193 
194  /// Send a key event to client.
195  void forwardKey(const Key &rawKey, bool isRelease = false, int time = 0);
196 
197  /**
198  * Notifies client about changes in clientPreedit
199  *
200  * @see InputPanel::clientPreedit
201  */
202  void updatePreedit();
203 
204  /**
205  * Notifies UI about changes in user interface.
206  *
207  * @param component The components of UI that need to be updated.
208  * @param immediate immediately flush the update to UI.
209  *
210  * @see UserInterfaceComponent InputPanel StatusArea
211  */
212  void updateUserInterface(UserInterfaceComponent component,
213  bool immediate = false);
214 
215  /**
216  * Prevent event deliver to input context, and re-send the event later.
217  *
218  * This should be only used by frontend to make sync and async event handled
219  * in the same order.
220  *
221  * @param block block state of input context.
222  *
223  * @see InputContextEventBlocker
224  */
225  void setBlockEventToClient(bool block);
226  bool hasPendingEvents() const;
227 
228  /**
229  * Has pending event that need to use key order fix.
230  *
231  * If pending event only have preedit, then it's generally fine to not use
232  * key forward.
233  *
234  * @since 5.0.21
235  */
236  bool hasPendingEventsStrictOrder() const;
237 
238  /// Returns the input context property by name.
239  InputContextProperty *property(const std::string &name);
240 
241  /// Returns the input context property by factory.
242  InputContextProperty *property(const InputContextPropertyFactory *factory);
243 
244  /// Returns the associated input panel.
245  InputPanel &inputPanel();
246 
247  /**
248  * Returns the associated input panel.
249  *
250  * @since 5.0.22
251  */
252  const InputPanel &inputPanel() const;
253 
254  /// Returns the associated StatusArea.
255  StatusArea &statusArea();
256 
257  /**
258  * Returns the associated StatusArea.
259  *
260  * @since 5.0.22
261  */
262  const StatusArea &statusArea() const;
263 
264  /**
265  * Helper function to return the input context property in specific type.
266  *
267  * @param T type of the input context property.
268  * @param name name of the input context property.
269  * @return T*
270  */
271  template <typename T>
272  T *propertyAs(const std::string &name) {
273  return static_cast<T *>(property(name));
274  }
275 
276  /**
277  * Helper function to return the input context property in specific type by
278  * given factory.
279  *
280  * @param T type of the input context property factory.
281  * @param name name of the input context property.
282  * @return T*
283  */
284  template <typename T>
285  typename T::PropertyType *propertyFor(const T *factory) {
286  return static_cast<typename T::PropertyType *>(property(factory));
287  }
288 
289  /**
290  * Notifies the change of a given input context property
291  *
292  * @param name name of the input context property.
293  *
294  * @see InputContextProperty::copyTo
295  */
296  void updateProperty(const std::string &name);
297 
298  /**
299  * Notifies the change of a given input context property by its factory.
300  *
301  * @param name name of the input context property.
302  *
303  * @see InputContextProperty::copyTo
304  */
305  void updateProperty(const InputContextPropertyFactory *factory);
306 
307  bool isVirtualKeyboardVisible() const;
308 
309  void showVirtualKeyboard() const;
310 
311  void hideVirtualKeyboard() const;
312 
313  bool clientControlVirtualkeyboardShow() const;
314 
315  void setClientControlVirtualkeyboardShow(bool show);
316 
317  bool clientControlVirtualkeyboardHide() const;
318 
319  void setClientControlVirtualkeyboardHide(bool show);
320 
321 protected:
322  /**
323  * Send the committed string to client
324  *
325  * @param text string
326  *
327  * @see commitString
328  */
329  virtual void commitStringImpl(const std::string &text) = 0;
330 
331  /**
332  * Send the delete Surrounding Text request to client.
333  *
334  * @param offset offset of deletion start, in UCS4 char.
335  * @param size length of the deletion in UCS4 char.
336  */
337  virtual void deleteSurroundingTextImpl(int offset, unsigned int size) = 0;
338 
339  /**
340  * Send the forwarded key to client
341  *
342  * @see forwardKey
343  */
344  virtual void forwardKeyImpl(const ForwardKeyEvent &key) = 0;
345 
346  /**
347  * Send the preedit update to the client.
348  *
349  * @see updatePreedit
350  */
351  virtual void updatePreeditImpl() = 0;
352 
353  /**
354  * Send the UI update to client.
355  *
356  * @see CapabilityFlag::ClientSideUI
357  */
358  virtual void updateClientSideUIImpl();
359 
360  /// Notifies the destruction of the input context. Need to be called in the
361  /// destructor.
362  void destroy();
363 
364  /// Notifies the creation of input context. Need to be called at the end of
365  /// the constructor.
366  void created();
367 
368 private:
369  void setHasFocus(bool hasFocus);
370 
371  std::unique_ptr<InputContextPrivate> d_ptr;
372  FCITX_DECLARE_PRIVATE(InputContext);
373 };
374 
375 class FCITXCORE_EXPORT InputContextV2 : public InputContext {
376  friend class InputContextPrivate;
377 
378 public:
379  using InputContext::InputContext;
380  ~InputContextV2() override;
381 
382 protected:
383  virtual void commitStringWithCursorImpl(const std::string &text,
384  size_t cursor) = 0;
385 };
386 
387 /**
388  * A helper class for frontend addon. It use RAII to call
389  * setBlockEventToClient(true) in constructor and setBlockEventToClient(false)
390  * in destructor.
391  *
392  */
393 class FCITXCORE_EXPORT InputContextEventBlocker {
394 public:
395  InputContextEventBlocker(InputContext *inputContext);
397 
398 private:
400 };
401 
402 } // namespace fcitx
403 
404 #endif // _FCITX_INPUTCONTEXT_H_
Utility class provides a weak reference to the object.
Describe a Key in fcitx.
Definition: key.h:41
T::PropertyType * propertyFor(const T *factory)
Helper function to return the input context property in specific type by given factory.
Definition: inputcontext.h:285
Utitliy classes for statically tracking the life of a object.
Definition: action.cpp:17
T * propertyAs(const std::string &name)
Helper function to return the input context property in specific type.
Definition: inputcontext.h:272
Local cache for surrounding text.
Provide utility to handle rectangle.
Enum type for input context capability.
Input Panel is usually a floating window that is display at the cursor of input.
Definition: inputpanel.h:48
Class represents the current state of surrounding text of an input context.
A helper class for frontend addon.
Definition: inputcontext.h:393
Helper class to be used with TrackableObjectReference.
UserInterfaceComponent
Definition: userinterface.h:21
Status area represent a list of actions and action may have sub actions.
Definition: statusarea.h:44
Factory class for input context property.
Class provides bit flag support for Enum.
Definition: flags.h:33
Input Method event for Fcitx.
Input Context Property for Fcitx.
An input context represents a client of Fcitx.
Definition: inputcontext.h:47
This is a class that designed to store state that is specific to certain input context.