StaticLayout.Builder
public
static
final
class
StaticLayout.Builder
extends Object
java.lang.Object | |
↳ | android.text.StaticLayout.Builder |
Builder for static layouts. The builder is the preferred pattern for constructing
StaticLayout objects and should be preferred over the constructors, particularly to access
newer features. To build a static layout, first call obtain(CharSequence, int, int, TextPaint, int)
with the required
arguments (text, paint, and width), then call setters for optional parameters, and finally
build()
to build the StaticLayout object. Parameters not explicitly set will get
default values.
Summary
Public methods | |
---|---|
StaticLayout
|
build()
Build the |
static
StaticLayout.Builder
|
obtain(CharSequence source, int start, int end, TextPaint paint, int width)
Obtain a builder for constructing StaticLayout objects. |
StaticLayout.Builder
|
setAlignment(Layout.Alignment alignment)
Set the alignment. |
StaticLayout.Builder
|
setBreakStrategy(int breakStrategy)
Set break strategy, useful for selecting high quality or balanced paragraph layout options. |
StaticLayout.Builder
|
setEllipsize(TextUtils.TruncateAt ellipsize)
Set ellipsizing on the layout. |
StaticLayout.Builder
|
setEllipsizedWidth(int ellipsizedWidth)
Set the width as used for ellipsizing purposes, if it differs from the normal layout width. |
StaticLayout.Builder
|
setHyphenationFrequency(int hyphenationFrequency)
Set hyphenation frequency, to control the amount of automatic hyphenation used. |
StaticLayout.Builder
|
setIncludePad(boolean includePad)
Set whether to include extra space beyond font ascent and descent (which is needed to avoid clipping in some languages, such as Arabic and Kannada). |
StaticLayout.Builder
|
setIndents(int[] leftIndents, int[] rightIndents)
Set indents. |
StaticLayout.Builder
|
setJustificationMode(int justificationMode)
Set paragraph justification mode. |
StaticLayout.Builder
|
setLineBreakConfig(LineBreakConfig lineBreakConfig)
Set the line break configuration. |
StaticLayout.Builder
|
setLineSpacing(float spacingAdd, float spacingMult)
Set line spacing parameters. |
StaticLayout.Builder
|
setMaxLines(int maxLines)
Set maximum number of lines. |
StaticLayout.Builder
|
setMinimumFontMetrics(Paint.FontMetrics minimumFontMetrics)
Set the minimum font metrics used for line spacing. |
StaticLayout.Builder
|
setShiftDrawingOffsetForStartOverhang(boolean shiftDrawingOffsetForStartOverhang)
Set true for shifting the drawing x offset for showing overhang at the start position. |
StaticLayout.Builder
|
setText(CharSequence source)
|
StaticLayout.Builder
|
setTextDirection(TextDirectionHeuristic textDir)
Set the text direction heuristic. |
StaticLayout.Builder
|
setUseBoundsForWidth(boolean useBoundsForWidth)
Set true for using width of bounding box as a source of automatic line breaking and drawing. |
StaticLayout.Builder
|
setUseLineSpacingFromFallbacks(boolean useLineSpacingFromFallbacks)
Set whether to respect the ascent and descent of the fallback fonts that are used in displaying the text (which is needed to avoid text from consecutive lines running into each other). |
Inherited methods | |
---|---|
Public methods
build
public StaticLayout build ()
Build the StaticLayout
after options have been set.
Note: the builder object must not be reused in any way after calling this method. Setting parameters after calling this method, or calling it a second time on the same builder object, will likely lead to unexpected results.
Returns | |
---|---|
StaticLayout |
the newly constructed StaticLayout object
This value cannot be null . |
obtain
public static StaticLayout.Builder obtain (CharSequence source, int start, int end, TextPaint paint, int width)
Obtain a builder for constructing StaticLayout objects.
Parameters | |
---|---|
source |
CharSequence : The text to be laid out, optionally with spans
This value cannot be null . |
start |
int : The index of the start of the text
Value is 0 or greater |
end |
int : The index + 1 of the end of the text
Value is 0 or greater |
paint |
TextPaint : The base paint used for layout
This value cannot be null . |
width |
int : The width in pixels
Value is 0 or greater |
Returns | |
---|---|
StaticLayout.Builder |
a builder object used for constructing the StaticLayout
This value cannot be null . |
setAlignment
public StaticLayout.Builder setAlignment (Layout.Alignment alignment)
Set the alignment. The default is Layout.Alignment#ALIGN_NORMAL
.
Parameters | |
---|---|
alignment |
Layout.Alignment : Alignment for the resulting StaticLayout
This value cannot be null . |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining
This value cannot be null . |
setBreakStrategy
public StaticLayout.Builder setBreakStrategy (int breakStrategy)
Set break strategy, useful for selecting high quality or balanced paragraph
layout options. The default is Layout#BREAK_STRATEGY_SIMPLE
.
Layout#HYPHENATION_FREQUENCY_NORMAL
or
Layout#HYPHENATION_FREQUENCY_FULL
while line breaking is set to one of
Layout#BREAK_STRATEGY_BALANCED
, Layout#BREAK_STRATEGY_HIGH_QUALITY
improves the structure of text layout however has performance impact and requires more
time to do the text layout.
Parameters | |
---|---|
breakStrategy |
int : break strategy for paragraph layout
Value is LineBreaker.BREAK_STRATEGY_SIMPLE , LineBreaker.BREAK_STRATEGY_HIGH_QUALITY , or LineBreaker.BREAK_STRATEGY_BALANCED |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining
This value cannot be null . |
setEllipsize
public StaticLayout.Builder setEllipsize (TextUtils.TruncateAt ellipsize)
Set ellipsizing on the layout. Causes words that are longer than the view
is wide, or exceeding the number of lines (see #setMaxLines) in the case
of TextUtils.TruncateAt.END
or
TextUtils.TruncateAt.MARQUEE
, to be ellipsized instead
of broken. The default is null
, indicating no ellipsis is to be applied.
Parameters | |
---|---|
ellipsize |
TextUtils.TruncateAt : type of ellipsis behavior
This value may be null . |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining |
See also:
setEllipsizedWidth
public StaticLayout.Builder setEllipsizedWidth (int ellipsizedWidth)
Set the width as used for ellipsizing purposes, if it differs from the
normal layout width. The default is the width
passed to obtain(CharSequence, int, int, TextPaint, int)
.
Parameters | |
---|---|
ellipsizedWidth |
int : width used for ellipsizing, in pixels
Value is 0 or greater |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining
This value cannot be null . |
See also:
setHyphenationFrequency
public StaticLayout.Builder setHyphenationFrequency (int hyphenationFrequency)
Set hyphenation frequency, to control the amount of automatic hyphenation used. The
possible values are defined in Layout
, by constants named with the pattern
HYPHENATION_FREQUENCY_*
. The default is
Layout#HYPHENATION_FREQUENCY_NONE
.
Layout#HYPHENATION_FREQUENCY_NORMAL
or
Layout#HYPHENATION_FREQUENCY_FULL
while line breaking is set to one of
Layout#BREAK_STRATEGY_BALANCED
, Layout#BREAK_STRATEGY_HIGH_QUALITY
improves the structure of text layout however has performance impact and requires more
time to do the text layout.
Parameters | |
---|---|
hyphenationFrequency |
int : hyphenation frequency for the paragraph
Value is Layout.HYPHENATION_FREQUENCY_NORMAL , Layout.HYPHENATION_FREQUENCY_NORMAL_FAST , Layout.HYPHENATION_FREQUENCY_FULL , Layout.HYPHENATION_FREQUENCY_FULL_FAST , or Layout.HYPHENATION_FREQUENCY_NONE |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining
This value cannot be null . |
setIncludePad
public StaticLayout.Builder setIncludePad (boolean includePad)
Set whether to include extra space beyond font ascent and descent (which is
needed to avoid clipping in some languages, such as Arabic and Kannada). The
default is true
.
Parameters | |
---|---|
includePad |
boolean : whether to include padding |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining
This value cannot be null . |
See also:
setIndents
public StaticLayout.Builder setIndents (int[] leftIndents, int[] rightIndents)
Set indents. Arguments are arrays holding an indent amount, one per line, measured in pixels. For lines past the last element in the array, the last element repeats.
Parameters | |
---|---|
leftIndents |
int : array of indent values for left margin, in pixels
This value may be null . |
rightIndents |
int : array of indent values for right margin, in pixels
This value may be null . |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining
This value cannot be null . |
setJustificationMode
public StaticLayout.Builder setJustificationMode (int justificationMode)
Set paragraph justification mode. The default value is
Layout#JUSTIFICATION_MODE_NONE
. If the last line is too short for justification,
the last line will be displayed with the alignment set by setAlignment(Alignment)
.
When Justification mode is JUSTIFICATION_MODE_INTER_WORD, wordSpacing on the given
Paint
will be ignored. This behavior also affects Spans which change the
wordSpacing.
Parameters | |
---|---|
justificationMode |
int : justification mode for the paragraph.
Value is LineBreaker.JUSTIFICATION_MODE_NONE , LineBreaker.JUSTIFICATION_MODE_INTER_WORD , or LineBreaker.JUSTIFICATION_MODE_INTER_CHARACTER |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining.
This value cannot be null . |
See also:
setLineBreakConfig
public StaticLayout.Builder setLineBreakConfig (LineBreakConfig lineBreakConfig)
Set the line break configuration. The line break will be passed to native used for
calculating the text wrapping. The default value of the line break style is
LineBreakConfig#LINE_BREAK_STYLE_NONE
Parameters | |
---|---|
lineBreakConfig |
LineBreakConfig : the line break configuration for text wrapping.
This value cannot be null . |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining.
This value cannot be null . |
setLineSpacing
public StaticLayout.Builder setLineSpacing (float spacingAdd, float spacingMult)
Set line spacing parameters. Each line will have its line spacing multiplied by
spacingMult
and then increased by spacingAdd
. The default is 0.0 for
spacingAdd
and 1.0 for spacingMult
.
Parameters | |
---|---|
spacingAdd |
float : the amount of line spacing addition |
spacingMult |
float : the line spacing multiplier
Value is 0.0 or greater |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining
This value cannot be null . |
See also:
setMaxLines
public StaticLayout.Builder setMaxLines (int maxLines)
Set maximum number of lines. This is particularly useful in the case of ellipsizing, where it changes the layout of the last line. The default is unlimited.
Parameters | |
---|---|
maxLines |
int : maximum number of lines in the layout
Value is 0 or greater |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining
This value cannot be null . |
See also:
setMinimumFontMetrics
public StaticLayout.Builder setMinimumFontMetrics (Paint.FontMetrics minimumFontMetrics)
Set the minimum font metrics used for line spacing.
null
is the default value. If null
is set or left as default, the
font metrics obtained by Paint#getFontMetricsForLocale(Paint.FontMetrics)
is
used.
The minimum meaning here is the minimum value of line spacing: maximum value of
Paint#ascent()
, minimum value of Paint#descent()
.
By setting this value, each line will have minimum line spacing regardless of the text
rendered. For example, usually Japanese script has larger vertical metrics than Latin
script. By setting the metrics obtained by
Paint#getFontMetricsForLocale(Paint.FontMetrics)
for Japanese or leave it
null
if the Paint's locale is Japanese, the line spacing for Japanese is reserved
if the text is an English text. If the vertical metrics of the text is larger than
Japanese, for example Burmese, the bigger font metrics is used.
Parameters | |
---|---|
minimumFontMetrics |
Paint.FontMetrics : A minimum font metrics. Passing null for using the
value obtained by
Paint#getFontMetricsForLocale(Paint.FontMetrics) |
Returns | |
---|---|
StaticLayout.Builder |
setShiftDrawingOffsetForStartOverhang
public StaticLayout.Builder setShiftDrawingOffsetForStartOverhang (boolean shiftDrawingOffsetForStartOverhang)
Set true for shifting the drawing x offset for showing overhang at the start position.
This flag is ignored if the Layout.getUseBoundsForWidth()
is false.
If this value is false, the Layout draws text from the zero even if there is a glyph
stroke in a region where the x coordinate is negative.
If this value is true, the Layout draws text with shifting the x coordinate of the
drawing bounding box.
This value is false by default.
Parameters | |
---|---|
shiftDrawingOffsetForStartOverhang |
boolean : true for shifting the drawing offset for
showing the stroke that is in the region where
the x coordinate is negative. |
Returns | |
---|---|
StaticLayout.Builder |
This value cannot be null . |
setText
public StaticLayout.Builder setText (CharSequence source)
Parameters | |
---|---|
source |
CharSequence |
Returns | |
---|---|
StaticLayout.Builder |
setTextDirection
public StaticLayout.Builder setTextDirection (TextDirectionHeuristic textDir)
Set the text direction heuristic. The text direction heuristic is used to
resolve text direction per-paragraph based on the input text. The default is
TextDirectionHeuristics#FIRSTSTRONG_LTR
.
Parameters | |
---|---|
textDir |
TextDirectionHeuristic : text direction heuristic for resolving bidi behavior.
This value cannot be null . |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining
This value cannot be null . |
setUseBoundsForWidth
public StaticLayout.Builder setUseBoundsForWidth (boolean useBoundsForWidth)
Set true for using width of bounding box as a source of automatic line breaking and drawing. If this value is false, the Layout determines the drawing offset and automatic line breaking based on total advances. By setting true, use all joined glyph's bounding boxes as a source of text width. If the font has glyphs that have negative bearing X or its xMax is greater than advance, the glyph clipping can happen because the drawing area may be bigger. By setting this to true, the Layout will reserve more spaces for drawing.
Parameters | |
---|---|
useBoundsForWidth |
boolean : True for using bounding box, false for advances. |
Returns | |
---|---|
StaticLayout.Builder |
this builder instance
This value cannot be null . |
setUseLineSpacingFromFallbacks
public StaticLayout.Builder setUseLineSpacingFromFallbacks (boolean useLineSpacingFromFallbacks)
Set whether to respect the ascent and descent of the fallback fonts that are used in displaying the text (which is needed to avoid text from consecutive lines running into each other). If set, fallback fonts that end up getting used can increase the ascent and descent of the lines that they are used on.
For backward compatibility reasons, the default is false
, but setting this to
true is strongly recommended. It is required to be true if text could be in languages
like Burmese or Tibetan where text is typically much taller or deeper than Latin text.
Parameters | |
---|---|
useLineSpacingFromFallbacks |
boolean : whether to expand linespacing based on fallback fonts |
Returns | |
---|---|
StaticLayout.Builder |
this builder, useful for chaining
This value cannot be null . |