Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
Android APIs
public abstract class

Layout

extends Object
java.lang.Object
   ↳ android.text.Layout
Known Direct Subclasses

Class Overview

A base class that manages text layout in visual elements on the screen.

For text that will be edited, use a DynamicLayout , which will be updated as the text changes. For text that will not change, use a StaticLayout .

Summary

Nested Classes
enum Layout.Alignment  
class Layout.Directions Stores information about bidirectional (left-to-right or right-to-left) text within the layout of a line. 
Constants
int DIR_LEFT_TO_RIGHT
int DIR_RIGHT_TO_LEFT
Protected Constructors
Layout ( CharSequence text, TextPaint paint, int width, Layout.Alignment align, float spacingMult, float spacingAdd)
Subclasses of Layout use this constructor to set the display text, width, and other standard properties.
Public Methods
void draw ( Canvas c)
Draw this Layout on the specified Canvas.
void draw ( Canvas canvas, Path highlight, Paint highlightPaint, int cursorOffsetVertical)
Draw this Layout on the specified canvas, with the highlight path drawn between the background and the text.
final Layout.Alignment getAlignment ()
Return the base alignment of this layout.
abstract int getBottomPadding ()
Returns the number of extra pixels of descent padding in the bottom line of the Layout.
void getCursorPath (int point, Path dest, CharSequence editingBuffer)
Fills in the specified Path with a representation of a cursor at the specified offset.
static float getDesiredWidth ( CharSequence source, int start, int end, TextPaint paint)
Return how wide a layout must be in order to display the specified text slice with one line per paragraph.
static float getDesiredWidth ( CharSequence source, TextPaint paint)
Return how wide a layout must be in order to display the specified text with one line per paragraph.
abstract int getEllipsisCount (int line)
Returns the number of characters to be ellipsized away, or 0 if no ellipsis is to take place.
abstract int getEllipsisStart (int line)
Return the offset of the first character to be ellipsized away, relative to the start of the line.
int getEllipsizedWidth ()
Return the width to which this Layout is ellipsizing, or getWidth() if it is not doing anything special.
int getHeight ()
Return the total height of this layout.
final int getLineAscent (int line)
Get the ascent of the text on the specified line.
final int getLineBaseline (int line)
Return the vertical position of the baseline of the specified line.
final int getLineBottom (int line)
Return the vertical position of the bottom of the specified line.
int getLineBounds (int line, Rect bounds)
Return the baseline for the specified line (0…getLineCount() - 1) If bounds is not null, return the top, left, right, bottom extents of the specified line in it.
abstract boolean getLineContainsTab (int line)
Returns whether the specified line contains one or more characters that need to be handled specially, like tabs or emoji.
abstract int getLineCount ()
Return the number of lines of text in this layout.
abstract int getLineDescent (int line)
Return the descent of the specified line(0…getLineCount() - 1).
abstract Layout.Directions getLineDirections (int line)
Returns the directional run information for the specified line.
final int getLineEnd (int line)
Return the text offset after the last character on the specified line.
int getLineForOffset (int offset)
Get the line number on which the specified text offset appears.
int getLineForVertical (int vertical)
Get the line number corresponding to the specified vertical position.
float getLineLeft (int line)
Get the leftmost position that should be exposed for horizontal scrolling on the specified line.
float getLineMax (int line)
Gets the unsigned horizontal extent of the specified line, including leading margin indent, but excluding trailing whitespace.
float getLineRight (int line)
Get the rightmost position that should be exposed for horizontal scrolling on the specified line.
abstract int getLineStart (int line)
Return the text offset of the beginning of the specified line ( 0…getLineCount()).
abstract int getLineTop (int line)
Return the vertical position of the top of the specified line (0…getLineCount()).
int getLineVisibleEnd (int line)
Return the text offset after the last visible character (so whitespace is not counted) on the specified line.
float getLineWidth (int line)
Gets the unsigned horizontal extent of the specified line, including leading margin indent and trailing whitespace.
int getOffsetForHorizontal (int line, float horiz)
Get the character offset on the specified line whose position is closest to the specified horizontal position.
int getOffsetToLeftOf (int offset)
int getOffsetToRightOf (int offset)
final TextPaint getPaint ()
Return the base Paint properties for this layout.
final Layout.Alignment getParagraphAlignment (int line)
Get the alignment of the specified paragraph, taking into account markup attached to it.
abstract int getParagraphDirection (int line)
Returns the primary directionality of the paragraph containing the specified line, either 1 for left-to-right lines, or -1 for right-to-left lines (see DIR_LEFT_TO_RIGHT , DIR_RIGHT_TO_LEFT ).
final int getParagraphLeft (int line)
Get the left edge of the specified paragraph, inset by left margins.
final int getParagraphRight (int line)
Get the right edge of the specified paragraph, inset by right margins.
float getPrimaryHorizontal (int offset)
Get the primary horizontal position for the specified text offset.
float getSecondaryHorizontal (int offset)
Get the secondary horizontal position for the specified text offset.
void getSelectionPath (int start, int end, Path dest)
Fills in the specified Path with a representation of a highlight between the specified offsets.
final float getSpacingAdd ()
Return the number of units of leading that are added to each line.
final float getSpacingMultiplier ()
Return what the text height is multiplied by to get the line height.
final CharSequence getText ()
Return the text that is displayed by this Layout.
abstract int getTopPadding ()
Returns the (negative) number of extra pixels of ascent padding in the top line of the Layout.
final int getWidth ()
Return the width of this layout.
final void increaseWidthTo (int wid)
Increase the width of this layout to the specified width.
boolean isRtlCharAt (int offset)
Returns true if the character at offset is right to left (RTL).
Protected Methods
final boolean isSpanned ()
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int DIR_LEFT_TO_RIGHT

Added in API level 1

Constant Value: 1 (0x00000001)

public static final int DIR_RIGHT_TO_LEFT

Added in API level 1

Constant Value: -1 (0xffffffff)

Protected Constructors

protected Layout ( CharSequence text, TextPaint paint, int width, Layout.Alignment align, float spacingMult, float spacingAdd)

Added in API level 1

Subclasses of Layout use this constructor to set the display text, width, and other standard properties.

Parameters
text the text to render
paint the default paint for the layout. Styles can override various attributes of the paint.
width the wrapping width for the text.
align whether to left, right, or center the text. Styles can override the alignment.
spacingMult factor by which to scale the font size to get the default line spacing
spacingAdd amount to add to the default line spacing

Public Methods

public void draw ( Canvas c)

Added in API level 1

Draw this Layout on the specified Canvas.

public void draw ( Canvas canvas, Path highlight, Paint highlightPaint, int cursorOffsetVertical)

Added in API level 1

Draw this Layout on the specified canvas, with the highlight path drawn between the background and the text.

Parameters
canvas the canvas
highlight the path of the highlight or cursor; can be null
highlightPaint the paint for the highlight
cursorOffsetVertical the amount to temporarily translate the canvas while rendering the highlight

public final Layout.Alignment getAlignment ()

Added in API level 1

Return the base alignment of this layout.

public abstract int getBottomPadding ()

Added in API level 1

Returns the number of extra pixels of descent padding in the bottom line of the Layout.

public void getCursorPath (int point, Path dest, CharSequence editingBuffer)

Added in API level 1

Fills in the specified Path with a representation of a cursor at the specified offset. This will often be a vertical line but can be multiple discontinuous lines in text with multiple directionalities.

public static float getDesiredWidth ( CharSequence source, int start, int end, TextPaint paint)

Added in API level 1

Return how wide a layout must be in order to display the specified text slice with one line per paragraph.

public static float getDesiredWidth ( CharSequence source, TextPaint paint)

Added in API level 1

Return how wide a layout must be in order to display the specified text with one line per paragraph.

public abstract int getEllipsisCount (int line)

Added in API level 1

Returns the number of characters to be ellipsized away, or 0 if no ellipsis is to take place.

public abstract int getEllipsisStart (int line)

Added in API level 1

Return the offset of the first character to be ellipsized away, relative to the start of the line. (So 0 if the beginning of the line is ellipsized, not getLineStart().)

public int getEllipsizedWidth ()

Added in API level 1

Return the width to which this Layout is ellipsizing, or getWidth() if it is not doing anything special.

public int getHeight ()

Added in API level 1

Return the total height of this layout.

public final int getLineAscent (int line)

Added in API level 1

Get the ascent of the text on the specified line. The return value is negative to match the Paint.ascent() convention.

public final int getLineBaseline (int line)

Added in API level 1

Return the vertical position of the baseline of the specified line.

public final int getLineBottom (int line)

Added in API level 1

Return the vertical position of the bottom of the specified line.

public int getLineBounds (int line, Rect bounds)

Added in API level 1

Return the baseline for the specified line (0…getLineCount() - 1) If bounds is not null, return the top, left, right, bottom extents of the specified line in it.

Parameters
line which line to examine (0..getLineCount() - 1)
bounds Optional. If not null, it returns the extent of the line
Returns
  • the Y-coordinate of the baseline

public abstract boolean getLineContainsTab (int line)

Added in API level 1

Returns whether the specified line contains one or more characters that need to be handled specially, like tabs or emoji.

public abstract int getLineCount ()

Added in API level 1

Return the number of lines of text in this layout.

public abstract int getLineDescent (int line)

Added in API level 1

Return the descent of the specified line(0…getLineCount() - 1).

public abstract Layout.Directions getLineDirections (int line)

Added in API level 1

Returns the directional run information for the specified line. The array alternates counts of characters in left-to-right and right-to-left segments of the line.

NOTE: this is inadequate to support bidirectional text, and will change.

public final int getLineEnd (int line)

Added in API level 1

Return the text offset after the last character on the specified line.

public int getLineForOffset (int offset)

Added in API level 1

Get the line number on which the specified text offset appears. If you ask for a position before 0, you get 0; if you ask for a position beyond the end of the text, you get the last line.

public int getLineForVertical (int vertical)

Added in API level 1

Get the line number corresponding to the specified vertical position. If you ask for a position above 0, you get 0; if you ask for a position below the bottom of the text, you get the last line.

public float getLineLeft (int line)

Added in API level 1

Get the leftmost position that should be exposed for horizontal scrolling on the specified line.

public float getLineMax (int line)

Added in API level 1

Gets the unsigned horizontal extent of the specified line, including leading margin indent, but excluding trailing whitespace.

public float getLineRight (int line)

Added in API level 1

Get the rightmost position that should be exposed for horizontal scrolling on the specified line.

public abstract int getLineStart (int line)

Added in API level 1

Return the text offset of the beginning of the specified line ( 0…getLineCount()). If the specified line is equal to the line count, returns the length of the text.

public abstract int getLineTop (int line)

Added in API level 1

Return the vertical position of the top of the specified line (0…getLineCount()). If the specified line is equal to the line count, returns the bottom of the last line.

public int getLineVisibleEnd (int line)

Added in API level 1

Return the text offset after the last visible character (so whitespace is not counted) on the specified line.

public float getLineWidth (int line)

Added in API level 1

Gets the unsigned horizontal extent of the specified line, including leading margin indent and trailing whitespace.

public int getOffsetForHorizontal (int line, float horiz)

Added in API level 1

Get the character offset on the specified line whose position is closest to the specified horizontal position.

public int getOffsetToLeftOf (int offset)

Added in API level 1

public int getOffsetToRightOf (int offset)

Added in API level 1

public final TextPaint getPaint ()

Added in API level 1

Return the base Paint properties for this layout. Do NOT change the paint, which may result in funny drawing for this layout.

public final Layout.Alignment getParagraphAlignment (int line)

Added in API level 1

Get the alignment of the specified paragraph, taking into account markup attached to it.

public abstract int getParagraphDirection (int line)

Added in API level 1

Returns the primary directionality of the paragraph containing the specified line, either 1 for left-to-right lines, or -1 for right-to-left lines (see DIR_LEFT_TO_RIGHT , DIR_RIGHT_TO_LEFT ).

public final int getParagraphLeft (int line)

Added in API level 1

Get the left edge of the specified paragraph, inset by left margins.

public final int getParagraphRight (int line)

Added in API level 1

Get the right edge of the specified paragraph, inset by right margins.

public float getPrimaryHorizontal (int offset)

Added in API level 1

Get the primary horizontal position for the specified text offset. This is the location where a new character would be inserted in the paragraph's primary direction.

public float getSecondaryHorizontal (int offset)

Added in API level 1

Get the secondary horizontal position for the specified text offset. This is the location where a new character would be inserted in the direction other than the paragraph's primary direction.

public void getSelectionPath (int start, int end, Path dest)

Added in API level 1

Fills in the specified Path with a representation of a highlight between the specified offsets. This will often be a rectangle or a potentially discontinuous set of rectangles. If the start and end are the same, the returned path is empty.

public final float getSpacingAdd ()

Added in API level 1

Return the number of units of leading that are added to each line.

public final float getSpacingMultiplier ()

Added in API level 1

Return what the text height is multiplied by to get the line height.

public final CharSequence getText ()

Added in API level 1

Return the text that is displayed by this Layout.

public abstract int getTopPadding ()

Added in API level 1

Returns the (negative) number of extra pixels of ascent padding in the top line of the Layout.

public final int getWidth ()

Added in API level 1

Return the width of this layout.

public final void increaseWidthTo (int wid)

Added in API level 1

Increase the width of this layout to the specified width. Be careful to use this only when you know it is appropriate— it does not cause the text to reflow to use the full new width.

public boolean isRtlCharAt (int offset)

Returns true if the character at offset is right to left (RTL).

Parameters
offset the offset
Returns
  • true if the character is RTL, false if it is LTR

Protected Methods

protected final boolean isSpanned ()

Added in API level 1