Added in API level 23

Summary: Methods | Inherited Methods

StaticLayout.Builder

---

Kotlin |Java

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 StaticLayout after options have been set.
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

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public methods

build

Added in API level 23

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

Added in API level 23

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

Added in API level 23

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

Added in API level 23

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.

Enabling hyphenation with either using 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.

See also:

• TextView.setBreakStrategy(int)
• setHyphenationFrequency(int)

setEllipsize

Added in API level 23

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:

• TextView.setEllipsize(TruncateAt)

setEllipsizedWidth

Added in API level 23

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:

• TextView.setEllipsize(TruncateAt)

setHyphenationFrequency

Added in API level 23

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.

Enabling hyphenation with either using 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.

See also:

• TextView.setHyphenationFrequency(int)
• setBreakStrategy(int)

setIncludePad

Added in API level 23

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:

• TextView.setIncludeFontPadding(boolean)

setIndents

Added in API level 23

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

Added in API level 26

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:

• Paint.setWordSpacing(float)

setLineBreakConfig

Added in API level 33

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.

See also:

• TextView.setLineBreakStyle(int)
• TextView.setLineBreakWordStyle(int)

setLineSpacing

Added in API level 23

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:

• TextView.setLineSpacing(float, float)

setMaxLines

Added in API level 23

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:

• TextView.setMaxLines(int)

setMinimumFontMetrics

Added in API level 35

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

See also:

• TextView.setMinimumFontMetrics(Paint.FontMetrics)
• TextView.getMinimumFontMetrics()
• Layout.getMinimumFontMetrics()
• Layout.Builder.setMinimumFontMetrics(Paint.FontMetrics)
• DynamicLayout.Builder.setMinimumFontMetrics(Paint.FontMetrics)

setShiftDrawingOffsetForStartOverhang

Added in API level 35

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.

See also:

• setUseBoundsForWidth(boolean)
• Layout.getUseBoundsForWidth()

setText

Added in API level 23

public StaticLayout.Builder setText (CharSequence source)

Parameters
source	CharSequence

Returns
StaticLayout.Builder

setTextDirection

Added in API level 23

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

Added in API level 35

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.

See also:

• Layout.getUseBoundsForWidth()
• Layout.Builder.setUseBoundsForWidth(boolean)

setUseLineSpacingFromFallbacks

Added in API level 28

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.