Flutter macOS Embedder
text_input_model.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef FLUTTER_SHELL_PLATFORM_COMMON_TEXT_INPUT_MODEL_H_
6 #define FLUTTER_SHELL_PLATFORM_COMMON_TEXT_INPUT_MODEL_H_
7 
8 #include <memory>
9 #include <string>
10 
12 
13 namespace flutter {
14 
15 // Handles underlying text input state, using a simple ASCII model.
16 //
17 // Ignores special states like "insert mode" for now.
19  public:
21  virtual ~TextInputModel();
22 
23  // Sets the text, as well as the selection and the composing region.
24  //
25  // This method is typically used to update the TextInputModel's editing state
26  // when the Flutter framework sends its latest text editing state.
27  //
28  // Returns false and leaves the model untouched if |selection| or
29  // |composing_range| does not fit within |text|. Either all three are applied
30  // or none are, so that the model never holds a range that indexes past the
31  // end of its own text.
32  bool SetText(const std::string& text,
33  const TextRange& selection = TextRange(0),
34  const TextRange& composing_range = TextRange(0));
35 
36  // Attempts to set the text selection.
37  //
38  // Returns false if the selection is not within the bounds of the text.
39  // While in composing mode, the selection is restricted to the composing
40  // range; otherwise, it is restricted to the length of the text.
41  //
42  // To update both the text and the selection/composing range within the text
43  // (for instance, when the framework sends its latest text editing state),
44  // call |SetText| instead.
45  bool SetSelection(const TextRange& range);
46 
47  // Attempts to set the composing range.
48  //
49  // Returns false if the range or offset are out of range for the text, or if
50  // the offset is outside the composing range.
51  //
52  // To update both the text and the selection/composing range within the text
53  // (for instance, when the framework sends its latest text editing state),
54  // call |SetText| instead.
55  bool SetComposingRange(const TextRange& range, size_t cursor_offset);
56 
57  // Begins IME composing mode.
58  //
59  // Resets the composing base and extent to the selection start. The existing
60  // selection is preserved in case composing is aborted with no changes. Until
61  // |EndComposing| is called, any further changes to selection base and extent
62  // are restricted to the composing range.
63  void BeginComposing();
64 
65  // Replaces the composing range with new UTF-16 text, and sets the selection.
66  //
67  // The given |text| replaces text within the current composing range, or the
68  // current selection if the text wasn't composing. The composing range is
69  // adjusted to the length of |text|, and the |selection| describes the new
70  // selection range, relative to the start of the new composing range.
71  void UpdateComposingText(const std::u16string& text,
72  const TextRange& selection);
73 
74  // Replaces the composing range with new UTF-16 text and sets the selection to
75  // the end of the composing text.
76  void UpdateComposingText(const std::u16string& text);
77 
78  // Replaces the composing range with new UTF-8 text.
79  //
80  // If a selection of non-zero length exists, it is deleted if the composing
81  // text is non-empty. The composing range is adjusted to the length of
82  // |text| and the selection base and offset are set to the end of the
83  // composing range.
84  void UpdateComposingText(const std::string& text);
85 
86  // Commits composing range to the string.
87  //
88  // Causes the composing base and extent to be collapsed to the end of the
89  // range.
90  void CommitComposing();
91 
92  // Ends IME composing mode.
93  //
94  // Collapses the composing base and offset to 0.
95  void EndComposing();
96 
97  // Adds a Unicode code point.
98  //
99  // Either appends after the cursor (when selection base and extent are the
100  // same), or deletes the selected text, replacing it with the given
101  // code point.
102  void AddCodePoint(char32_t c);
103 
104  // Adds UTF-16 text.
105  //
106  // Either appends after the cursor (when selection base and extent are the
107  // same), or deletes the selected text, replacing it with the given text.
108  void AddText(const std::u16string& text);
109 
110  // Adds UTF-8 text.
111  //
112  // Either appends after the cursor (when selection base and extent are the
113  // same), or deletes the selected text, replacing it with the given text.
114  void AddText(const std::string& text);
115 
116  // Deletes either the selection, or one character ahead of the cursor.
117  //
118  // Deleting one character ahead of the cursor occurs when the selection base
119  // and extent are the same. When composing is active, deletions are
120  // restricted to text between the composing base and extent.
121  //
122  // Returns true if any deletion actually occurred.
123  bool Delete();
124 
125  // Deletes text near the cursor.
126  //
127  // A section is made starting at |offset_from_cursor| code points past the
128  // cursor (negative values go before the cursor). |count| code points are
129  // removed. The selection may go outside the bounds of the available text and
130  // will result in only the part selection that covers the available text
131  // being deleted. The existing selection is ignored and removed after this
132  // operation. When composing is active, deletions are restricted to the
133  // composing range.
134  //
135  // Returns true if any deletion actually occurred.
136  bool DeleteSurrounding(int offset_from_cursor, int count);
137 
138  // Deletes either the selection, or one character behind the cursor.
139  //
140  // Deleting one character behind the cursor occurs when the selection base
141  // and extent are the same. When composing is active, deletions are
142  // restricted to the text between the composing base and extent.
143  //
144  // Returns true if any deletion actually occurred.
145  bool Backspace();
146 
147  // Attempts to move the cursor backward.
148  //
149  // Returns true if the cursor could be moved. If a selection is active, moves
150  // to the start of the selection. If composing is active, motion is
151  // restricted to the composing range.
152  bool MoveCursorBack();
153 
154  // Attempts to move the cursor forward.
155  //
156  // Returns true if the cursor could be moved. If a selection is active, moves
157  // to the end of the selection. If composing is active, motion is restricted
158  // to the composing range.
159  bool MoveCursorForward();
160 
161  // Attempts to move the cursor to the beginning.
162  //
163  // If composing is active, the cursor is moved to the beginning of the
164  // composing range; otherwise, it is moved to the beginning of the text. If
165  // composing is active, motion is restricted to the composing range.
166  //
167  // Returns true if the cursor could be moved.
168  bool MoveCursorToBeginning();
169 
170  // Attempts to move the cursor to the end.
171  //
172  // If composing is active, the cursor is moved to the end of the composing
173  // range; otherwise, it is moved to the end of the text. If composing is
174  // active, motion is restricted to the composing range.
175  //
176  // Returns true if the cursor could be moved.
177  bool MoveCursorToEnd();
178 
179  // Attempts to select text from the cursor position to the beginning.
180  //
181  // If composing is active, the selection is applied to the beginning of the
182  // composing range; otherwise, it is applied to the beginning of the text.
183  //
184  // Returns true if the selection could be applied.
185  bool SelectToBeginning();
186 
187  // Attempts to select text from the cursor position to the end.
188  //
189  // If composing is active, the selection is applied to the end of the
190  // composing range; otherwise, it is moved to the end of the text.
191  //
192  // Returns true if the selection could be applied.
193  bool SelectToEnd();
194 
195  // Gets the current text as UTF-8.
196  std::string GetText() const;
197 
198  // Gets the cursor position as a byte offset in UTF-8 string returned from
199  // GetText().
200  int GetCursorOffset() const;
201 
202  // Returns a range covering the entire text.
203  TextRange text_range() const { return TextRange(0, text_.length()); }
204 
205  // The current selection.
206  TextRange selection() const { return selection_; }
207 
208  // The composing range.
209  //
210  // If not in composing mode, returns a collapsed range at position 0.
211  TextRange composing_range() const { return composing_range_; }
212 
213  // Whether multi-step input composing mode is active.
214  bool composing() const { return composing_; }
215 
216  private:
217  // Deletes the current selection, if any.
218  //
219  // Returns true if any text is deleted. The selection base and extent are
220  // reset to the start of the selected range.
221  bool DeleteSelected();
222 
223  // Returns the currently editable text range.
224  //
225  // In composing mode, returns the composing range; otherwise, returns a range
226  // covering the entire text.
227  TextRange editable_range() const {
228  return composing_ ? composing_range_ : text_range();
229  }
230 
231  std::u16string text_;
232  TextRange selection_ = TextRange(0);
233  TextRange composing_range_ = TextRange(0);
234  bool composing_ = false;
235 };
236 
237 } // namespace flutter
238 
239 #endif // FLUTTER_SHELL_PLATFORM_COMMON_TEXT_INPUT_MODEL_H_
TextRange selection() const
std::string GetText() const
bool DeleteSurrounding(int offset_from_cursor, int count)
void AddText(const std::u16string &text)
void AddCodePoint(char32_t c)
bool SetComposingRange(const TextRange &range, size_t cursor_offset)
TextRange text_range() const
TextRange composing_range() const
bool SetSelection(const TextRange &range)
bool SetText(const std::string &text, const TextRange &selection=TextRange(0), const TextRange &composing_range=TextRange(0))
void UpdateComposingText(const std::u16string &text, const TextRange &selection)