RenderText API Outline.

ui/gfx/render_text.h

Index: ui/gfx/render_text.h
diff --git a/ui/gfx/render_text.h b/ui/gfx/render_text.h
new file mode 100755
index 0000000000000000000000000000000000000000..4bcbc8abef67ef806366a0895d54128ef93ed1a5
--- /dev/null
+++ b/ui/gfx/render_text.h
@@ -0,0 +1,170 @@
+// 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/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 {
+
+struct StyleRange {
+  Font font;
+  SkColor foreground;
+  bool strike;
+  bool underline;
+  ui::Range range;

[xji, 2011/07/01 18:29:44]

also
SkColor background;
for selection background

[msw, 2011/07/01 21:52:15]

Interesting, we can add a background color if we want to allow stylized
backgrounds, but we shouldn't apply StyleRanges to render the selection. That
would essentially append a new StyleRange for each selection modification and
bloat the model.

+};
+
+typedef std::vector<StyleRange*> StyleRanges;
+
+// 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();
+  static RenderText* CreateRenderText(const string16& text,
+                                      const gfx::Font& font,
+                                      const SkColor& color,
+                                      const gfx::Rect& display_rect,
+                                      int flags);
+
+  const string16& text() const { return text_; }
+  virtual void SetText(const string16& text);
+
+  int get_flags() const { return flags_; }
+  void set_flags(int flags) { flags_ = flags; }
+
+  const gfx::Rect& get_display_rect() const { return display_rect_; }
+
+  size_t GetCursor() const;
+  void SetCursor(const size_t position);
+
+  // TODO(msw): The current composition text will be confirmed???
+
+  // 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.
+  // The current composition text will be confirmed.
+  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.
+  // The current composition text will be confirmed.
+  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.
+  // The current composition text will be confirmed.
+  void MoveCursorTo(size_t position, bool select);
+
+  const ui::Range& GetSelection() const;
+  void SetSelection(const ui::Range& selection_range);
+
+  // Selects no text, all text, or the word at the current cursor position.
+  // The current composition text will be confirmed.
+  void ClearSelection();
+  void SelectAll();
+  void SelectWord();
+
+  const ui::Range& GetComposition() const;
+  void SetComposition(const ui::Range& composition_range);
+
+  const StyleRanges& GetStyleRanges() const;
+  // Takes ownership of |style_range| and updates the internal style model.
+  void ApplyStyleRange(StyleRange* style_range);
+
+  virtual void Draw(gfx::NativeDrawingContext drawing_context) const = 0;
+
+  // Get the logical cursor position from a visual point in local coordinates.
+  virtual size_t FindCursorPosition(const gfx::Point& point) const = 0;
+
+  // 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 = 0;
+
+  // 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 = 0;
+  virtual size_t GetRightCursorPosition(size_t position,
+                                        bool move_by_word) const = 0;

[xji, 2011/07/01 18:29:44]

if we have "MoveCursorLeft() and MoveCursorRight()" as public, maybe we should
make those "GetLeftCursorPosition() and GetRightCursorPosition" as private.

[msw, 2011/07/01 21:52:15]

I agree. I'm just now integrating this new API into NativeTextfieldViews, I'll
make these private if they aren't required.

+
+  // 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 = 0;
+
+ protected:
+  RenderText();
+  RenderText(const string16& text,
+             const gfx::Font& font,
+             const SkColor& color,
+             const gfx::Rect& display_rect,
+             int flags);
+
+ private:
+  // TODO(msw): Revise SelectWord to eliminate this?
+  bool IsPositionAtWordSelectionBoundary(size_t pos);
+
+  // Logical UTF-16 string data to be drawn.
+  string16 text_;

[xji, 2011/07/01 18:29:44]

are we going to remove those duplicated fields from NativeTextfieldViews or
TextfieldViewsModel if RenderText is a member of one of them?

[msw, 2011/07/01 21:52:15]

I'm not sure; currently the TextfieldViewsModel operates on its text_ member,
and NativeTextfieldViews has a Textfield member with its own text_, and I was
planning to make RenderText a member of NativeTextfieldViews, but it's looking
more likely to be a member of TextfieldViewsModel now, which should eliminate
the need for TextfieldViewsModel::text_. I'm open to suggestions.

+
+  // Logical selection range; the range end is also the logical cursor position.
+  ui::Range selection_range_;
+
+  // The cursor visibility.
+  bool is_cursor_visible_;
+
+  // Composition text range.
+  ui::Range composition_range_;
+
+  // List of style ranges. Elements in the list never overlap each other.
+  StyleRanges style_ranges_;
+
+  // The local display area for rendering the text.
+  gfx::Rect display_rect_;
+  // The x offset for the text to be drawn, without insets.
+  gfx::Point render_offset_;

[xji, 2011/07/01 18:29:44]

what is the usage of this field?

[msw, 2011/07/01 21:52:15]

This is for offsetting the origin of the text as rendered within the textfield,
as NativeTextfieldViews::text_offset_ does for the x dimension. This allows
panning over text that is wider (and possibly taller for multi-line?) than the
textfield can display. I may just go back to a single int, since we don't plan
to offer multi-line text immediately.

+
+  gfx::Font default_font_;
+  SkColor default_color_;
+
+  // TODO(msw): Needed?
+  // The visual cursor bounds. These bounds typically represent a vertical line,
+  // but in insert mode they contain the bounds of the associated glyph.
+  //gfx::Rect cursor_bounds_;
+  // The visual selection bounds. These bounds could be visually discontiguous
+  // if the logical selection range is split by a single LTR/RTL level change.
+  //std::vector<gfx::Rect> selection_bounds_;
+
+  // Rendering flags, defined in Canvas.
+  int flags_;
+

[xji, 2011/07/01 18:29:44]

I do not have clear idea on what (how much) stuff we want to put in RenderText,
and what (how much) stuff we want to put in TextfieldViewsModel and/or
NativeTextfieldViews? Are we making RenderText thin enough and pass information
from TextfieldViewsModel to it if needed? Or we are making it heavy enough to do
most of TextfieldViewsModel's work?

[msw, 2011/07/01 21:52:15]

Unfortunately I haven't solved that dilemma. I thought NativeTextfieldViews
should use TextfieldViewsModel for editing/history/composition and use
RenderText for cursor/selection/coordinates/drawing. But these operations are so
intertwined that a slimmer RenderText may have to live in TextfieldViewsModel
with some redundant pass-through API. I'm not very pleased with either approach,
but leaning towards the second one now; feedback is appreciated,

+  DISALLOW_COPY_AND_ASSIGN(RenderText);
+};
+
+}  // namespace gfx;
+
+#endif  // UI_GFX_RENDER_TEXT_H_