AuroraMiddleware/skia2
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

update dox for vertical-text demise

Browse Source 
Bug: skia:
Change-Id: I0c8887fc31ea491a155ce9f182bbd5235f403120
Reviewed-on: https://skia-review.googlesource.com/c/164607
Commit-Queue: Mike Reed <reed@google.com>
Commit-Queue: Cary Clark <caryclark@google.com>
Reviewed-by: Cary Clark <caryclark@google.com>
Auto-Submit: Mike Reed <reed@google.com>
This commit is contained in:
Mike Reed 2018-10-23 13:57:46 -04:00 committed by Skia Commit-Bot
parent 6a300ac5b7
commit 07055a3ee7
2 changed files with 22 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/SkCanvas_Reference.bmh
View File

@ -203,35 +203,25 @@ Passes a placeholder to a function that requires one.
##
#Function
// Returns true if either the canvas rotates the text by 90 degrees, or the paint does.
static void check_for_up_and_down_text(const SkCanvas* canvas, const SkPaint& paint) {
bool paintHasVertical = paint.isVerticalText();
static void check_for_rotated_ctm(const SkCanvas* canvas) {
const SkMatrix& matrix = canvas->getTotalMatrix();
bool matrixIsVertical = matrix.preservesRightAngles() && !matrix.isScaleTranslate();
SkDebugf("paint draws text %s\n", paintHasVertical != matrixIsVertical ?
"top to bottom" : "left to right");
}
static void check_for_up_and_down_text(const SkPaint& paint) {
SkCanvas canvas; // placeholder only, does not have an associated device
check_for_up_and_down_text(&canvas, paint);
SkDebugf("rect stays rect is %s\n", matrix.rectStaysRect() ? "true" : "false");
}
##
void draw(SkCanvas* canvas) {
SkPaint paint;
check_for_up_and_down_text(paint); // paint draws text left to right
paint.setVerticalText(true);
check_for_up_and_down_text(paint); // paint draws text top to bottom
paint.setVerticalText(false);
canvas->rotate(90);
check_for_up_and_down_text(canvas, paint); // paint draws text top to bottom
check_for_rotated_ctm(canvas);
canvas->rotate(30);
check_for_rotated_ctm(canvas);
SkCanvas defaultCanvas;
check_for_rotated_ctm(&defaultCanvas);
}
#StdOut
paint draws text left to right
paint draws text top to bottom
paint draws text top to bottom
rect stays rect is true
rect stays rect is false
rect stays rect is true
##
##
@ -5073,7 +5063,7 @@ Draws text, with origin at (x, y), using Clip, Matrix, and Paint paint.
text meaning depends on Paint_Text_Encoding; by default, text is encoded as
UTF-8.
x and y meaning depends on Paint_Text_Align and Paint_Vertical_Text; by default
x and y meaning depends on Paint_Text_Align; by default
text draws left to right, positioning the first glyph left side bearing at x
and its baseline at y. Text size is affected by Matrix and Paint_Text_Size.
@ -5131,8 +5121,7 @@ string meaning depends on Paint_Text_Encoding; by default, strings are encoded
as UTF-8. Other values of Paint_Text_Encoding are unlikely to produce the desired
results, since zero bytes may be embedded in the string.
x and y meaning depends on Paint_Text_Align and Paint_Vertical_Text; by default
string draws left to right, positioning the first glyph left side bearing at x
The string draws left to right, positioning the first glyph left side bearing at x
and its baseline at y. Text size is affected by Matrix and Paint_Text_Size.
All elements of paint: Path_Effect, Mask_Filter, Shader,
@ -5165,8 +5154,7 @@ string meaning depends on Paint_Text_Encoding; by default, strings are encoded
as UTF-8. Other values of Paint_Text_Encoding are unlikely to produce the desired
results, since zero bytes may be embedded in the string.
x and y meaning depends on Paint_Text_Align and Paint_Vertical_Text; by default
string draws left to right, positioning the first glyph left side bearing at x
The string draws left to right, positioning the first glyph left side bearing at x
and its baseline at y. Text size is affected by Matrix and Paint_Text_Size.
All elements of paint: Path_Effect, Mask_Filter, Shader,
@ -5203,8 +5191,7 @@ Paint paint. The number of entries in pos array must match the number of Glyphs
described by byteLength of text.
text meaning depends on Paint_Text_Encoding; by default, text is encoded as
UTF-8. pos elements meaning depends on Paint_Vertical_Text; by default
glyph left side bearing and baseline are relative to Point in pos array.
UTF-8. glyph left side bearing and baseline are relative to Point in pos array.
Text size is affected by Matrix and Paint_Text_Size.
All elements of paint: Path_Effect, Mask_Filter, Shader,
@ -5248,8 +5235,7 @@ constY, using Clip, Matrix, and Paint paint. The number of entries in xpos array
must match the number of Glyphs described by byteLength of text.
text meaning depends on Paint_Text_Encoding; by default, text is encoded as
UTF-8. xpos elements meaning depends on Paint_Vertical_Text;
by default each glyph left side bearing is positioned at an xpos element and
UTF-8. Each glyph left side bearing is positioned at an xpos element and
its baseline is positioned at constY. Text size is affected by Matrix and
Paint_Text_Size.

133
docs/SkPaint_Reference.bmh
View File

@ -79,7 +79,6 @@ Constructs Paint with default values.
# Stroke_Join # kMiter_Join ##
# Stroke_Width # 0 ##
# Subpixel_Text # false ##
# Vertical_Text # false ##
#Table ##
The flags, text size, hinting, and miter limit may be overridden at compile time by defining
@ -514,9 +513,6 @@ multiple settings at once.
#Const kAutoHinting_Flag 0x0800
#Line # mask for setting Automatic_Hinting ##
##
#Const kVerticalText_Flag 0x1000
#Line # mask for setting Vertical_Text ##
##
#Const kAllFlags 0xFFFF
#Line # mask of all Flags ##
mask of all Flags, including private flags and flags reserved for future use
@ -1256,96 +1252,6 @@ Automatic_Hinting only affects platforms that use FreeType as the Font_Manager.
##
# ------------------------------------------------------------------------------
#Subtopic Vertical_Text
#Line # orient text from top to bottom ##
Text may be drawn by positioning each glyph, or by positioning the first glyph and
using Font_Advance to position subsequent Glyphs. By default, each successive glyph
is positioned to the right of the preceding glyph. Vertical_Text sets successive
Glyphs to position below the preceding glyph.
Skia can translate text character codes as a series of Glyphs, but does not implement
font substitution,
textual substitution, line layout, or contextual spacing like Kerning pairs. Use
a text shaping engine like
#A HarfBuzz # https://harfbuzz.org/ ##
to translate text runs
into glyph series.
Vertical_Text is clear if text is drawn left to right or set if drawn from top to bottom.
Flags kVerticalText_Flag if clear draws text left to right.
Flags kVerticalText_Flag if set draws text top to bottom.
Vertical_Text is clear by default.
Vertical_Text can be set by default by setting SkPaintDefaults_Flags to
kVerticalText_Flag at compile time.
#Example
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setAntiAlias(true);
paint.setTextSize(50);
for (bool vertical : { false, true } ) {
paint.setVerticalText(vertical);
canvas->drawString("aAlL", 25, 50, paint);
}
}
##
#Subtopic Vertical_Text ##
#Method bool isVerticalText() const
#In Vertical_Text
#Line # returns true if Vertical_Text is set ##
Returns true if Glyphs are drawn top to bottom instead of left to right.
Equivalent to getFlags masked with kVerticalText_Flag.
#Return kVerticalText_Flag state ##
#Example
SkPaint paint;
SkDebugf("paint.isVerticalText() %c= !!(paint.getFlags() & SkPaint::kVerticalText_Flag)\n",
paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag) ? '=' : '!');
paint.setVerticalText(true);
SkDebugf("paint.isVerticalText() %c= !!(paint.getFlags() & SkPaint::kVerticalText_Flag)\n",
paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag) ? '=' : '!');
#StdOut
paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag)
paint.isVerticalText() == !!(paint.getFlags() & SkPaint::kVerticalText_Flag)
##
##
##
#Method void setVerticalText(bool verticalText)
#In Vertical_Text
#Line # sets or clears Vertical_Text ##
Returns true if text advance positions the next glyph below the previous glyph instead of to the
right of previous glyph.
Sets kVerticalText_Flag if vertical is true.
Clears kVerticalText_Flag if vertical is false.
#Param verticalText setting for kVerticalText_Flag ##
#Example
SkPaint paint1, paint2;
paint1.setVerticalText(true);
paint2.setFlags(paint2.getFlags() | SkPaint::kVerticalText_Flag);
SkDebugf("paint1 %c= paint2\n", paint1 == paint2 ? '=' : '!');
#StdOut
paint1 == paint2
##
##
##
# ------------------------------------------------------------------------------
#Subtopic Fake_Bold
@ -3435,14 +3341,12 @@ Align defaults to kLeft_Align.
#Const kCenter_Align 1
#Line # centers line of glyphs by its width or height ##
Moves the glyph half its width if Flags has kVerticalText_Flag clear, and
half its height if Flags has kVerticalText_Flag set.
Moves the glyph half its width.
##
#Const kRight_Align 2
#Line # moves lines of glyphs by its width or height ##
Moves the glyph by its width if Flags has kVerticalText_Flag clear,
and by its height if Flags has kVerticalText_Flag set.
Moves the glyph by its width.
##
#Const kAlignCount 3
@ -3471,25 +3375,6 @@ May be used to verify that Align is a legal value.
}
##
#Example
#Height 160
#Description
Vertical_Text treats kLeft_Align as top align, and kRight_Align as bottom align.
##
void draw(SkCanvas* canvas) {
SkPaint paint;
paint.setTextSize(40);
paint.setVerticalText(true);
for (SkPaint::Align a : { SkPaint::kLeft_Align,
SkPaint::kCenter_Align,
SkPaint::kRight_Align }) {
paint.setTextAlign(a);
canvas->drawString("Aa", 50, 80, paint);
canvas->translate(50, 0);
}
}
##
#Method Align getTextAlign() const
#In Text_Align
@ -4388,8 +4273,7 @@ text contains an invalid UTF-8 sequence, zero is returned.
#In Measure_Text
#Line # returns advance width and bounds of text ##
Returns the advance width of text if kVerticalText_Flag is clear,
and the height of text if kVerticalText_Flag is set.
Returns the advance width of text.
The advance is the normal distance to move before drawing additional text.
Uses Text_Encoding to decode text, Typeface to get the font metrics,
and Text_Size, Text_Scale_X, Text_Skew_X, Stroke_Width, and
@ -4425,8 +4309,7 @@ text contains an invalid UTF-8 sequence, zero is returned.
#Method SkScalar measureText(const void* text, size_t length) const
#In Measure_Text
Returns the advance width of text if kVerticalText_Flag is clear,
and the height of text if kVerticalText_Flag is set.
Returns the advance width of text.
The advance is the normal distance to move before drawing additional text.
Uses Text_Encoding to decode text, Typeface to get the font metrics,
and Text_Size to scale the metrics.
@ -4457,10 +4340,7 @@ text contains an invalid UTF-8 sequence, zero is returned.
#Line # returns text that fits in a width ##
Returns the bytes of text that fit within maxWidth.
If kVerticalText_Flag is clear, the text fragment fits if its advance width is less than or
equal to maxWidth.
If kVerticalText_Flag is set, the text fragment fits if its advance height is less than or
equal to maxWidth.
The text fragment fits if its advance width is less than or equal to maxWidth.
Measures only while the advance is less than or equal to maxWidth.
Returns the advance or the text fragment in measuredWidth if it not nullptr.
Uses Text_Encoding to decode text, Typeface to get the font metrics,
@ -4507,8 +4387,7 @@ text contains an invalid UTF-8 sequence, zero is returned.
Both widths and bounds may be nullptr.
If widths is not nullptr, widths must be an array of glyph count entries.
if bounds is not nullptr, bounds must be an array of glyph count entries.
If kVerticalText_Flag is clear, widths returns the horizontal advance.
If kVerticalText_Flag is set, widths returns the vertical advance.
Widths returns the horizontal advance.
Uses Text_Encoding to decode text, Typeface to get the font metrics,
and Text_Size to scale the widths and bounds.
Does not scale the advance by Fake_Bold or Path_Effect.