Layout.Builder
public
static
final
class
Layout.Builder
extends Object
java.lang.Object | |
↳ | android.text.Layout.Builder |
A builder class for Layout object.
Different from StaticLayout.Builder
, this builder generates the optimal layout based
on input. If the given text and parameters can be rendered with BoringLayout
, this
builder generates BoringLayout
instance. Otherwise, StaticLayout
instance is
generated.
See also:
Summary
Public constructors | |
---|---|
Builder(CharSequence text, int start, int end, TextPaint paint, int width)
Construct a builder class. |
Public methods | |
---|---|
Layout
|
build()
Build a Layout object. |
Layout.Builder
|
setAlignment(Layout.Alignment alignment)
Set the text alignment. |
Layout.Builder
|
setBreakStrategy(int breakStrategy)
Set the line break strategy. |
Layout.Builder
|
setEllipsize(TextUtils.TruncateAt ellipsize)
Set the ellipsizing type. |
Layout.Builder
|
setEllipsizedWidth(int ellipsizeWidth)
Set the width as used for ellipsizing purpose in pixels. |
Layout.Builder
|
setFallbackLineSpacingEnabled(boolean fallbackLineSpacing)
Set whether to respect the ascent and descent of the fallback fonts. |
Layout.Builder
|
setFontPaddingIncluded(boolean includeFontPadding)
Set whether including extra padding into the first and the last line height. |
Layout.Builder
|
setHyphenationFrequency(int hyphenationFrequency)
Set the hyphenation frequency. |
Layout.Builder
|
setJustificationMode(int justificationMode)
Set justification mode. |
Layout.Builder
|
setLeftIndents(int[] leftIndents)
Set visually left indents in pixels per lines. |
Layout.Builder
|
setLineBreakConfig(LineBreakConfig lineBreakConfig)
Set the line break configuration. |
Layout.Builder
|
setLineSpacingAmount(float amount)
Set the line spacing amount. |
Layout.Builder
|
setLineSpacingMultiplier(float multiplier)
Set the line spacing multiplier. |
Layout.Builder
|
setMaxLines(int maxLines)
Set the maximum number of lines. |
Layout.Builder
|
setMinimumFontMetrics(Paint.FontMetrics minimumFontMetrics)
Set the minimum font metrics used for line spacing. |
Layout.Builder
|
setRightIndents(int[] rightIndents)
Set visually right indents in pixels per lines. |
Layout.Builder
|
setShiftDrawingOffsetForStartOverhang(boolean shiftDrawingOffsetForStartOverhang)
Set true for shifting the drawing x offset for showing overhang at the start position. |
Layout.Builder
|
setTextDirectionHeuristic(TextDirectionHeuristic textDirection)
Set the text direction heuristics. |
Layout.Builder
|
setUseBoundsForWidth(boolean useBoundsForWidth)
Set true for using width of bounding box as a source of automatic line breaking and drawing. |
Inherited methods | |
---|---|
Public constructors
Builder
public Builder (CharSequence text, int start, int end, TextPaint paint, int width)
Construct a builder class.
Parameters | |
---|---|
text |
CharSequence : a text to be displayed.
This value cannot be null . |
start |
int : an inclusive start index of the text to be displayed.
Value is 0 or greater |
end |
int : an exclusive end index of the text to be displayed.
Value is 0 or greater |
paint |
TextPaint : a paint object to be used for drawing text.
This value cannot be null . |
width |
int : a width constraint in pixels.
Value is 0 or greater |
Public methods
build
public Layout build ()
Build a Layout object.
Returns | |
---|---|
Layout |
This value cannot be null . |
setAlignment
public Layout.Builder setAlignment (Layout.Alignment alignment)
Set the text alignment.
The default value is Layout.Alignment#ALIGN_NORMAL
.
Parameters | |
---|---|
alignment |
Layout.Alignment : an alignment.
This value cannot be null . |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setBreakStrategy
public Layout.Builder setBreakStrategy (int breakStrategy)
Set the line break strategy.
The default value is Layout#BREAK_STRATEGY_SIMPLE
.
Parameters | |
---|---|
breakStrategy |
int : a break strategy for line breaking.
Value is LineBreaker.BREAK_STRATEGY_SIMPLE , LineBreaker.BREAK_STRATEGY_HIGH_QUALITY , or LineBreaker.BREAK_STRATEGY_BALANCED |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setEllipsize
public Layout.Builder setEllipsize (TextUtils.TruncateAt ellipsize)
Set the ellipsizing type.
By setting null, the ellipsize is disabled.
The default value is null
.
Parameters | |
---|---|
ellipsize |
TextUtils.TruncateAt : type of the ellipsize. null for disabling ellipsize. |
Returns | |
---|---|
Layout.Builder |
this builder instance. |
setEllipsizedWidth
public Layout.Builder setEllipsizedWidth (int ellipsizeWidth)
Set the width as used for ellipsizing purpose in pixels. The passed value is ignored and forced to set to the value of width constraint passed in constructor if no ellipsize option is set. The default value is the width constraint.
Parameters | |
---|---|
ellipsizeWidth |
int : a ellipsizing width in pixels.
Value is 0 or greater |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setFallbackLineSpacingEnabled
public Layout.Builder setFallbackLineSpacingEnabled (boolean fallbackLineSpacing)
Set whether to respect the ascent and descent of the fallback fonts.
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.
The default value is false
Parameters | |
---|---|
fallbackLineSpacing |
boolean : whether to expand line height based on fallback fonts. |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setFontPaddingIncluded
public Layout.Builder setFontPaddingIncluded (boolean includeFontPadding)
Set whether including extra padding into the first and the last line height.
By setting true, the first line of the text and the last line of the text will have extra
vertical space for avoiding clipping.
The default value is true
.
Parameters | |
---|---|
includeFontPadding |
boolean : true for including extra space into first and last line. |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setHyphenationFrequency
public Layout.Builder setHyphenationFrequency (int hyphenationFrequency)
Set the hyphenation frequency.
The default value is Layout#HYPHENATION_FREQUENCY_NONE
.
Parameters | |
---|---|
hyphenationFrequency |
int : a hyphenation frequency.
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 | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setJustificationMode
public Layout.Builder setJustificationMode (int justificationMode)
Set justification mode.
When justification mode is Layout#JUSTIFICATION_MODE_INTER_WORD
, the word spacing
on the given Paint passed to the constructor will be ignored. This behavior also affects
spans which change the word spacing.
The default value is Layout#JUSTIFICATION_MODE_NONE
.
Parameters | |
---|---|
justificationMode |
int : justification mode.
Value is LineBreaker.JUSTIFICATION_MODE_NONE , LineBreaker.JUSTIFICATION_MODE_INTER_WORD , or LineBreaker.JUSTIFICATION_MODE_INTER_CHARACTER |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setLeftIndents
public Layout.Builder setLeftIndents (int[] leftIndents)
Set visually left indents in pixels per lines.
For the lines past the last element in the array, the last element repeats. Passing null
for disabling indents.
Note that even with the RTL layout, this method reserve spacing at the visually left of
the line.
The default value is null
.
Parameters | |
---|---|
leftIndents |
int : array of indents values for the left margins in pixels.
This value may be null . |
Returns | |
---|---|
Layout.Builder |
this builder instance. |
setLineBreakConfig
public Layout.Builder setLineBreakConfig (LineBreakConfig lineBreakConfig)
Set the line break configuration.
The default value is a LinebreakConfig instance that has
LineBreakConfig#LINE_BREAK_STYLE_NONE
and
LineBreakConfig#LINE_BREAK_WORD_STYLE_NONE
.
Parameters | |
---|---|
lineBreakConfig |
LineBreakConfig : the line break configuration
This value cannot be null . |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setLineSpacingAmount
public Layout.Builder setLineSpacingAmount (float amount)
Set the line spacing amount.
The specified amount of pixels will be added to each line.
The default value is 0
. The negative value is allowed for squeezing lines.
Parameters | |
---|---|
amount |
float : an amount of pixels to be added to line height. |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setLineSpacingMultiplier
public Layout.Builder setLineSpacingMultiplier (float multiplier)
Set the line spacing multiplier.
The specified value will be multiplied to each line.
The default value is 1
.
Parameters | |
---|---|
multiplier |
float : a multiplier to be applied to the line height
Value is 0 or greater |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setMaxLines
public Layout.Builder setMaxLines (int maxLines)
Set the maximum number of lines. The default value is unlimited.
Parameters | |
---|---|
maxLines |
int : maximum number of lines in the layout.
Value is 1 or greater |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setMinimumFontMetrics
public Layout.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 it 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 | |
---|---|
Layout.Builder |
setRightIndents
public Layout.Builder setRightIndents (int[] rightIndents)
Set visually right indents in pixels per lines.
For the lines past the last element in the array, the last element repeats. Passing null
for disabling indents.
Note that even with the RTL layout, this method reserve spacing at the visually right of
the line.
The default value is null
.
Parameters | |
---|---|
rightIndents |
int : array of indents values for the right margins in pixels.
This value may be null . |
Returns | |
---|---|
Layout.Builder |
this builder instance. |
setShiftDrawingOffsetForStartOverhang
public Layout.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 | |
---|---|
Layout.Builder |
This value cannot be null . |
setTextDirectionHeuristic
public Layout.Builder setTextDirectionHeuristic (TextDirectionHeuristic textDirection)
Set the text direction heuristics.
The text direction heuristics is used to resolve text direction on the text.
The default value is TextDirectionHeuristics#FIRSTSTRONG_LTR
Parameters | |
---|---|
textDirection |
TextDirectionHeuristic : a text direction heuristic.
This value cannot be null . |
Returns | |
---|---|
Layout.Builder |
this builder instance.
This value cannot be null . |
setUseBoundsForWidth
public Layout.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 | |
---|---|
Layout.Builder |
this builder instance
This value cannot be null . |