Package icyllis.modernui.text

# Class TextPaint

java.lang.Object
icyllis.modernui.graphics.Paint
icyllis.modernui.text.TextPaint

public class TextPaint extends Paint
This class holds data used during text measuring and drawing at higher levels. For the base class `FontPaint`, changing any attributes will require a reflow and re-layout, not just re-drawing.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class icyllis.modernui.graphics.Paint

  `Paint.Align, Paint.Cap, Paint.Join, Paint.Style, Paint.TextStyle`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `int`
  `baselineShift`
  `int`
  `bgColor`
  `float`
  `density`
  `int`
  `linkColor`
  `static final int`
  `STRIKETHROUGH_FLAG`
  Paint flag that applies a strike-through decoration to drawn text.
  `static final int`
  `UNDERLINE_FLAG`
  Paint flag that applies an underline decoration to drawn text.
  `int`
  `underlineColor`
  Special value 0 means no custom underline

  ### Fields inherited from class icyllis.modernui.graphics.Paint

  `ALIGN_CENTER, ALIGN_INSIDE, ALIGN_OUTSIDE, BOLD, BOLD_ITALIC, CAP_BUTT, CAP_ROUND, CAP_SQUARE, FILL, FILL_AND_STROKE, ITALIC, JOIN_BEVEL, JOIN_MITER, JOIN_ROUND, mFlags, NORMAL, STROKE, STROKE_AND_FILL`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TextPaint()`
  Creates the new TextPaint.
  `TextPaint(TextPaint paint)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final FontPaint`
  `createInternalPaint()`
  Create a copy of this paint as the base class paint for internal layout engine.
  `boolean`
  `equalsForTextMeasurement(TextPaint paint)`
  Returns true of the passed `TextPaint` will have the different effect on text measurement
  `FontMetricsInt`
  `getFontMetricsInt()`
  `int`
  `getFontMetricsInt(FontMetricsInt fm)`
  Return the font's interline spacing, given the Paint's settings for typeface, textSize, etc.
  `final FontPaint`
  `getInternalPaint()`
  Populates layout attributes to a temporary internal paint and returns.
  `float`
  `getStrikethroughOffset(FontMetricsInt fm)`
  Distance from top of the strike-through line to the baseline in pixels.
  `float`
  `getStrikethroughThickness(FontMetricsInt fm)`
  Returns the thickness of the strike-through line in pixels.
  `Locale`
  `getTextLocale()`
  Get the text's Locale.
  `int`
  `getTextRunCursor(char[] text, int contextStart, int contextLength, int offset, int op)`
  Returns the next cursor position in the run.
  `int`
  `getTextRunCursor(CharSequence text, int contextStart, int contextEnd, int offset, int op)`
  Returns the next cursor position in the run.
  `Typeface`
  `getTypeface()`
  `float`
  `getUnderlineOffset(FontMetricsInt fm)`
  Returns the distance from top of the underline to the baseline in pixels.
  `float`
  `getUnderlineThickness(FontMetricsInt fm)`
  Returns the thickness of the underline in pixels.
  `final boolean`
  `isStrikethrough()`
  Helper for getFlags(), returning true if STRIKE_THRU_TEXT_FLAG bit is set
  `final boolean`
  `isUnderline()`
  Helper for getFlags(), returning true if UNDERLINE_TEXT_FLAG bit is set
  `static TextPaint`
  `obtain()`
  Returns a TextPaint from the shared pool, a `set(TextPaint)` is expected before use and a `recycle()` after use.
  `void`
  `recycle()`
  Recycle this text paint, this object cannot be used anymore after recycling.
  `void`
  `set(TextPaint paint)`
  Copy the data from paint into this TextPaint
  `void`
  `setStrikethrough(boolean strikethrough)`
  Helper for setFlags(), setting or clearing the STRIKE_THRU_TEXT_FLAG bit
  `void`
  `setTextLocale(Locale locale)`
  Set the text locale.
  `void`
  `setTypeface(Typeface typeface)`
  Set the font collection object to draw the text.
  `void`
  `setUnderline(boolean underline)`
  Helper for setFlags(), setting or clearing the UNDERLINE_TEXT_FLAG bit

  ### Methods inherited from class icyllis.modernui.graphics.Paint

  `equals, getAlpha, getAlphaF, getBlendMode, getColor, getColor4f, getColor4f, getColorFilter, getFilterMode, getMipmapMode, getShader, getStrokeAlign, getStrokeCap, getStrokeJoin, getStrokeMiter, getStrokeWidth, getStyle, getTextSize, getTextStyle, hashCode, isAntiAlias, isDither, isFilter, isLinearText, isTextAntiAlias, reset, set, setAlpha, setAlphaF, setAntiAlias, setARGB, setBlendMode, setColor, setColor4f, setColorFilter, setDither, setFilter, setFilterMode, setLinearText, setMipmapMode, setRGBA, setRGBA, setShader, setStroke, setStrokeAlign, setStrokeAlign, setStrokeCap, setStrokeCap, setStrokeJoin, setStrokeJoin, setStrokeMiter, setStrokeWidth, setStyle, setStyle, setTextAntiAlias, setTextSize, setTextStyle`

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

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

- ## Field Details

  - ### UNDERLINE_FLAG

    public static final int UNDERLINE_FLAG
    Paint flag that applies an underline decoration to drawn text.
    See Also:
      - Constant Field Values

  - ### STRIKETHROUGH_FLAG

    public static final int STRIKETHROUGH_FLAG
    Paint flag that applies a strike-through decoration to drawn text.
    See Also:
      - Constant Field Values

  - ### bgColor

    @ColorInt public int bgColor

  - ### baselineShift

    public int baselineShift

  - ### linkColor

    @ColorInt public int linkColor

  - ### density

    public float density

  - ### underlineColor

    @ColorInt public int underlineColor
    Special value 0 means no custom underline

- ## Constructor Details

  - ### TextPaint

    public TextPaint()
    Creates the new TextPaint.

  - ### TextPaint

    @Internal public TextPaint(@NonNull TextPaint paint)

- ## Method Details

  - ### obtain

    @NonNull public static TextPaint obtain()
    Returns a TextPaint from the shared pool, a `set(TextPaint)` is expected before use and a `recycle()` after use.
    Returns:
      a pooled object, states are undefined

  - ### recycle

    public void recycle()
    Recycle this text paint, this object cannot be used anymore after recycling.
    Overrides:
      `recycle` in class `Paint`
    See Also:
      - `Paint.obtain()`

  - ### set

    public void set(@NonNull TextPaint paint)
    Copy the data from paint into this TextPaint

  - ### setTypeface

    public void setTypeface(@NonNull Typeface typeface)
    Set the font collection object to draw the text.
    Parameters:
      `typeface` - the font collection

  - ### getTypeface

    @NonNull public Typeface getTypeface()

  - ### setTextLocale

    public void setTextLocale(@NonNull Locale locale)
    Set the text locale.

    A Locale may affect word break, line break, grapheme cluster break, etc. The locale should match the language of the text to be drawn or user preference, by default, the selected locale should be used `ModernUI.getSelectedLocale()`.

    Parameters:
      `locale` - the paint's locale value for drawing text, must not be null.

  - ### getTextLocale

    @NonNull public Locale getTextLocale()
    Get the text's Locale.
    Returns:
      the paint's Locale used for measuring and drawing text, never null.

  - ### isUnderline

    public final boolean isUnderline()
    Helper for getFlags(), returning true if UNDERLINE_TEXT_FLAG bit is set
    Returns:
      true if the underlineText bit is set in the paint's flags.
    See Also:
      - `setUnderline(boolean)`

  - ### setUnderline

    public void setUnderline(boolean underline)
    Helper for setFlags(), setting or clearing the UNDERLINE_TEXT_FLAG bit
    Parameters:
      `underline` - true to set the underline bit in the paint's flags, false to clear it.
    See Also:
      - `isUnderline()`

  - ### getUnderlineOffset

    public float getUnderlineOffset(@NonNull FontMetricsInt fm)
    Returns the distance from top of the underline to the baseline in pixels.

    The result is positive for positions that are below the baseline. This method returns where the underline should be drawn independent of if the `UNDERLINE_FLAG` bit is set.

    Returns:
      the position of the underline in pixels
    See Also:
      - `isUnderline()`
      - `getUnderlineThickness(FontMetricsInt)`
      - `setUnderline(boolean)`

  - ### getUnderlineThickness

    public float getUnderlineThickness(@NonNull FontMetricsInt fm)
    Returns the thickness of the underline in pixels.
    Returns:
      the thickness of the underline in pixels
    See Also:
      - `isUnderline()`
      - `getUnderlineOffset(FontMetricsInt)`
      - `setUnderline(boolean)`

  - ### isStrikethrough

    public final boolean isStrikethrough()
    Helper for getFlags(), returning true if STRIKE_THRU_TEXT_FLAG bit is set
    Returns:
      true if the `STRIKETHROUGH_FLAG` bit is set in the paint's flags.
    See Also:
      - `setStrikethrough(boolean)`

  - ### setStrikethrough

    public void setStrikethrough(boolean strikethrough)
    Helper for setFlags(), setting or clearing the STRIKE_THRU_TEXT_FLAG bit
    Parameters:
      `strikethrough` - true to set the strikethrough bit in the paint's flags, false to clear it.
    See Also:
      - `isStrikethrough()`

  - ### getStrikethroughOffset

    public float getStrikethroughOffset(@NonNull FontMetricsInt fm)
    Distance from top of the strike-through line to the baseline in pixels.

    The result is negative for positions that are above the baseline. This method returns where the strike-through line should be drawn independent of if the `STRIKETHROUGH_FLAG` bit is set.

    Returns:
      the position of the strike-through line in pixels
    See Also:
      - `getStrikethroughThickness(FontMetricsInt)`

  - ### getStrikethroughThickness

    public float getStrikethroughThickness(@NonNull FontMetricsInt fm)
    Returns the thickness of the strike-through line in pixels.
    Returns:
      the position of the strike-through line in pixels
    See Also:
      - `getStrikethroughOffset(FontMetricsInt)`

  - ### getTextRunCursor

    public int getTextRunCursor(@NonNull char[] text, int contextStart, int contextLength, int offset, int op)
    Returns the next cursor position in the run.

    This avoids placing the cursor between surrogates, between characters that form conjuncts, between base characters and combining marks, or within a reordering cluster.

    ContextStart and offset are relative to the start of text. The context is the shaping context for cursor movement, generally the bounds of the metric span enclosing the cursor in the direction of movement.

    If op is `GraphemeBreak.AT` and the offset is not a valid cursor position, this returns -1. Otherwise, this will never return a value before contextStart or after contextStart + contextLength.

    Parameters:
      `text` - the text
      `contextStart` - the start of the context
      `contextLength` - the length of the context
      `offset` - the cursor position to move from
      `op` - how to move the cursor
    Returns:
      the offset of the next position or -1

  - ### getTextRunCursor

    public int getTextRunCursor(@NonNull CharSequence text, int contextStart, int contextEnd, int offset, int op)
    Returns the next cursor position in the run.

    This avoids placing the cursor between surrogates, between characters that form conjuncts, between base characters and combining marks, or within a reordering cluster.

    ContextStart, contextEnd, and offset are relative to the start of text. The context is the shaping context for cursor movement, generally the bounds of the metric span enclosing the cursor in the direction of movement.

    If op is `GraphemeBreak.AT` and the offset is not a valid cursor position, this returns -1. Otherwise, this will never return a value before contextStart or after contextEnd.

    Parameters:
      `text` - the text
      `contextStart` - the start of the context
      `contextEnd` - the end of the context
      `offset` - the cursor position to move from
      `op` - how to move the cursor
    Returns:
      the offset of the next position, or -1

  - ### equalsForTextMeasurement

    public boolean equalsForTextMeasurement(@Nonnull TextPaint paint)
    Returns true of the passed `TextPaint` will have the different effect on text measurement
    Parameters:
      `paint` - the paint to compare with
    Returns:
      true if given `TextPaint` has the different effect on text measurement.

  - ### getFontMetricsInt

    @NonNull public FontMetricsInt getFontMetricsInt()

  - ### getFontMetricsInt

    public int getFontMetricsInt(@Nullable FontMetricsInt fm)
    Return the font's interline spacing, given the Paint's settings for typeface, textSize, etc. If metrics is not null, return the fontmetric values in it. Note: all values have been converted to integers from floats, in such a way has to make the answers useful for both spacing and clipping. If you want more control over the rounding, call getFontMetrics().

    Note that these are the values for the main typeface, and actual text rendered may need a larger set of values because fallback fonts may get used in rendering the text.

    Returns:
      the font's interline spacing.

  - ### getInternalPaint

    @Internal @NonNull public final FontPaint getInternalPaint()
    Populates layout attributes to a temporary internal paint and returns. See `createInternalPaint()` to create a new paint.
    Returns:
      a shared internal paint

  - ### createInternalPaint

    @Internal @NonNull public final FontPaint createInternalPaint()
    Create a copy of this paint as the base class paint for internal layout engine.
    Returns:
      an internal paint