Add multi-step IME support to TextInputModel (flutter/engine#21682)

* Add multi-step IME support to TextInputModel

This updates the platform-independent TextInputModel to add support for
input method (abbreviated IM or IME) composing regions.

In contrast to languages such as English, where keyboard input is
managed keystroke-by-keystroke, languages such as Japanese require a
multi-step input process wherein the user begins a composing sequence,
during which point their keystrokes are captured by a system input
method and converted into a text sequence. During composing, the user is
able to edit the composing range and manage the conversion from keyboard
input to text before eventually committing the text to the underlying
text input field.

To illustrate this, in Japanese, this sequence might look something like
the following:

1. User types 'k'. The character 'k' is added to the composing region.
   Typically, the text 'k' will be inserted inline into the underlying
   text field but the composing range will be highlighted in some manner,
   frequently with a highlight or underline.
2. User types 'a'. The composing range is replaced with the phonetic
   kana character 'か' (ka). The composing range continues to be
   highlighted.
3. User types 'k'. The character 'k' is appended to the composing
   range such that the highlighted text is now 'かｋ'
4. User types 'u'. The trailing 'k' is replaced with the phonetic kana
   character 'く' (ku) such that the composing range now reads 'かく'
   The composing range continues to be highlighted.
5. The user presses the space bar to convert the kana characters to
   kanji. The composing range is replaced with '書く' (kaku: to write).
6. The user presses the space bar again to show other conversions. The
   user's configured input method (for example, ibus) pops up a
   completions menu populated with alternatives such as 各 (kaku:
   every), 描く (kaku: to draw), 核 (kaku: pit of a fruit, nucleus), 角
   (kaku: angle), etc.
7. The user uses the arrow keys to navigate the completions menu and
   select the alternative to input. As they do, the inline composing
   region in the text field is updated. It continues to be highlighted
   or underlined.
8. The user hits enter to commit the composing region. The text is
   committed to the underlying text field and the visual highlighting is
   removed.
9. If the user presses another key, a new composing sequence begins.

If a selection is present when composing begins, it is preserved until
the first keypress of input is received, at which point the selection is
deleted. If a composing sequence is aborted before the first keypress,
the selection is preserved. Creating a new selection (with the mouse,
for example) aborts composing and the composing region is automatically
committed. A composing range and selection, both with an extent, are
not permitted to co-exist.

During composing, keyboard navigation via the arrow keys, or home and
end (or equivalent shortcuts) is restricted to the composing range, as
are deletions via backspace and the delete key. This patch adds two new
private convenience methods, `editing_range` and `text_range`. The
former returns the range for which editing is currently active -- the
composing range, if composing, otherwise the full range of the text. The
latter, returns a range from position 0 (inclusive) to `text_.length()`
exclusive.

* Move SetComposingLength to TextRange::set_*

Adds set_base, set_extent, set_start, set_end methods to TextRange.

engine/src/flutter/shell/platform/common/cpp/text_input_model.cc

@@ -1,7 +1,6 @@
 // Copyright 2013 The Flutter Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
-// FLUTTER_NOLINT
 
 #include "flutter/shell/platform/common/cpp/text_input_model.h"
 
@@ -39,22 +38,75 @@ void TextInputModel::SetText(const std::string& text) {
       utf16_converter;
   text_ = utf16_converter.from_bytes(text);
   selection_ = TextRange(0);
+  composing_range_ = TextRange(0);
 }
 
 bool TextInputModel::SetSelection(const TextRange& range) {
-  if (!text_range().Contains(range)) {
+  if (composing_ && !range.collapsed()) {
+    return false;
+  }
+  if (!editable_range().Contains(range)) {
     return false;
   }
   selection_ = range;
   return true;
 }
 
+bool TextInputModel::SetComposingRange(const TextRange& range,
+                                       size_t cursor_offset) {
+  if (!composing_ || !text_range().Contains(range)) {
+    return false;
+  }
+  composing_range_ = range;
+  selection_ = TextRange(range.start() + cursor_offset);
+  return true;
+}
+
+void TextInputModel::BeginComposing() {
+  composing_ = true;
+  composing_range_ = TextRange(selection_.start());
+}
+
+void TextInputModel::UpdateComposingText(const std::string& composing_text) {
+  std::wstring_convert<std::codecvt_utf8_utf16<char16_t>, char16_t>
+      utf16_converter;
+  std::u16string text = utf16_converter.from_bytes(composing_text);
+
+  // Preserve selection if we get a no-op update to the composing region.
+  if (text.length() == 0 && composing_range_.collapsed()) {
+    return;
+  }
+  DeleteSelected();
+  text_.replace(composing_range_.start(), composing_range_.length(), text);
+  composing_range_.set_end(composing_range_.start() + text.length());
+  selection_ = TextRange(composing_range_.end());
+}
+
+void TextInputModel::CommitComposing() {
+  // Preserve selection if no composing text was entered.
+  if (composing_range_.collapsed()) {
+    return;
+  }
+  composing_range_ = TextRange(composing_range_.end());
+  selection_ = composing_range_;
+}
+
+void TextInputModel::EndComposing() {
+  composing_ = false;
+  composing_range_ = TextRange(0);
+}
+
 bool TextInputModel::DeleteSelected() {
   if (selection_.collapsed()) {
     return false;
   }
-  text_.erase(selection_.start(), selection_.length());
-  selection_ = TextRange(selection_.start());
+  size_t start = selection_.start();
+  text_.erase(start, selection_.length());
+  selection_ = TextRange(start);
+  if (composing_) {
+    // This occurs only immediately after composing has begun with a selection.
+    composing_range_ = selection_;
+  }
   return true;
 }
 
@@ -74,6 +126,12 @@ void TextInputModel::AddCodePoint(char32_t c) {
 
 void TextInputModel::AddText(const std::u16string& text) {
   DeleteSelected();
+  if (composing_) {
+    // Delete the current composing text, set the cursor to composing start.
+    text_.erase(composing_range_.start(), composing_range_.length());
+    selection_ = TextRange(composing_range_.start());
+    composing_range_.set_end(composing_range_.start() + text.length());
+  }
   size_t position = selection_.position();
   text_.insert(position, text);
   selection_ = TextRange(position + text.length());
@@ -89,12 +147,15 @@ bool TextInputModel::Backspace() {
   if (DeleteSelected()) {
     return true;
   }
-  // If there's no selection, delete the preceding codepoint.
+  // There is no selection. Delete the preceding codepoint.
   size_t position = selection_.position();
-  if (position != 0) {
+  if (position != editable_range().start()) {
     int count = IsTrailingSurrogate(text_.at(position - 1)) ? 2 : 1;
     text_.erase(position - count, count);
     selection_ = TextRange(position - count);
+    if (composing_) {
+      composing_range_.set_end(composing_range_.end() - count);
+    }
     return true;
   }
   return false;
@@ -104,36 +165,40 @@ bool TextInputModel::Delete() {
   if (DeleteSelected()) {
     return true;
   }
-  // If there's no selection, delete the preceding codepoint.
+  // There is no selection. Delete the preceding codepoint.
   size_t position = selection_.position();
-  if (position != text_.length()) {
+  if (position < editable_range().end()) {
     int count = IsLeadingSurrogate(text_.at(position)) ? 2 : 1;
     text_.erase(position, count);
+    if (composing_) {
+      composing_range_.set_end(composing_range_.end() - count);
+    }
     return true;
   }
   return false;
 }
 
 bool TextInputModel::DeleteSurrounding(int offset_from_cursor, int count) {
+  size_t max_pos = editable_range().end();
   size_t start = selection_.extent();
   if (offset_from_cursor < 0) {
     for (int i = 0; i < -offset_from_cursor; i++) {
       // If requested start is before the available text then reduce the
       // number of characters to delete.
-      if (start == 0) {
+      if (start == editable_range().start()) {
         count = i;
         break;
       }
       start -= IsTrailingSurrogate(text_.at(start - 1)) ? 2 : 1;
     }
   } else {
-    for (int i = 0; i < offset_from_cursor && start != text_.length(); i++) {
+    for (int i = 0; i < offset_from_cursor && start != max_pos; i++) {
       start += IsLeadingSurrogate(text_.at(start)) ? 2 : 1;
     }
   }
 
   auto end = start;
-  for (int i = 0; i < count && end != text_.length(); i++) {
+  for (int i = 0; i < count && end != max_pos; i++) {
     end += IsLeadingSurrogate(text_.at(start)) ? 2 : 1;
   }
 
@@ -141,25 +206,33 @@ bool TextInputModel::DeleteSurrounding(int offset_from_cursor, int count) {
     return false;
   }
 
-  text_.erase(start, end - start);
+  auto deleted_length = end - start;
+  text_.erase(start, deleted_length);
 
   // Cursor moves only if deleted area is before it.
   selection_ = TextRange(offset_from_cursor <= 0 ? start : selection_.start());
 
+  // Adjust composing range.
+  if (composing_) {
+    composing_range_.set_end(composing_range_.end() - deleted_length);
+  }
   return true;
 }
 
 bool TextInputModel::MoveCursorToBeginning() {
-  if (selection_.collapsed() && selection_.position() == 0)
+  size_t min_pos = editable_range().start();
+  if (selection_.collapsed() && selection_.position() == min_pos) {
     return false;
-  selection_ = TextRange(0);
+  }
+  selection_ = TextRange(min_pos);
   return true;
 }
 
 bool TextInputModel::MoveCursorToEnd() {
-  size_t max_pos = text_.length();
-  if (selection_.collapsed() && selection_.position() == max_pos)
+  size_t max_pos = editable_range().end();
+  if (selection_.collapsed() && selection_.position() == max_pos) {
     return false;
+  }
   selection_ = TextRange(max_pos);
   return true;
 }
@@ -172,7 +245,7 @@ bool TextInputModel::MoveCursorForward() {
   }
   // Otherwise, move the cursor forward.
   size_t position = selection_.position();
-  if (position != text_.length()) {
+  if (position != editable_range().end()) {
     int count = IsLeadingSurrogate(text_.at(position)) ? 2 : 1;
     selection_ = TextRange(position + count);
     return true;
@@ -188,7 +261,7 @@ bool TextInputModel::MoveCursorBack() {
   }
   // Otherwise, move the cursor backward.
   size_t position = selection_.position();
-  if (position != 0) {
+  if (position != editable_range().start()) {
     int count = IsTrailingSurrogate(text_.at(position - 1)) ? 2 : 1;
     selection_ = TextRange(position - count);
     return true;

engine/src/flutter/shell/platform/common/cpp/text_input_model.h

@@ -28,8 +28,43 @@ class TextInputModel {
   // Attempts to set the text selection.
   //
   // Returns false if the selection is not within the bounds of the text.
+  // While in composing mode, the selection is restricted to the composing
+  // range; otherwise, it is restricted to the length of the text.
   bool SetSelection(const TextRange& range);
 
+  // Attempts to set the composing range.
+  //
+  // Returns false if the range or offset are out of range for the text, or if
+  // the offset is outside the composing range.
+  bool SetComposingRange(const TextRange& range, size_t cursor_offset);
+
+  // Begins IME composing mode.
+  //
+  // Resets the composing base and extent to the selection start. The existing
+  // selection is preserved in case composing is aborted with no changes. Until
+  // |EndComposing| is called, any further changes to selection base and extent
+  // are restricted to the composing range.
+  void BeginComposing();
+
+  // Replaces the composing range with new text.
+  //
+  // If a selection of non-zero length exists, it is deleted if the composing
+  // text is non-empty. The composing range is adjusted to the length of
+  // |composing_text| and the selection base and offset are set to the end of
+  // the composing range.
+  void UpdateComposingText(const std::string& composing_text);
+
+  // Commits composing range to the string.
+  //
+  // Causes the composing base and extent to be collapsed to the end of the
+  // range.
+  void CommitComposing();
+
+  // Ends IME composing mode.
+  //
+  // Collapses the composing base and offset to 0.
+  void EndComposing();
+
   // Adds a Unicode code point.
   //
   // Either appends after the cursor (when selection base and extent are the
@@ -52,18 +87,21 @@ class TextInputModel {
   // Deletes either the selection, or one character ahead of the cursor.
   //
   // Deleting one character ahead of the cursor occurs when the selection base
-  // and extent are the same.
+  // and extent are the same. When composing is active, deletions are
+  // restricted to text between the composing base and extent.
   //
   // Returns true if any deletion actually occurred.
   bool Delete();
 
   // Deletes text near the cursor.
   //
-  // A section is made starting at @offset code points past the cursor (negative
-  // values go before the cursor). @count code points are removed. The selection
-  // may go outside the bounds of the text and will result in only the part
-  // selection that covers the available text being deleted. The existing
-  // selection is ignored and removed after this operation.
+  // A section is made starting at |offset_from_cursor| code points past the
+  // cursor (negative values go before the cursor). |count| code points are
+  // removed. The selection may go outside the bounds of the available text and
+  // will result in only the part selection that covers the available text
+  // being deleted. The existing selection is ignored and removed after this
+  // operation. When composing is active, deletions are restricted to the
+  // composing range.
   //
   // Returns true if any deletion actually occurred.
   bool DeleteSurrounding(int offset_from_cursor, int count);
@@ -71,7 +109,8 @@ class TextInputModel {
   // Deletes either the selection, or one character behind the cursor.
   //
   // Deleting one character behind the cursor occurs when the selection base
-  // and extent are the same.
+  // and extent are the same. When composing is active, deletions are
+  // restricted to the text between the composing base and extent.
   //
   // Returns true if any deletion actually occurred.
   bool Backspace();
@@ -79,21 +118,31 @@ class TextInputModel {
   // Attempts to move the cursor backward.
   //
   // Returns true if the cursor could be moved. If a selection is active, moves
-  // to the start of the selection.
+  // to the start of the selection. If composing is active, motion is
+  // restricted to the composing range.
   bool MoveCursorBack();
 
   // Attempts to move the cursor forward.
   //
   // Returns true if the cursor could be moved. If a selection is active, moves
-  // to the end of the selection.
+  // to the end of the selection. If composing is active, motion is restricted
+  // to the composing range.
   bool MoveCursorForward();
 
   // Attempts to move the cursor to the beginning.
   //
+  // If composing is active, the cursor is moved to the beginning of the
+  // composing range; otherwise, it is moved to the beginning of the text. If
+  // composing is active, motion is restricted to the composing range.
+  //
   // Returns true if the cursor could be moved.
   bool MoveCursorToBeginning();
 
-  // Attempts to move the cursor to the back.
+  // Attempts to move the cursor to the end.
+  //
+  // If composing is active, the cursor is moved to the end of the composing
+  // range; otherwise, it is moved to the end of the text. If composing is
+  // active, motion is restricted to the composing range.
   //
   // Returns true if the cursor could be moved.
   bool MoveCursorToEnd();
@@ -108,6 +157,14 @@ class TextInputModel {
   // The current selection.
   TextRange selection() const { return selection_; }
 
+  // The composing range.
+  //
+  // If not in composing mode, returns a collapsed range at position 0.
+  TextRange composing_range() const { return composing_range_; }
+
+  // Whether multi-step input composing mode is active.
+  bool composing() const { return composing_; }
+
  private:
   // Deletes the current selection, if any.
   //
@@ -115,11 +172,21 @@ class TextInputModel {
   // reset to the start of the selected range.
   bool DeleteSelected();
 
+  // Returns the currently editable text range.
+  //
+  // In composing mode, returns the composing range; otherwise, returns a range
+  // covering the entire text.
+  TextRange editable_range() const {
+    return composing_ ? composing_range_ : text_range();
+  }
+
   // Returns a range covering the entire text.
   TextRange text_range() const { return TextRange(0, text_.length()); }
 
   std::u16string text_;
   TextRange selection_ = TextRange(0);
+  TextRange composing_range_ = TextRange(0);
+  bool composing_ = false;
 };
 
 }  // namespace flutter

engine/src/flutter/shell/platform/common/cpp/text_range.h

@@ -21,19 +21,43 @@ class TextRange {
 
   virtual ~TextRange() = default;
 
-  // Returns the base position of the range.
+  // The base position of the range.
   size_t base() const { return base_; }
 
-  // Returns the extent position of the range.
+  // Sets the base position of the range.
+  void set_base(size_t pos) { base_ = pos; }
+
+  // The extent position of the range.
   size_t extent() const { return extent_; }
 
-  // Returns the lesser of the base and extent positions.
+  // Sets the extent position of the range.
+  void set_extent(size_t pos) { extent_ = pos; }
+
+  // The lesser of the base and extent positions.
   size_t start() const { return std::min(base_, extent_); }
 
-  // Returns the greater of the base and extent positions.
+  // Sets the start position of the range.
+  void set_start(size_t pos) {
+    if (base_ <= extent_) {
+      base_ = pos;
+    } else {
+      extent_ = pos;
+    }
+  }
+
+  // The greater of the base and extent positions.
   size_t end() const { return std::max(base_, extent_); }
 
-  // Returns the position of a collapsed range.
+  // Sets the end position of the range.
+  void set_end(size_t pos) {
+    if (base_ <= extent_) {
+      extent_ = pos;
+    } else {
+      base_ = pos;
+    }
+  }
+
+  // The position of a collapsed range.
   //
   // Asserts that the range is of length 0.
   size_t position() const {
@@ -41,7 +65,7 @@ class TextRange {
     return extent_;
   }
 
-  // Returns the length of the range.
+  // The length of the range.
   size_t length() const { return end() - start(); }
 
   // Returns true if the range is of length 0.

engine/src/flutter/shell/platform/common/cpp/text_range_unittests.cc

@@ -50,6 +50,62 @@ TEST(TextRange, TextRangeFromReversedRange) {
   EXPECT_FALSE(range.collapsed());
 }
 
+TEST(TextRange, SetBase) {
+  TextRange range(3, 7);
+  range.set_base(4);
+  EXPECT_EQ(range.base(), size_t(4));
+  EXPECT_EQ(range.extent(), size_t(7));
+}
+
+TEST(TextRange, SetBaseReversed) {
+  TextRange range(7, 3);
+  range.set_base(5);
+  EXPECT_EQ(range.base(), size_t(5));
+  EXPECT_EQ(range.extent(), size_t(3));
+}
+
+TEST(TextRange, SetExtent) {
+  TextRange range(3, 7);
+  range.set_extent(6);
+  EXPECT_EQ(range.base(), size_t(3));
+  EXPECT_EQ(range.extent(), size_t(6));
+}
+
+TEST(TextRange, SetExtentReversed) {
+  TextRange range(7, 3);
+  range.set_extent(4);
+  EXPECT_EQ(range.base(), size_t(7));
+  EXPECT_EQ(range.extent(), size_t(4));
+}
+
+TEST(TextRange, SetStart) {
+  TextRange range(3, 7);
+  range.set_start(5);
+  EXPECT_EQ(range.base(), size_t(5));
+  EXPECT_EQ(range.extent(), size_t(7));
+}
+
+TEST(TextRange, SetStartReversed) {
+  TextRange range(7, 3);
+  range.set_start(5);
+  EXPECT_EQ(range.base(), size_t(7));
+  EXPECT_EQ(range.extent(), size_t(5));
+}
+
+TEST(TextRange, SetEnd) {
+  TextRange range(3, 7);
+  range.set_end(6);
+  EXPECT_EQ(range.base(), size_t(3));
+  EXPECT_EQ(range.extent(), size_t(6));
+}
+
+TEST(TextRange, SetEndReversed) {
+  TextRange range(7, 3);
+  range.set_end(5);
+  EXPECT_EQ(range.base(), size_t(5));
+  EXPECT_EQ(range.extent(), size_t(3));
+}
+
 TEST(TextRange, ContainsPreStartPosition) {
   TextRange range(2, 6);
   EXPECT_FALSE(range.Contains(1));