Package icyllis.modernui.text

# Class Layout

java.lang.Object
icyllis.modernui.text.Layout

Direct Known Subclasses:
  `BoringLayout`, `DynamicLayout`, `StaticLayout`

public abstract class Layout extends Object
A base class that manages text layout in visual elements on the screen, which is designed for text pages at high-level.

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

Since:
  3.0
See Also:
  - `StaticLayout`
  - `DynamicLayout`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `Layout.Alignment`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DIR_LEFT_TO_RIGHT`
  `static final int`
  `DIR_RIGHT_TO_LEFT`
  `static final float`
  `TAB_INCREMENT`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Layout(CharSequence text, TextPaint paint, int width, Layout.Alignment align)`
  Subclasses of Layout use this constructor to set the display text, width, and other standard properties.
  `protected`
  `Layout(CharSequence text, TextPaint paint, int width, Layout.Alignment align, TextDirectionHeuristic textDir)`
  Subclasses of Layout use this constructor to set the display text, width, and other standard properties.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `draw(Canvas canvas)`
  Draw this Layout on the specified Canvas.
  `final void`
  `drawBackground(Canvas canvas, int firstLine, int lastLine)`
  Draw the visible background drawables of this Layout on the specified canvas.
  `void`
  `drawText(Canvas canvas, int firstLine, int lastLine)`
  Draw all visible text lines of this Layout on the specified canvas.
  `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, it.unimi.dsi.fastutil.floats.FloatArrayList dest, CharSequence buffer)`
  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, int start, int end, TextPaint paint, TextDirectionHeuristic textDir)`
  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.
  `static float`
  `getDesiredWidthWithLimit(CharSequence source, int start, int end, TextPaint paint, TextDirectionHeuristic textDir, float upperLimit)`
  Return how wide a layout must be in order to display the specified text slice 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.
  `int`
  `getHeight(boolean cap)`
  Return the total height of this layout.
  `int`
  `getIndentAdjust(int line, Layout.Alignment alignment)`
  Returns the left indent for a line.
  `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.
  `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 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.
  `final long`
  `getLineRangeForDraw(Canvas canvas)`
  Computes the range of visible lines that will be drawn on the specified canvas.
  `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`
  `getOffsetForHorizontal(int line, float horiz, boolean primary)`
  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`
  `getPrimaryHorizontal(int offset, boolean clamped)`
  Get the primary horizontal position for the specified text offset, but optionally clamp it so that it doesn't exceed the width of the layout.
  `float`
  `getSecondaryHorizontal(int offset)`
  Get the secondary horizontal position for the specified text offset.
  `float`
  `getSecondaryHorizontal(int offset, boolean clamped)`
  Get the secondary horizontal position for the specified text offset, but optionally clamp it so that it doesn't exceed the width of the layout.
  `void`
  `getSelectionPath(int start, int end, it.unimi.dsi.fastutil.floats.FloatArrayList dest)`
  Calculates the rectangles which should be highlighted to indicate a selection between start and end and feeds them into the given array.
  `final CharSequence`
  `getText()`
  Return the text that is displayed by this Layout.
  `final TextDirectionHeuristic`
  `getTextDirectionHeuristic()`
  Return the heuristic used to determine paragraph text direction.
  `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`
  `isLevelBoundary(int offset)`
  Returns true if the character at offset and the preceding character are at different run levels (and thus there's a split caret).
  `boolean`
  `isRtlCharAt(int offset)`
  Returns true if the character at offset is right to left (RTL).
  `boolean`
  `primaryIsTrailingPrevious(int offset)`
  Checks if the trailing BiDi level should be used for an offset
  `boolean[]`
  `primaryIsTrailingPreviousAllLineOffsets(int line)`
  Computes in linear time the results of calling #primaryIsTrailingPrevious for all offsets on a line.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### DIR_LEFT_TO_RIGHT

    public static final int DIR_LEFT_TO_RIGHT
    See Also:
      - Constant Field Values

  - ### DIR_RIGHT_TO_LEFT

    public static final int DIR_RIGHT_TO_LEFT
    See Also:
      - Constant Field Values

  - ### TAB_INCREMENT

    public static final float TAB_INCREMENT
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Layout

    protected Layout(CharSequence text, TextPaint paint, int width, Layout.Alignment align)
    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.

  - ### Layout

    protected Layout(CharSequence text, TextPaint paint, int width, Layout.Alignment align, TextDirectionHeuristic textDir)
    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.
      `textDir` - the text direction algorithm

- ## Method Details

  - ### draw

    public void draw(@NonNull Canvas canvas)
    Draw this Layout on the specified Canvas.

    Note that this method just calls `drawBackground(Canvas, int, int)` and then `drawText(Canvas, int, int)`. If you need to draw something between the two, such as blinking cursor and selection highlight, you may manually call them separately.

    Parameters:
      `canvas` - the canvas to draw on
    See Also:
      - `drawBackground(Canvas, int, int)`
      - `drawText(Canvas, int, int)`

  - ### drawBackground

    public final void drawBackground(@NonNull Canvas canvas, int firstLine, int lastLine)
    Draw the visible background drawables of this Layout on the specified canvas.

    Significantly, visible area given by `firstLine` and `lastLine` is computed by `getLineRangeForDraw(Canvas)`. You may never just call this method without that method.

    Parameters:
      `canvas` - the canvas to draw on
      `firstLine` - first line index (inclusive)
      `lastLine` - last line index (inclusive)
    See Also:
      - `drawText(Canvas, int, int)`

  - ### drawText

    public void drawText(@NonNull Canvas canvas, int firstLine, int lastLine)
    Draw all visible text lines of this Layout on the specified canvas.

    Significantly, visible area given by `firstLine` and `lastLine` is computed by `getLineRangeForDraw(Canvas)`. You may never just call this method without that method.

    Parameters:
      `canvas` - the canvas to draw on
      `firstLine` - first line index (inclusive)
      `lastLine` - last line index (inclusive)
    See Also:
      - `drawBackground(Canvas, int, int)`

  - ### getLineRangeForDraw

    public final long getLineRangeForDraw(@NonNull Canvas canvas)
    Computes the range of visible lines that will be drawn on the specified canvas. It will be used for `drawText(Canvas, int, int)`. The higher 32 bits represent the first line number, while the lower 32 bits represent the last line number. Note that if the range is empty, then the method returns `~0L`.
    Parameters:
      `canvas` - the canvas used to draw this Layout
    Returns:
      the range of lines that need to be drawn, possibly empty.

  - ### getLineForVertical

    public int getLineForVertical(int vertical)
    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.

  - ### getLineForOffset

    public int getLineForOffset(int offset)
    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.

  - ### getText

    public final CharSequence getText()
    Return the text that is displayed by this Layout.

  - ### getPaint

    public final TextPaint getPaint()
    Return the base Paint properties for this layout. Do NOT change the paint, which may result in funny drawing for this layout.

  - ### getWidth

    public final int getWidth()
    Return the width of this layout.

  - ### getEllipsizedWidth

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

  - ### increaseWidthTo

    public final void increaseWidthTo(int wid)
    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.

  - ### getHeight

    public int getHeight()
    Return the total height of this layout.

  - ### getHeight

    public int getHeight(boolean cap)
    Return the total height of this layout.
    Parameters:
      `cap` - if true and max lines is set, returns the height of the layout at the max lines.

  - ### getAlignment

    public final Layout.Alignment getAlignment()
    Return the base alignment of this layout.

  - ### getTextDirectionHeuristic

    public final TextDirectionHeuristic getTextDirectionHeuristic()
    Return the heuristic used to determine paragraph text direction.

  - ### getLineCount

    public abstract int getLineCount()
    Return the number of lines of text in this layout.

  - ### getLineBounds

    public int getLineBounds(int line, @Nullable 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.
    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

  - ### getLineTop

    public abstract int getLineTop(int line)
    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.

  - ### getLineDescent

    public abstract int getLineDescent(int line)
    Return the descent of the specified line(0…getLineCount() - 1).

  - ### getLineStart

    public abstract int getLineStart(int line)
    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.

  - ### getParagraphDirection

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

  - ### getLineContainsTab

    public abstract boolean getLineContainsTab(int line)
    Returns whether the specified line contains one or more characters that need to be handled specially, like tabs.

  - ### getLineDirections

    public abstract Directions getLineDirections(int line)
    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.

  - ### getTopPadding

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

  - ### getBottomPadding

    public abstract int getBottomPadding()
    Returns the number of extra pixels of descent padding in the bottom line of the Layout.

  - ### getIndentAdjust

    public int getIndentAdjust(int line, Layout.Alignment alignment)
    Returns the left indent for a line.

  - ### getEllipsisStart

    public abstract int getEllipsisStart(int line)
    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().)

  - ### getEllipsisCount

    public abstract int getEllipsisCount(int line)
    Returns the number of characters to be ellipsized away, or 0 if no ellipsis is to take place.

  - ### getLineMax

    public float getLineMax(int line)
    Gets the unsigned horizontal extent of the specified line, including leading margin indent, but excluding trailing whitespace.

  - ### getLineWidth

    public float getLineWidth(int line)
    Gets the unsigned horizontal extent of the specified line, including leading margin indent and trailing whitespace.

  - ### getLineEnd

    public final int getLineEnd(int line)
    Return the text offset after the last character on the specified line.

  - ### getLineVisibleEnd

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

  - ### getLineBottom

    public final int getLineBottom(int line)
    Return the vertical position of the bottom of the specified line.

  - ### getLineBaseline

    public final int getLineBaseline(int line)
    Return the vertical position of the baseline of the specified line.

  - ### getLineAscent

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

  - ### getParagraphAlignment

    public final Layout.Alignment getParagraphAlignment(int line)
    Get the alignment of the specified paragraph, taking into account markup attached to it.

  - ### getParagraphLeft

    public final int getParagraphLeft(int line)
    Get the left edge of the specified paragraph, inset by left margins.

  - ### getParagraphRight

    public final int getParagraphRight(int line)
    Get the right edge of the specified paragraph, inset by right margins.

  - ### primaryIsTrailingPrevious

    public boolean primaryIsTrailingPrevious(int offset)
    Checks if the trailing BiDi level should be used for an offset

    This method is useful when the offset is at the BiDi level transition point and determine which run need to be used. For example, let's think about following input: (L* denotes Left-to-Right characters, R* denotes Right-to-Left characters.) Input (Logical Order): L1 L2 L3 R1 R2 R3 L4 L5 L6 Input (Display Order): L1 L2 L3 R3 R2 R1 L4 L5 L6

    Then, think about selecting the range (3, 6). The offset=3 and offset=6 are ambiguous here since they are at the BiDi transition point. In Android, the offset is considered to be associated with the trailing run if the BiDi level of the trailing run is higher than of the previous run. In this case, the BiDi level of the input text is as follows:

    Input (Logical Order): L1 L2 L3 R1 R2 R3 L4 L5 L6 BiDi Run: [ Run 0 ][ Run 1 ][ Run 2 ] BiDi Level: 0 0 0 1 1 1 0 0 0

    Thus, offset = 3 is part of Run 1 and this method returns true for offset = 3, since the BiDi level of Run 1 is higher than the level of Run 0. Similarly, the offset = 6 is a part of Run 1 and this method returns false for the offset = 6 since the BiDi level of Run 1 is higher than the level of Run 2.

    Returns:
      true if offset is at the BiDi level transition point and trailing BiDi level is higher than previous BiDi level. See above for the detail.

  - ### primaryIsTrailingPreviousAllLineOffsets

    public boolean[] primaryIsTrailingPreviousAllLineOffsets(int line)
    Computes in linear time the results of calling #primaryIsTrailingPrevious for all offsets on a line.
    Parameters:
      `line` - The line giving the offsets we compute the information for
    Returns:
      The array of results, indexed from 0, where 0 corresponds to the line start offset

  - ### getPrimaryHorizontal

    public float getPrimaryHorizontal(int offset)
    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.

  - ### getPrimaryHorizontal

    public float getPrimaryHorizontal(int offset, boolean clamped)
    Get the primary horizontal position for the specified text offset, but optionally clamp it so that it doesn't exceed the width of the layout.

  - ### getSecondaryHorizontal

    public float getSecondaryHorizontal(int offset)
    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.

  - ### getSecondaryHorizontal

    public float getSecondaryHorizontal(int offset, boolean clamped)
    Get the secondary horizontal position for the specified text offset, but optionally clamp it so that it doesn't exceed the width of the layout.

  - ### getOffsetForHorizontal

    public int getOffsetForHorizontal(int line, float horiz)
    Get the character offset on the specified line whose position is closest to the specified horizontal position.

  - ### getOffsetForHorizontal

    public int getOffsetForHorizontal(int line, float horiz, boolean primary)
    Get the character offset on the specified line whose position is closest to the specified horizontal position.
    Parameters:
      `line` - the line used to find the closest offset
      `horiz` - the horizontal position used to find the closest offset
      `primary` - whether to use the primary position or secondary position to find the offset

  - ### isLevelBoundary

    public boolean isLevelBoundary(int offset)
    Returns true if the character at offset and the preceding character are at different run levels (and thus there's a split caret).
    Parameters:
      `offset` - the offset
    Returns:
      true if at a level boundary

  - ### isRtlCharAt

    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

  - ### getOffsetToLeftOf

    public int getOffsetToLeftOf(int offset)

  - ### getOffsetToRightOf

    public int getOffsetToRightOf(int offset)

  - ### getLineLeft

    public float getLineLeft(int line)
    Get the leftmost position that should be exposed for horizontal scrolling on the specified line.

  - ### getLineRight

    public float getLineRight(int line)
    Get the rightmost position that should be exposed for horizontal scrolling on the specified line.

  - ### getCursorPath

    public void getCursorPath(int point, @NonNull it.unimi.dsi.fastutil.floats.FloatArrayList dest, @NonNull CharSequence buffer)
    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.
    Parameters:
      `point` - the cursor offset in chars
      `dest` - the destination lines
      `buffer` - the editing buffer

  - ### getSelectionPath

    public void getSelectionPath(int start, int end, @NonNull it.unimi.dsi.fastutil.floats.FloatArrayList dest)
    Calculates the rectangles which should be highlighted to indicate a selection between start and end and feeds them into the given array.
    Parameters:
      `start` - the starting index of the selection
      `end` - the ending index of the selection
      `dest` - the destination rectangles

  - ### getDesiredWidth

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

    As of O, Uses `TextDirectionHeuristics.FIRSTSTRONG_LTR` as the default text direction heuristics. In the earlier versions uses `TextDirectionHeuristics.LTR` as the default.

  - ### getDesiredWidth

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

    As of O, Uses `TextDirectionHeuristics.FIRSTSTRONG_LTR` as the default text direction heuristics. In the earlier versions uses `TextDirectionHeuristics.LTR` as the default.

  - ### getDesiredWidth

    public static float getDesiredWidth(CharSequence source, int start, int end, TextPaint paint, TextDirectionHeuristic textDir)
    Return how wide a layout must be in order to display the specified text slice with one line per paragraph.

  - ### getDesiredWidthWithLimit

    public static float getDesiredWidthWithLimit(CharSequence source, int start, int end, TextPaint paint, TextDirectionHeuristic textDir, float upperLimit)
    Return how wide a layout must be in order to display the specified text slice with one line per paragraph.

    If the measured width exceeds given limit, returns limit value instead.