Package icyllis.modernui.text

# Class MeasuredParagraph

java.lang.Object
icyllis.modernui.text.MeasuredParagraph

@NotThreadSafe public class MeasuredParagraph extends Object
MeasuredParagraph provides text information for rendering purpose.

This class can identify text directions, and break the styled text into text runs of range decreasing step by step (style runs, replacement runs, character style runs, font runs, bidi runs). These text runs compute all characters' font metrics, shaping, measurements and glyph graphs, which are enough to render a paragraph of a rich text under Unicode specification and internationalization standards.

See Also:
  - `MeasuredText`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static MeasuredParagraph`
  `buildForBidi(CharSequence text, int start, int end, TextDirectionHeuristic textDir, MeasuredParagraph recycle)`
  Generates new MeasuredParagraph for Bidi computation.
  `static MeasuredParagraph`
  `buildForStaticLayout(TextPaint paint, LineBreakConfig lineBreakConfig, CharSequence text, int start, int end, TextDirectionHeuristic textDir, boolean fullLayout, MeasuredParagraph recycle)`
  Generates new MeasuredParagraph for StaticLayout.
  `float`
  `getAdvance(int offset)`
  Returns the advance of the char at the given index of the text buffer.
  `float`
  `getAdvance(int start, int end)`
  Returns the advance of the given range.
  `char[]`
  `getChars()`
  Returns the characters to be measured.
  `Directions`
  `getDirections(int start, int end)`
  Returns the directions, based on `getParagraphDir()`}, with given range.
  `void`
  `getExtent(int start, int end, FontMetricsInt fmi)`
  Retrieves the font metrics for the given range.
  `it.unimi.dsi.fastutil.ints.IntArrayList`
  `getFontMetrics()`
  Returns the int array which holds FontMetrics.
  `MeasuredText`
  `getMeasuredText()`
  Returns the result of the MeasuredParagraph.
  `int`
  `getMemoryUsage()`
  Note: This includes the text buffer, and be considered to be recycled later.
  `int`
  `getParagraphDir()`
  Returns the base paragraph direction.
  `it.unimi.dsi.fastutil.ints.IntArrayList`
  `getSpanEndCache()`
  Returns the `MetricAffectingSpan` end indices.
  `int`
  `getTextLength()`
  Returns the length of the paragraph.
  `int`
  `getTextStart()`
  Returns the start offset of the paragraph to the original text.
  `void`
  `recycle()`
  Recycle the MeasuredParagraph.
  `void`
  `release()`
  Release internal arrays.

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

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

- ## Method Details

  - ### release

    public void release()
    Release internal arrays.

  - ### getTextStart

    public int getTextStart()
    Returns the start offset of the paragraph to the original text.

  - ### getTextLength

    public int getTextLength()
    Returns the length of the paragraph. This will be the same value as the length of `getChars()`.

  - ### getChars

    @NonNull public char[] getChars()
    Returns the characters to be measured. This will be the same value as `MeasuredText.getTextBuf()` if `getMeasuredText()` available.
    Returns:
      backend text buffer

  - ### getParagraphDir

    public int getParagraphDir()
    Returns the base paragraph direction.
    Returns:
      either `Layout.DIR_LEFT_TO_RIGHT` or
      invalid @link

          {@link Layout#DIR_RIGHT_TO_LEFT)

  - ### getDirections

    @NonNull public Directions getDirections(int start, int end)
    Returns the directions, based on `getParagraphDir()`}, with given range.
    Parameters:
      `start` - start char index, with start offset
      `end` - end char index, with start offset
    Returns:
      new calculated directions of this paragraph

  - ### getSpanEndCache

    @NonNull public it.unimi.dsi.fastutil.ints.IntArrayList getSpanEndCache()
    Returns the `MetricAffectingSpan` end indices.

    If the input text is not a spanned string, this has one value that is the length of the text.

    This is available only if the MeasuredParagraph is computed with buildForStaticLayout. and the text is not empty. Returns empty array in other cases.

  - ### getFontMetrics

    @NonNull public it.unimi.dsi.fastutil.ints.IntArrayList getFontMetrics()
    Returns the int array which holds FontMetrics.

    This array holds the repeat of ascent, descent of font metrics value.

    This is available only if the MeasuredParagraph is computed with buildForStaticLayout. and the text is not empty. Returns empty array in other cases.

  - ### getMeasuredText

    @Nullable public MeasuredText getMeasuredText()
    Returns the result of the MeasuredParagraph.

    This is available only if the MeasuredParagraph is computed with buildForStaticLayout and the text is not empty. Returns null in other cases.

  - ### getAdvance

    public float getAdvance(int offset)
    Returns the advance of the char at the given index of the text buffer.

    This follows grapheme cluster break. For example: there are 6 chars (uint_16), the first two are the first grapheme, the last four are the second one. Then mAdvances[0] is for the first grapheme, mAdvances[2] for the second one, other elements are zero. It's in the same order of `getChars()`

    This is available only if the MeasuredParagraph is computed with buildForMeasurement. Returns empty array in other cases.

    Parameters:
      `offset` - the char index with start offset
    Returns:
      advance

  - ### getAdvance

    public float getAdvance(int start, int end)
    Returns the advance of the given range.

    This is not available if the MeasuredParagraph is computed with buildForBidi. Returns 0 if the MeasuredParagraph is computed with buildForBidi.

    Parameters:
      `start` - the inclusive start offset of the target region in the text
      `end` - the exclusive end offset of the target region in the text
    Returns:
      advance
    See Also:
      - `getAdvance(int)`

  - ### getExtent

    public void getExtent(@IntRange(from=0L) int start, @IntRange(from=0L) int end, @NonNull FontMetricsInt fmi)
    Retrieves the font metrics for the given range.

    This is available only if the MeasuredParagraph is computed with buildForStaticLayout.

  - ### buildForBidi

    @NonNull public static MeasuredParagraph buildForBidi(@NonNull CharSequence text, int start, int end, @NonNull TextDirectionHeuristic textDir, @Nullable MeasuredParagraph recycle)
    Generates new MeasuredParagraph for Bidi computation.

    If recycle is null, this returns new instance. If recycle is not null, this fills computed result to recycle and returns recycle.

    Parameters:
      `text` - the character sequence to be measured
      `start` - the inclusive start offset of the target region in the text
      `end` - the exclusive end offset of the target region in the text
      `textDir` - the text direction algorithm
      `recycle` - pass existing MeasuredParagraph if you want to recycle it.
    Returns:
      measured text

  - ### buildForStaticLayout

    @NonNull public static MeasuredParagraph buildForStaticLayout(@NonNull TextPaint paint, @Nullable LineBreakConfig lineBreakConfig, @NonNull CharSequence text, @IntRange(from=0L) int start, @IntRange(from=0L) int end, @NonNull TextDirectionHeuristic textDir, boolean fullLayout, @Nullable MeasuredParagraph recycle)
    Generates new MeasuredParagraph for StaticLayout.

    If recycle is null, this returns new instance. If recycle is not null, this fills computed result to recycle and returns recycle.

    Parameters:
      `paint` - the base paint to be used for drawing the text
      `text` - the character sequence to be measured
      `start` - the inclusive start offset of the target region in the text
      `end` - the exclusive end offset of the target region in the text
      `textDir` - the text direction algorithm
      `fullLayout` - true to compute full layout, for rendering the text soon
      `recycle` - pass existing MeasuredParagraph if you want to recycle it
    Returns:
      measured text

  - ### recycle

    public void recycle()
    Recycle the MeasuredParagraph.

  - ### getMemoryUsage

    public int getMemoryUsage()
    Note: This includes the text buffer, and be considered to be recycled later. Input CharSequence is not considered.
    Returns:
      memory usage in bytes