Added in API level 28

Builder

class Builder
kotlin.Any
   ↳ android.text.DynamicLayout.Builder

Builder for dynamic layouts. The builder is the preferred pattern for constructing DynamicLayout objects and should be preferred over the constructors, particularly to access newer features. To build a dynamic layout, first call obtain with the required arguments (base, paint, and width), then call setters for optional parameters, and finally build to build the DynamicLayout object. Parameters not explicitly set will get default values.

Summary

Public methods
DynamicLayout

Build the DynamicLayout after options have been set.

static DynamicLayout.Builder
obtain(base: CharSequence, paint: TextPaint, width: Int)

Obtain a builder for constructing DynamicLayout objects.

DynamicLayout.Builder

Set the alignment.

DynamicLayout.Builder
setBreakStrategy(breakStrategy: Int)

Set break strategy, useful for selecting high quality or balanced paragraph layout options.

DynamicLayout.Builder

Set the transformed text (password transformation being the primary example of a transformation) that will be updated as the base text is changed.

DynamicLayout.Builder!

Set ellipsizing on the layout.

DynamicLayout.Builder
setEllipsizedWidth(ellipsizedWidth: Int)

Set the width as used for ellipsizing purposes, if it differs from the normal layout width.

DynamicLayout.Builder
setHyphenationFrequency(hyphenationFrequency: Int)

Set hyphenation frequency, to control the amount of automatic hyphenation used.

DynamicLayout.Builder
setIncludePad(includePad: Boolean)

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).

DynamicLayout.Builder
setJustificationMode(justificationMode: Int)

Set paragraph justification mode.

DynamicLayout.Builder
setLineSpacing(spacingAdd: Float, spacingMult: Float)

Set line spacing parameters.

DynamicLayout.Builder

Set the text direction heuristic.

DynamicLayout.Builder
setUseLineSpacingFromFallbacks(useLineSpacingFromFallbacks: Boolean)

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).

Public methods

build

Added in API level 28
fun build(): DynamicLayout

Build the DynamicLayout 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.

Return
DynamicLayout the newly constructed DynamicLayout object This value cannot be null.

obtain

Added in API level 28
static fun obtain(
    base: CharSequence,
    paint: TextPaint,
    width: Int
): DynamicLayout.Builder

Obtain a builder for constructing DynamicLayout objects.

Parameters
base CharSequence: This value cannot be null.
paint TextPaint: This value cannot be null.
width Int: Value is 0 or greater
Return
DynamicLayout.Builder This value cannot be null.

setAlignment

Added in API level 28
fun setAlignment(alignment: Layout.Alignment): DynamicLayout.Builder

Set the alignment. The default is Layout.Alignment#ALIGN_NORMAL.

Parameters
alignment Layout.Alignment: Alignment for the resulting DynamicLayout This value cannot be null.
Return
DynamicLayout.Builder this builder, useful for chaining This value cannot be null.

setBreakStrategy

Added in API level 28
fun setBreakStrategy(breakStrategy: Int): DynamicLayout.Builder

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 android.graphics.text.LineBreaker#BREAK_STRATEGY_SIMPLE, android.graphics.text.LineBreaker#BREAK_STRATEGY_HIGH_QUALITY, or android.graphics.text.LineBreaker#BREAK_STRATEGY_BALANCED
Return
DynamicLayout.Builder this builder, useful for chaining This value cannot be null.

setDisplayText

Added in API level 28
fun setDisplayText(display: CharSequence): DynamicLayout.Builder

Set the transformed text (password transformation being the primary example of a transformation) that will be updated as the base text is changed. The default is the 'base' text passed to the builder's constructor.

Parameters
display CharSequence: the transformed text This value cannot be null.
Return
DynamicLayout.Builder this builder, useful for chaining This value cannot be null.

setEllipsize

Added in API level 28
fun setEllipsize(ellipsize: TextUtils.TruncateAt?): DynamicLayout.Builder!

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 android.text.TextUtils.TruncateAt#END or android.text.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.
Return
DynamicLayout.Builder! this builder, useful for chaining

setEllipsizedWidth

Added in API level 28
fun setEllipsizedWidth(ellipsizedWidth: Int): DynamicLayout.Builder

Set the width as used for ellipsizing purposes, if it differs from the normal layout width. The default is the width passed to obtain.

Parameters
ellipsizedWidth Int: width used for ellipsizing, in pixels Value is 0 or greater
Return
DynamicLayout.Builder this builder, useful for chaining This value cannot be null.

setHyphenationFrequency

Added in API level 28
fun setHyphenationFrequency(hyphenationFrequency: Int): DynamicLayout.Builder

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 android.text.Layout#HYPHENATION_FREQUENCY_NORMAL, android.text.Layout#HYPHENATION_FREQUENCY_NORMAL_FAST, android.text.Layout#HYPHENATION_FREQUENCY_FULL, android.text.Layout#HYPHENATION_FREQUENCY_FULL_FAST, or android.text.Layout#HYPHENATION_FREQUENCY_NONE
Return
DynamicLayout.Builder this builder, useful for chaining This value cannot be null.

setIncludePad

Added in API level 28
fun setIncludePad(includePad: Boolean): DynamicLayout.Builder

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
Return
DynamicLayout.Builder this builder, useful for chaining This value cannot be null.

setJustificationMode

Added in API level 28
fun setJustificationMode(justificationMode: Int): DynamicLayout.Builder

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.

Parameters
justificationMode Int: justification mode for the paragraph. Value is android.graphics.text.LineBreaker#JUSTIFICATION_MODE_NONE, or android.graphics.text.LineBreaker#JUSTIFICATION_MODE_INTER_WORD
Return
DynamicLayout.Builder this builder, useful for chaining. This value cannot be null.

setLineSpacing

Added in API level 28
fun setLineSpacing(
    spacingAdd: Float,
    spacingMult: Float
): DynamicLayout.Builder

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
Return
DynamicLayout.Builder this builder, useful for chaining This value cannot be null.

setTextDirection

Added in API level 28
fun setTextDirection(textDir: TextDirectionHeuristic): DynamicLayout.Builder

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.
Return
DynamicLayout.Builder this builder, useful for chaining This value cannot be null.

setUseLineSpacingFromFallbacks

Added in API level 28
fun setUseLineSpacingFromFallbacks(useLineSpacingFromFallbacks: Boolean): DynamicLayout.Builder

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
Return
DynamicLayout.Builder this builder, useful for chaining This value cannot be null.