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