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 <memory>
14 #include <string>
16 #include <fcitx-utils/flags.h>
17 #include <fcitx-utils/key.h>
18 #include <fcitx-utils/macros.h>
19 #include <fcitx-utils/rect.h>
21 #include <fcitx/event.h>
23 #include <fcitx/surroundingtext.h>
24 #include <fcitx/text.h>
25 #include <fcitx/userinterface.h>
26 #include "fcitxcore_export.h"
27 
28 /// \addtogroup FcitxCore
29 /// \{
30 /// \file
31 /// \brief Input Context for Fcitx.
32 
33 namespace fcitx {
34 typedef std::array<uint8_t, 16> ICUUID;
35 
36 class InputContextManager;
37 class FocusGroup;
38 class InputContextPrivate;
39 class InputContextProperty;
40 class InputPanel;
41 class StatusArea;
42 typedef std::function<bool(InputContext *ic)> InputContextVisitor;
43 
44 /**
45  * An input context represents a client of Fcitx. It can be a Window, or a text
46  * field depending on the application.
47  *
48  */
49 class FCITXCORE_EXPORT InputContext : public TrackableObject<InputContext> {
50  friend class InputContextManagerPrivate;
51  friend class FocusGroup;
52  friend class UserInterfaceManager;
53 
54 public:
55  InputContext(InputContextManager &manager, const std::string &program = {});
56  virtual ~InputContext();
57  InputContext(InputContext &&other) = delete;
58 
59  /// Returns the underlying implementation of Input Context.
60  virtual const char *frontend() const = 0;
61 
62  /// Returns the uuid of this input context.
63  const ICUUID &uuid() const;
64 
65  /// Returns the program name of input context. It can be empty depending on
66  /// the application.
67  const std::string &program() const;
68 
69  /// Returns the display server of the client. In form of type:string, E.g.
70  /// client from X11 server of :0 will become x11::0.
71  std::string display() const;
72 
73  /// Returns the cursor position of the client.
74  const Rect &cursorRect() const;
75 
76  /// Return the client scale factor.
77  double scaleFactor() const;
78 
79  // Following functions should only be called by Frontend.
80  // Calling following most of folloing functions will generate a
81  // corresponding InputContextEvent.
82 
83  /// Called When input context gains the input focus.
84  void focusIn();
85 
86  /// Called when input context losts the input focus.
87  void focusOut();
88 
89  /**
90  * Set the focus group of this input context. group can be null if it does
91  * not belong to any group.
92  *
93  * @see FocusGroup
94  */
95  void setFocusGroup(FocusGroup *group);
96 
97  /// Returns the current focus group of input context.
98  FocusGroup *focusGroup() const;
99 
100  /// Called when input context state need to be reset.
101  FCITXCORE_DEPRECATED void reset(ResetReason reason);
102 
103  /// Called when input context state need to be reset. Input context need to
104  /// have focus.
105  void reset();
106 
107  /**
108  * Update the capability flags of the input context.
109  *
110  * @see CapabilityFlag
111  */
112  void setCapabilityFlags(CapabilityFlags flags);
113 
114  /**
115  * Returns the current capability flags
116  *
117  * @see CapabilityFlag
118  */
119  CapabilityFlags capabilityFlags() const;
120 
121  /// Override the preedit hint from client.
122  void setEnablePreedit(bool enable);
123 
124  /// Check if preedit is manually disalbed.
125  bool isPreeditEnabled() const;
126 
127  /// Update the current cursor rect of the input context.
128  void setCursorRect(Rect rect);
129 
130  /// Update the client rect with scale factor.
131  void setCursorRect(Rect rect, double scale);
132 
133  /// Send a key event to current input context.
134  bool keyEvent(KeyEvent &event);
135 
136  /// Returns whether the input context holds the input focus. Input context
137  /// need to have focus.
138  bool hasFocus() const;
139 
140  /// Invoke an action on the preedit
141  void invokeAction(InvokeActionEvent &event);
142 
143  /**
144  * Returns the mutable surrounding text of the input context.
145  *
146  * updateSurroundingText() need to be called after changes by frontend.
147  *
148  * @see InputContext::updateSurroundingText SurroundingText
149  */
150  SurroundingText &surroundingText();
151 
152  /// Returns the immutable surrounding text of the input context.
153  const SurroundingText &surroundingText() const;
154 
155  /// Notifies the surrounding text modification from the client.
156  void updateSurroundingText();
157 
158  // Following functions are invoked by input method or misc modules to send
159  // event to the corresponding client.
160  /// Commit a string to the client.
161  void commitString(const std::string &text);
162 
163  /// Ask client to delete a range of surrounding text.
164  void deleteSurroundingText(int offset, unsigned int size);
165 
166  /// Send a key event to client.
167  void forwardKey(const Key &rawKey, bool isRelease = false, int time = 0);
168 
169  /**
170  * Notifies client about changes in clientPreedit
171  *
172  * @see InputPanel::clientPreedit
173  */
174  void updatePreedit();
175 
176  /**
177  * Notifies UI about changes in user interface.
178  *
179  * @param component The components of UI that need to be updated.
180  * @param immediate immediately flush the update to UI.
181  *
182  * @see UserInterfaceComponent InputPanel StatusArea
183  */
184  void updateUserInterface(UserInterfaceComponent component,
185  bool immediate = false);
186 
187  /**
188  * Prevent event deliver to input context, and re-send the event later.
189  *
190  * This should be only used by frontend to make sync and async event handled
191  * in the same order.
192  *
193  * @param block block state of input context.
194  *
195  * @see InputContextEventBlocker
196  */
197  void setBlockEventToClient(bool block);
198  bool hasPendingEvents() const;
199 
200  /// Returns the input context property by name.
201  InputContextProperty *property(const std::string &name);
202 
203  /// Returns the input context property by factory.
204  InputContextProperty *property(const InputContextPropertyFactory *factory);
205 
206  /// Returns the associated input panel.
207  InputPanel &inputPanel();
208 
209  /// Returns the associated StatusArea.
210  StatusArea &statusArea();
211 
212  /**
213  * Helper function to return the input context property in specific type.
214  *
215  * @param T type of the input context property.
216  * @param name name of the input context property.
217  * @return T*
218  */
219  template <typename T>
220  T *propertyAs(const std::string &name) {
221  return static_cast<T *>(property(name));
222  }
223 
224  /**
225  * Helper function to return the input context property in specific type by
226  * given factory.
227  *
228  * @param T type of the input context property factory.
229  * @param name name of the input context property.
230  * @return T*
231  */
232  template <typename T>
233  typename T::PropertyType *propertyFor(const T *factory) {
234  return static_cast<typename T::PropertyType *>(property(factory));
235  }
236 
237  /**
238  * Notifes the change of a given input context property
239  *
240  * @param name name of the input context property.
241  *
242  * @see InputContextProperty::copyTo
243  */
244  void updateProperty(const std::string &name);
245 
246  /**
247  * Notifes the change of a given input context property by its factory.
248  *
249  * @param name name of the input context property.
250  *
251  * @see InputContextProperty::copyTo
252  */
253  void updateProperty(const InputContextPropertyFactory *factory);
254 
255 protected:
256  /**
257  * Send the committed string to client
258  *
259  * @param text string
260  *
261  * @see commitString
262  */
263  virtual void commitStringImpl(const std::string &text) = 0;
264 
265  /**
266  * Send the delete Surrounding Text request to client.
267  *
268  * @param offset offset of deletion start, in UCS4 char.
269  * @param size length of the deletion in UCS4 char.
270  */
271  virtual void deleteSurroundingTextImpl(int offset, unsigned int size) = 0;
272 
273  /**
274  * Send the forwarded key to client
275  *
276  * @see forwardKey
277  */
278  virtual void forwardKeyImpl(const ForwardKeyEvent &key) = 0;
279 
280  /**
281  * Send the preedit update to the client.
282  *
283  * @see updatePreedit
284  */
285  virtual void updatePreeditImpl() = 0;
286 
287  /**
288  * Send the UI update to client.
289  *
290  * @see CapabilityFlag::ClientSideUI
291  */
292  virtual void updateClientSideUIImpl();
293 
294  /// Notifies the destruction of the input context. Need to be called in the
295  /// destructor.
296  void destroy();
297 
298  /// Notifies the creation of input context. Need to be called at the end of
299  /// the constructor.
300  void created();
301 
302 private:
303  void setHasFocus(bool hasFocus);
304 
305  std::unique_ptr<InputContextPrivate> d_ptr;
306  FCITX_DECLARE_PRIVATE(InputContext);
307 };
308 
309 /**
310  * A helper class for frontend addon. It use RAII to call
311  * setBlockEventToClient(true) in constructor and setBlockEventToClient(false)
312  * in destructor.
313  *
314  */
315 class FCITXCORE_EXPORT InputContextEventBlocker {
316 public:
317  InputContextEventBlocker(InputContext *inputContext);
319 
320 private:
322 };
323 
324 } // namespace fcitx
325 
326 #endif // _FCITX_INPUTCONTEXT_H_
Utility class provides a weak reference to the object.
Describe a Key in fcitx.
Definition: key.h:40
T::PropertyType * propertyFor(const T *factory)
Helper function to return the input context property in specific type by given factory.
Definition: inputcontext.h:233
Formatted string commonly used in user interface.
Utitliy classes for statically tracking the life of a object.
Definition: action.cpp:12
T * propertyAs(const std::string &name)
Helper function to return the input context property in specific type.
Definition: inputcontext.h:220
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:47
Base class for User Interface addon.
Class represents the current state of surrounding text of an input context.
A helper class for frontend addon.
Definition: inputcontext.h:315
Helper class to be used with TrackableObjectReference.
UserInterfaceComponent
Definition: userinterface.h:23
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
Helper template class to make easier to use type safe enum flags.
Input Context Property for Fcitx.
An input context represents a client of Fcitx.
Definition: inputcontext.h:49
Class to represent a key.
This is a class that designed to store state that is specific to certain input context.