Package icyllis.modernui.text

# Class TextLine

java.lang.Object
icyllis.modernui.text.TextLine

@Internal public class TextLine extends Object
Represents a line of styled text, for measuring in visual order and for rendering.

Get a new instance using `obtain()`, and when finished with it, return it to the pool using `recycle()`.

Call set to prepare the instance for use, then either draw, measure, metrics, or caretToLeftRightOf.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `draw(Canvas canvas, float x, int top, int y, int bottom)`
  Draw the text line, based on visual order.
  `int`
  `getOffsetToLeftRightOf(int cursor, boolean toLeft)`
  Walk the cursor through this line, skipping conjuncts and zero-width characters.
  `float`
  `measure(int offset, boolean trailing, FontMetricsInt fmi)`
  Returns the signed graphical offset from the leading margin.
  `float[]`
  `measureAllOffsets(boolean[] trailing, FontMetricsInt fmi)`
  `float`
  `metrics(FontMetricsInt fmi)`
  Returns metrics information for the entire line.
  `float`
  `nextTab(float h)`
  Returns the next tab position.
  `static TextLine`
  `obtain()`
  Returns a new TextLine from the shared pool.
  `void`
  `recycle()`
  Puts a TextLine back into the shared pool.
  `void`
  `set(TextPaint paint, CharSequence text, int start, int limit, int dir, Directions directions, boolean hasTabs, TabStops tabStops, int ellipsisStart, int ellipsisEnd)`
  Initializes a TextLine and prepares it for use.

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

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

- ## Method Details

  - ### obtain

    @NonNull public static TextLine obtain()
    Returns a new TextLine from the shared pool.
    Returns:
      an uninitialized TextLine

  - ### recycle

    public void recycle()
    Puts a TextLine back into the shared pool. Do not use this TextLine once it has been returned.

  - ### set

    public void set(@NonNull TextPaint paint, @NonNull CharSequence text, int start, int limit, int dir, @NonNull Directions directions, boolean hasTabs, @Nullable TabStops tabStops, int ellipsisStart, int ellipsisEnd)
    Initializes a TextLine and prepares it for use.
    Parameters:
      `paint` - the base paint for the line
      `text` - the text, can be Styled
      `start` - the start of the line relative to the text
      `limit` - the limit of the line relative to the text
      `dir` - the paragraph direction of this line
      `directions` - the directions information of this line
      `hasTabs` - true if the line might contain tabs
      `tabStops` - the tabStops. Can be null
      `ellipsisStart` - the start of the ellipsis relative to the line
      `ellipsisEnd` - the end of the ellipsis relative to the line. When there is no ellipsis, this should be equal to ellipsisStart.

  - ### draw

    public void draw(@NonNull Canvas canvas, float x, int top, int y, int bottom)
    Draw the text line, based on visual order. If paragraph (base) direction is RTL, then x should be on the opposite side (i.e. leading) corresponding to normal one.
    Parameters:
      `canvas` - canvas to draw on
      `x` - the leading margin position
      `top` - the top of the line
      `y` - the baseline
      `bottom` - the bottom of the line

  - ### metrics

    public float metrics(@Nullable FontMetricsInt fmi)
    Returns metrics information for the entire line.
    Parameters:
      `fmi` - receives font metrics information, can be null
    Returns:
      the signed width of the line

  - ### measure

    public float measure(int offset, boolean trailing, @Nullable FontMetricsInt fmi)
    Returns the signed graphical offset from the leading margin.

    Following examples are all for measuring offset=3. LX(e.g. L0, L1, ...) denotes a character which has LTR BiDi property. On the other hand, RX(e.g. R0, R1, ...) denotes a character which has RTL BiDi property. Assuming all character has 1em width.

    Example 1: All LTR chars within LTR context Input Text (logical) : L0 L1 L2 L3 L4 L5 L6 L7 L8 Input Text (visual) : L0 L1 L2 L3 L4 L5 L6 L7 L8 Output(trailing=true) : |--------| (Returns 3em) Output(trailing=false): |--------| (Returns 3em)

    Example 2: All RTL chars within RTL context. Input Text (logical) : R0 R1 R2 R3 R4 R5 R6 R7 R8 Input Text (visual) : R8 R7 R6 R5 R4 R3 R2 R1 R0 Output(trailing=true) : |--------| (Returns -3em) Output(trailing=false): |--------| (Returns -3em)

    Example 3: BiDi chars within LTR context. Input Text (logical) : L0 L1 L2 R3 R4 R5 L6 L7 L8 Input Text (visual) : L0 L1 L2 R5 R4 R3 L6 L7 L8 Output(trailing=true) : |-----------------| (Returns 6em) Output(trailing=false): |--------| (Returns 3em)

    Example 4: BiDi chars within RTL context. Input Text (logical) : L0 L1 L2 R3 R4 R5 L6 L7 L8 Input Text (visual) : L6 L7 L8 R5 R4 R3 L0 L1 L2 Output(trailing=true) : |-----------------| (Returns -6em) Output(trailing=false): |--------| (Returns -3em)

    Parameters:
      `offset` - the line-relative character offset, between 0 and the line length, inclusive
      `trailing` - no effect if the offset is not on the BiDi transition offset. If the offset is on the BiDi transition offset and true is passed, the offset is regarded as the edge of the trailing run's edge. If false, the offset is regarded as the edge of the preceding run's edge. See example above.
      `fmi` - receives metrics information about the requested character, can be null
    Returns:
      the signed graphical offset from the leading margin to the requested character edge. The positive value means the offset is right from the leading edge. The negative value means the offset is left from the leading edge.

  - ### measureAllOffsets

    public float[] measureAllOffsets(boolean[] trailing, FontMetricsInt fmi)
    Returns:
      The measure results for all possible offsets
    See Also:
      - `measure(int, boolean, FontMetricsInt)`

  - ### getOffsetToLeftRightOf

    public int getOffsetToLeftRightOf(int cursor, boolean toLeft)
    Walk the cursor through this line, skipping conjuncts and zero-width characters.

    This function cannot properly walk the cursor off the ends of the line since it does not know about any shaping on the previous/following line that might affect the cursor position. Callers must either avoid these situations or handle the result specially.

    Parameters:
      `cursor` - the starting position of the cursor, between 0 and the length of the line, inclusive
      `toLeft` - true if the caret is moving to the left.
    Returns:
      the new offset. If it is less than 0 or greater than the length of the line, the previous/following line should be examined to get the actual offset.

  - ### nextTab

    public float nextTab(float h)
    Returns the next tab position.
    Parameters:
      `h` - the (unsigned) offset from the leading margin
    Returns:
      the (unsigned) tab position after this offset