RenderText API Outline.

ui/gfx/render_text.h

+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef UI_GFX_RENDER_TEXT_H_
+#define UI_GFX_RENDER_TEXT_H_
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "base/gtest_prod_util.h"
+#include "base/i18n/rtl.h"
+#include "base/string16.h"
+#include "third_party/skia/include/core/SkColor.h"
+#include "ui/base/range/range.h"
+#include "ui/gfx/font.h"
+#include "ui/gfx/rect.h"
+#include "ui/gfx/point.h"
+
+namespace gfx {
+
+class Canvas;
+class RenderTextTest;
+
+struct StyleRange {
+  StyleRange()
+      : font(),
+        foreground(SK_ColorBLACK),
+        strike(false),
+        underline(false),
+        range() {
+  }
+

[oshima, 2011/07/23 09:51:12]

move constructor to .cc as this has non trivial objects.

+  Font font;
+  SkColor foreground;
+  bool strike;
+  bool underline;
+  ui::Range range;
+};
+
+typedef std::vector<StyleRange> StyleRanges;
+
+// TODO(msw): Implement RenderText[Win|Linux] for Uniscribe/Pango BiDi...
+
+// RenderText represents an abstract model of styled text and its corresponding
+// visual layout. Support is built in for a cursor, a selection, simple styling,
+// complex scripts, and bi-directional text. Implementations provide mechanisms
+// for rendering and translation between logical and visual data.
+class RenderText {
+ public:
+  virtual ~RenderText();
+
+  // Creates a platform-specific RenderText instance.
+  static RenderText* CreateRenderText();
+
+  const string16& text() const { return text_; }
+  virtual void SetText(const string16& text);
+
+  void set_cursor_visible(bool visible) { is_cursor_visible_ = visible; }
+
+  bool get_insert_mode() const { return insert_mode_; }
+  void toggle_insert_mode() { insert_mode_ = !insert_mode_; }
+
+  void set_focused(bool focused) { is_focused_ = focused; }
+
+  const StyleRange& get_default_style() { return default_style_; }
+  void set_default_style(StyleRange style) { default_style_ = style; }
+
+  const gfx::Rect& get_display_rect() const { return display_rect_; }
+  void set_display_rect(const gfx::Rect& r) { display_rect_ = r; }
+
+  size_t GetCursor() const;
+  void SetCursor(const size_t position);
+
+  // Moves the cursor left or right. Cursor movement is visual, meaning that
+  // left and right are relative to screen, not the directionality of the text.
+  // If |select| is false, the selection range is emptied at the new position.
+  // If |move_by_word| is true, the cursor moves to the nearest word boundary.
+  void MoveCursorLeft(bool select, bool move_by_word);
+  void MoveCursorRight(bool select, bool move_by_word);
+
+  // Moves the cursor to left or right end of the text as shown on screen.
+  // If |select| is false, the selection range is emptied at the new position.
+  void MoveCursorToLeftEnd(bool select);
+  void MoveCursorToRightEnd(bool select);
+
+  // Moves the cursor to the specified logical |position|.
+  // If |select| is false, the selection range is emptied at the new position.
+  // Returns true if the cursor position or selection range changed.
+  bool MoveCursorTo(size_t position, bool select);
+
+  const ui::Range& GetSelection() const;
+  void SetSelection(const ui::Range& range);
+
+  // Selects no text, all text, or the word at the current cursor position.
+  void ClearSelection();
+  void SelectAll();
+  void SelectWord();
+
+  const ui::Range& GetCompositionRange() const;
+  void SetCompositionRange(const ui::Range& composition_range);
+
+  // Apply |style_range| to the internal style model.
+  void ApplyStyleRange(StyleRange style_range);
+  // Apply |default_style_| over the entire text range.
+  void ApplyDefaultStyle();
+
+  base::i18n::TextDirection GetTextDirection() const;
+
+  // Get the width of the entire string.
+  int GetStringWidth() const;
+
+  virtual void Draw(gfx::Canvas* canvas) const;
+
+  // Get the logical cursor position from a visual point in local coordinates.
+  virtual size_t FindCursorPosition(const gfx::Point& point) const;
+
+  // Get the visual bounds containing the logical substring within |range|.
+  // These bounds could be visually discontiguous if the logical selection range
+  // is split by a single LTR/RTL level change.
+  virtual std::vector<gfx::Rect> GetSubstringBounds(
+      const ui::Range& range) const;
+
+  // Get the visual bounds describing the cursor at |position|. These bounds
+  // typically represent a vertical line, but if |insert_mode| is true they
+  // contain the bounds of the associated glyph.
+  virtual gfx::Rect GetCursorBounds(size_t position, bool insert_mode) const;
+
+ protected:
+  RenderText();
+
+  // Get the cursor position that visually neighbors |position|.
+  // If |move_by_word| is true, return the neighboring word delimiter position.
+  virtual size_t GetLeftCursorPosition(size_t position,
+                                       bool move_by_word) const;
+  virtual size_t GetRightCursorPosition(size_t position,
+                                        bool move_by_word) const;
+
+ private:
+  friend class RenderTextTest;
+
+  FRIEND_TEST_ALL_PREFIXES(RenderTextTest, DefaultStyle);
+  FRIEND_TEST_ALL_PREFIXES(RenderTextTest, CustomDefaultStyle);
+  FRIEND_TEST_ALL_PREFIXES(RenderTextTest, ApplyStyleRange);
+  FRIEND_TEST_ALL_PREFIXES(RenderTextTest, StyleRangesAdjust);
+
+  const StyleRanges& get_style_ranges() const { return style_ranges_; }
+
+  // Clear out |style_ranges_|.
+  void ClearStyleRanges();
+
+  bool IsPositionAtWordSelectionBoundary(size_t pos);
+
+  // Logical UTF-16 string data to be drawn.
+  string16 text_;
+
+  // Logical selection range; the range end is also the logical cursor position.
+  ui::Range selection_range_;

[xji, 2011/07/20 01:33:33]

I think we will need the leading or trailing information besides the logical
index.

For example, given a logical text "abcDEF" where capital letter stands for
Hebrew, the visual display is "abcFED".

According to the bidi editing guide:
1. If pointing to the right half of the cell of a LTR character, the current
position must be set after this character and the caret must be displayed after
this character.
2. If pointing to the right half of the cell of a RTL character, the current
position must be set before this character and the caret must be displayed
before this character.

So, pointing to the right half of 'c' and pointing to the right half of 'D' all
set cursor position as 3.
But the cursor displayed visually at different places:
pointing right half of 'c' displays cursor right of 'c',
pointing right half of 'D' displays cursor right of 'D'.

In chrome's flow. When pointing using mouse, FindCursorPosition() is called, and
it returns the logical position (as 3). Later, GetCursorBounds() will be called
to draw the cursor at logical position 3. For the above 2 cases, although the
logical position are both 3, but the cursor should be dawn in different places.
A single cursor position wont be able to achieve this. Instead, we will need the
trailing or leading information.

For example, pointing to right of 'c' put current cursor at trailing position of
character at index of 2. pointing to right of 'D' put current cursor at leading
position of character of index 3. (note: for a LTR character, right edge is the
trailing edge, for a RTL character, right edge is the  leading edge).

A subsequent question that I am not sure about is that:
selection_range_'s end is where the next character will be inserted.

If we save the current cursor position as (cursor_position, trailing/leading)
pair, the cursor_position means the current cursor  position, which is different
from the cursor position where next character will be inserted.
For the above example, when pointing to right of 'c', the cursor position (where
next character will be inserted) is 3. But we need to save (2, trailing) to draw
the cursor at right visual place. Then, do we need to save the cursor position
(where next character will be inserted) plus the (current cursor position,
trailing/leading)? We could generate the cursor position (where next character
will be inserted) from (current cursor position, trailing/leading) pair, but the
position wont be just increased by 1 for complex script. For example, "abcd" in
a complex script, characters a, b, and c are rendered as one grapheme, pointing
to trailing of this grapheme, the pointed to cursor position is  0, but the
logical cursor position (where the next character will be inserted) is 3.

[msw, 2011/07/20 09:22:46]

You're right, this model doesn't currently support two potential visual cursor
positions for the same logical index (visually 'abc|FEDghi' and 'abcFED|ghi',
both logically at [3] 'abc|DEFghi'). I think it's bad behavior*. However, we
could implement it by adding a member: either (cursor_position,
leading/trailing) as you suggest, or a visual_cursor_index_ disjoint from the
logical cursor (selection_range_.end()), and adding a function
RenderText::MoveCursorTo(const gfx::Point& point, bool select). Perhaps I'll
just add a note for now, and we can address it later.

*How are we supposed to render the non insert-mode cursor (which surrounds the
glyph) in these cases? Do both display as 'abcFE[D]ghi', even if you click the
right side of 'c'? Also, this behavior makes visual cursors at level changes
ambiguous ('abcFED|ghi' could be from clicking the right of 'c' or the left of
'g'), perhaps we want to show directionality?

[xji, 2011/07/20 18:39:51]

in bidi text, the mapping between logical and visual is not one-to-one.
Webkit implemented it as one-to-one mapping, and that caused quite a few
problems, such as you are not able to point the cursor between Arabic number and
Arabic letter when embedding levels are high (because there is no position
points there), the cursor is at the rightmost position when you type Hebrew in
LTR context (findInPage in Linux chrome does the same, but omnibox does it
correctly), extending selection by mouse dragging from the rightmost Hebrew
character in LTR context is not working (the rightmost character is not
selected).

If we support split caret like Pango does (but the consensus from native
speakers is NO), one logical position might rendered with 2 different visual
carets. Otherwise, we need to have a flag to indicate where we want the single
caret to be drawn.
That should be fine to address it later.
I did not quite get the idea of render cursor in non-insert-mode.
Does it render cursor as a selection of (cursor_position, cursor_position + 1)?
]
If the cursor is rendered as a selection of (3, 4), yes, [D] should be displayed
even if you click the right side of 'c'.
It is similar as if you type in a Hebrew character X (no matter after you right
click 'c' or right click 'D'), X will always be rendered at right of 'D' because
the logical position is 3 before insert 'X'. But although the logical position
is 3, the visual display of cursor is different if click right of 'c' and right
of 'D'.
Visual cursor is also mapped to multiple logical positions.
"abcFEDghi", click right of 'D' put logical position as 3, click left of 'g' put
logical position as 6. But the cursor display between 'D' and 'g' for both.

That is confusion, and it is one of the discussions in bidi editing standard. We
will need an indicator to indicate the logical position. But I do not think I
will implement that in my 1st version.

[xji, 2011/07/20 19:59:36]

I'am resending/republishing my comments since it was mailed correctly but not
published last time.....

in bidi text, the mapping between logical and visual is not one-to-one.
Webkit implemented it as one-to-one mapping, and that caused quite a few
problems, such as you are not able to point the cursor between Arabic number and
Arabic letter when embedding levels are high (because there is no position
points there), the cursor is at the rightmost position when you type Hebrew in
LTR context (findInPage in Linux chrome does the same, but omnibox does it
correctly), extending selection by mouse dragging from the rightmost Hebrew
character in LTR context is not working (the rightmost character is not
selected).

If we support split caret like Pango does (but the consensus from native
speakers is NO), one logical position might rendered with 2 different visual
carets. Otherwise, we need to have a flag to indicate where we want the single
caret to be drawn.

That should be fine to address it later.
I did not quite get the idea of render cursor in non-insert-mode.
Does it render cursor as a selection of (cursor_position, cursor_position + 1)?


If the cursor is rendered as a selection of (3, 4), yes, [D] should be displayed
even if you click the right side of 'c'.
It is similar as if you type in a Hebrew character X (no matter after you right
click 'c' or right click 'D'), X will always be rendered at right of 'D' because
the logical position is 3 before insert 'X'. But although the logical position
is 3, the visual display of cursor is different if click right of 'c' and right
of 'D'.


Visual cursor is also mapped to multiple logical positions.
"abcFEDghi", click right of 'D' put logical position as 3, click left of 'g' put
logical position as 6. But the cursor display between 'D' and 'g' for both.

That is confusion, and it is one of the discussions in bidi editing standard. We
will need an indicator to indicate the logical position. But I do not think I
will implement that in my 1st version.

[msw, 2011/07/21 00:19:55]

Yes, the non insert-mode cursor is essentially a movable selection.
I've added a pair of TODO notes with explanations for now.

+
+  // The cursor visibility and insert mode.
+  bool is_cursor_visible_;
+  bool insert_mode_;
+
+  // The focus state of the text.
+  bool is_focused_;
+
+  // Composition text range.
+  ui::Range composition_range_;
+
+  // List of style ranges. Elements in the list never overlap each other.
+  StyleRanges style_ranges_;
+  // The default text style.
+  StyleRange default_style_;
+
+  // The local display area for rendering the text.
+  gfx::Rect display_rect_;
+  // The offset for the text to be drawn, relative to the display area.
+  gfx::Point display_offset_;
+
+  DISALLOW_COPY_AND_ASSIGN(RenderText);
+};
+
+}  // namespace gfx
+
+#endif  // UI_GFX_RENDER_TEXT_H_