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:
  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
     
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
     
    static final int
     
    static final float
     
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    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.
  • 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.
    Return the base alignment of this layout.
    abstract int
    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
    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
    Return the width to which this Layout is ellipsizing, or getWidth() if it is not doing anything special.
    int
    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
    getLineBottom(int line, boolean includeLineSpacing)
    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
    Returns whether the specified line contains one or more characters that need to be handled specially, like tabs.
    abstract int
    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
    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
    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
    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
    Return the base Paint properties for this layout.
    Get the alignment of the specified paragraph, taking into account markup attached to it.
    abstract int
    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
    Get the right edge of the specified paragraph, inset by right margins.
    float
    Get the primary horizontal position for the specified text offset.
    float
    Get the secondary horizontal position for the specified text offset.
    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 float
     
    final float
     
    Return the text that is displayed by this Layout.
    Return the heuristic used to determine paragraph text direction.
    abstract int
    Returns the (negative) number of extra pixels of ascent padding in the top line of the Layout.
    final int
    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).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

  • Constructor Details

    • Layout

      protected 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.
      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
  • 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

      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

      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:
    • 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

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

      @NonNull 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

      @IntRange(from=0L) 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.
    • getSpacingMultiplier

      public final float getSpacingMultiplier()
    • getSpacingAdd

      public final float getSpacingAdd()
    • 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.
    • getLineBottom

      public int getLineBottom(int line, boolean includeLineSpacing)
      Return the vertical position of the bottom of the specified line.
      Parameters:
      line - index of the line
      includeLineSpacing - whether to include the line spacing
    • 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.
    • 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.
    • 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.
    • 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.
    • 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.