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:

  • 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

  • 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

      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

      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.