StaticLayout.Builder | API reference

StaticLayout.Builder | API reference | Android Developers

public static final class StaticLayout.Builder
extends Object

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

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

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

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

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

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.0f or greater

Returns
`StaticLayout.Builder`	this builder, useful for chaining. This value cannot be `null`.

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

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

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