Android APIs
public static final class

StaticLayout.Builder

extends Object
java.lang.Object
   ↳ android.text.StaticLayout.Builder

Class Overview

Builder for static layouts. The builder is a newer 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 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.
Protected Methods
void finalize()
Invoked when the garbage collector has detected that this instance is no longer reachable.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public StaticLayout build ()

Added in API level 23

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

public static StaticLayout.Builder obtain (CharSequence source, int start, int end, TextPaint paint, int width)

Added in API level 23

Obtain a builder for constructing StaticLayout objects

Parameters
source The text to be laid out, optionally with spans
start The index of the start of the text
end The index + 1 of the end of the text
paint The base paint used for layout
width The width in pixels
Returns
  • a builder object used for constructing the StaticLayout

public StaticLayout.Builder setAlignment (Layout.Alignment alignment)

Added in API level 23

Set the alignment. The default is ALIGN_NORMAL.

Parameters
alignment Alignment for the resulting StaticLayout
Returns
  • this builder, useful for chaining

public StaticLayout.Builder setBreakStrategy (int breakStrategy)

Added in API level 23

Set break strategy, useful for selecting high quality or balanced paragraph layout options. The default is BREAK_STRATEGY_SIMPLE.

Parameters
breakStrategy break strategy for paragraph layout
Returns
  • this builder, useful for chaining

public StaticLayout.Builder setEllipsize (TextUtils.TruncateAt ellipsize)

Added in API level 23

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 END or MARQUEE, to be ellipsized instead of broken. The default is null, indicating no ellipsis is to be applied.

Parameters
ellipsize type of ellipsis behavior
Returns
  • this builder, useful for chaining

public StaticLayout.Builder setEllipsizedWidth (int ellipsizedWidth)

Added in API level 23

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 width used for ellipsizing, in pixels
Returns
  • this builder, useful for chaining

public StaticLayout.Builder setHyphenationFrequency (int hyphenationFrequency)

Added in API level 23

Set hyphenation frequency, to control the amount of automatic hyphenation used. The default is HYPHENATION_FREQUENCY_NONE.

Parameters
hyphenationFrequency hyphenation frequency for the paragraph
Returns
  • this builder, useful for chaining

public StaticLayout.Builder setIncludePad (boolean includePad)

Added in API level 23

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 whether to include padding
Returns
  • this builder, useful for chaining

public StaticLayout.Builder setIndents (int[] leftIndents, int[] rightIndents)

Added in API level 23

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 array of indent values for left margin, in pixels
rightIndents array of indent values for right margin, in pixels
Returns
  • this builder, useful for chaining

public StaticLayout.Builder setLineSpacing (float spacingAdd, float spacingMult)

Added in API level 23

Set line spacing parameters. The default is 0.0 for spacingAdd and 1.0 for spacingMult.

Parameters
spacingAdd line spacing add
spacingMult line spacing multiplier
Returns
  • this builder, useful for chaining

public StaticLayout.Builder setMaxLines (int maxLines)

Added in API level 23

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 maximum number of lines in the layout
Returns
  • this builder, useful for chaining
See Also

public StaticLayout.Builder setText (CharSequence source)

Added in API level 23

public StaticLayout.Builder setTextDirection (TextDirectionHeuristic textDir)

Added in API level 23

Set the text direction heuristic. The text direction heuristic is used to resolve text direction based per-paragraph based on the input text. The default is FIRSTSTRONG_LTR.

Parameters
textDir text direction heuristic for resolving BiDi behavior.
Returns
  • this builder, useful for chaining

Protected Methods

protected void finalize ()

Added in API level 23

Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.

Note that objects that override finalize are significantly more expensive than objects that don't. Finalizers may be run a long time after the object is no longer reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup. Note also that finalizers are run on a single VM-wide finalizer thread, so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary for a class that has a native peer and needs to call a native method to destroy that peer. Even then, it's better to provide an explicit close method (and implement Closeable), and insist that callers manually dispose of instances. This works well for something like files, but less well for something like a BigInteger where typical calling code would have to deal with lots of temporaries. Unfortunately, code that creates lots of temporaries is the worst kind of code from the point of view of the single finalizer thread.

If you must use finalizers, consider at least providing your own ReferenceQueue and having your own thread process that queue.

Unlike constructors, finalizers are not automatically chained. You are responsible for calling super.finalize() yourself.

Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.

Throws
Throwable