added in API level 23

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 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 setLineSpacing(float spacingAdd, float spacingMult)

Set line spacing parameters.

StaticLayout.Builder setMaxLines(int maxLines)

Set maximum number of lines.

StaticLayout.Builder setText(CharSequence source)
StaticLayout.Builder setTextDirection(TextDirectionHeuristic textDir)

Set the text direction heuristic.

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

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 will never 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 must never be null.

start int: The index of the start of the text

end int: The index + 1 of the end of the text

paint TextPaint: The base paint used for layout

This value must never be null.

width int: The width in pixels

Returns
StaticLayout.Builder a builder object used for constructing the StaticLayout

This value will never 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 must never be null.

Returns
StaticLayout.Builder this builder, useful for chaining

This value will never 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.

Parameters
breakStrategy int: break strategy for paragraph layout

Value is BREAK_STRATEGY_SIMPLE, BREAK_STRATEGY_HIGH_QUALITY or BREAK_STRATEGY_BALANCED.

Returns
StaticLayout.Builder this builder, useful for chaining

This value will never be null.

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

This value will never be null.

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

Returns
StaticLayout.Builder this builder, useful for chaining

This value will never be null.

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.

Parameters
hyphenationFrequency int: hyphenation frequency for the paragraph

Value is HYPHENATION_FREQUENCY_NORMAL, HYPHENATION_FREQUENCY_FULL or HYPHENATION_FREQUENCY_NONE.

Returns
StaticLayout.Builder this builder, useful for chaining

This value will never be null.

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 will never be null.

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 will never 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(Layout.Alignment).

Parameters
justificationMode int: justification mode for the paragraph.

Value is JUSTIFICATION_MODE_NONE or JUSTIFICATION_MODE_INTER_WORD.

Returns
StaticLayout.Builder this builder, useful for chaining.

This value will never be null.

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 will never be null.

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

Returns
StaticLayout.Builder this builder, useful for chaining

This value will never be null.

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 must never be null.

Returns
StaticLayout.Builder this builder, useful for chaining

This value will never be null.

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 will never be null.