Package ej.microvg

## Class VectorFont

- java.lang.Object
- - ej.microvg.VectorFont

- All Implemented Interfaces:
    `Closeable`, `AutoCloseable`

      public class VectorFont
      extends Object
      implements Closeable

  Represents a vector font.

  Font metrics:

  - Font size: the size of the text bounding box. Most of the glyphs will fit into that box, but some may stick out of this box (like glyphs with accent, for example "Ä").
  - Max ascent: the distance above the baseline for the highest glyph across the font.
  - Baseline: the text baseline, a line on which the characters are placed.
  - Max descent: the distance below the baseline for the lowest glyph across the font.

  Important note: The font size should not be confused with the actual font height:

  - The font size specifies the height of the text bounding box, but some glyphs of the font may extend beyond the box.
  - The actual font height is the distance between the line of maximum ascent and the line of maximum descent. All the glyphs of the font will be fully enclosed between these two lines. The actual font height can be retrieved with the method `getHeight(float)`.

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `VectorFont()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `close()` | Closes this font and its associated resources.
    `float` | `getBaselinePosition​(float size)` | Returns the position of the baseline for this font, at given font size.
    `Font` | `getFont​(int size)` | Retrieves a fixed-sized font from this vector font.
    `float` | `getHeight​(float size)` | Returns the height of this font, at given font size.
    `boolean` | `isClosed()` | Returns whether this font has been closed or not.
    `static VectorFont` | `loadFont​(String resourcePath)` | Loads a vector font from a path using a simple text layout.
    `static VectorFont` | `loadFont​(String resourcePath, boolean complexText)` | Loads a vector font from a path using the specified text layout(simple or complex).
    `float` | `measureStringHeight​(String string, float size)` | Returns the height of a string when it is drawn with this font and the given size.
    `float` | `measureStringWidth​(String string, float size)` | Returns the width of a string when it is drawn with this font and the given size.
    `float` | `measureStringWidth​(String string, float size, float letterSpacing)` | Returns the width of a string when it is drawn with this font and the given size.

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

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

- - ### Constructor Detail

    - #### VectorFont

          public VectorFont()

  - ### Method Detail

    - #### loadFont

          public static VectorFont loadFont​(String resourcePath)

      Loads a vector font from a path using a simple text layout. Equivalent to calling `loadFont(resourcePath, false)`.
      Parameters:
        `resourcePath` - the path to get the font from
      Returns:
        a vector font
      Throws:
        `VectorGraphicsException` - if the font could not be loaded (see `VectorGraphicsException.getErrorCode()` for the error cause)

    - #### loadFont

          public static VectorFont loadFont​(String resourcePath,
                                            boolean complexText)

      Loads a vector font from a path using the specified text layout(simple or complex).
      Parameters:
        `resourcePath` - the path to get the font from
        `complexText` - if true the font layouter considers complex text layout features like contextual glyph substitution or positioning.

        Arabic and Thai scripts are examples of scripts that need complex text layout features.

        - Simple text layout uses the glyph advance metrics and the font kerning table.
        - Complex text layout uses the font GPOS and GSUB tables.

        The vector font file should contain the tables needed by the selected text layout.

      Returns:
        a vector font
      Throws:
        `VectorGraphicsException` - if the font could not be loaded or if complexText is true and no complex layouter is available(see `VectorGraphicsException.getErrorCode()` for the error cause)

    - #### isClosed

          public boolean isClosed()

      Returns whether this font has been closed or not.
      Returns:
        `true` if the font has been closed, `false` otherwise

    - #### close

          public void close()

      Closes this font and its associated resources.

      Calling this method on a font which has already been closed has no effect.

      Beware that this method is not thread safe. Any concurrent use of this font to draw a string during the closing may result in a undefined behavior.

      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `Closeable`

    - #### getHeight

          public float getHeight​(float size)

      Returns the height of this font, at given font size.

      The returned value is the distance between the line of maximum ascent and the line of maximum descent (see `VectorFont`).

      This method can be used to size a text area. Since all the glyphs of a font are located between these two lines, any text will fit in an area of that height when drawn with `VectorGraphicsPainter` methods. If, instead, you prefer to adjust the size of your area to be the exact size of a specific text, refer to the method `measureStringHeight(String, float)`.

      The specified font size must be positive. If it is less than or equal to 0, the method will return 0.

      Parameters:
        `size` - the font size, in pixels
      Returns:
        the height of this font at given font size, in pixels
      Throws:
        `VectorGraphicsException` - if the measure could not be obtained for any reason (see `VectorGraphicsException.getErrorCode()`)
      See Also:
        `measureStringHeight(String, float)`, `VectorGraphicsPainter.drawString(ej.microui.display.GraphicsContext, String, VectorFont, float, float, float)`

    - #### getBaselinePosition

          public float getBaselinePosition​(float size)

      Returns the position of the baseline for this font, at given font size.

      The returned value is the distance between the line of maximum ascent and the baseline (see `VectorFont`).

      The specified font size must be positive. If it is less than or equal to 0, the method will return 0.

      Parameters:
        `size` - the font size, in pixels
      Returns:
        the baseline position of this font at given font size, in pixels
      Throws:
        `VectorGraphicsException` - if the measure could not be obtained for any reason (see `VectorGraphicsException.getErrorCode()`)

    - #### measureStringWidth

          public float measureStringWidth​(String string,
                                          float size)

      Returns the width of a string when it is drawn with this font and the given size.

      The returned value is the width of the smallest rectangle that encloses all the glyphs.

      This method can be used to size a text area. The given text will fit perfectly in an area of that width when drawn with `VectorGraphicsPainter` methods.

      Note that the measure includes the gaps between the glyphs (also known as side bearings). For this reason, the measurement for a given string is not equal to the sum of the measurements for each glyph of that string.

      The specified font size must be positive. If it is less than or equal to 0, the method will return 0.

      Equivalent to calling `measureStringWidth(String, float, float)` with a letter spacing of 0.

      Parameters:
        `string` - the string to measure
        `size` - the font size, in pixels
      Returns:
        the width of the specified string, in pixels
      Throws:
        `VectorGraphicsException` - if the measure could not be obtained for any reason (see `VectorGraphicsException.getErrorCode()`)
      See Also:
        `measureStringWidth(String, float, float)`, `VectorGraphicsPainter.drawString(ej.microui.display.GraphicsContext, String, VectorFont, float, float, float)`

    - #### measureStringWidth

          public float measureStringWidth​(String string,
                                          float size,
                                          float letterSpacing)

      Returns the width of a string when it is drawn with this font and the given size.

      The returned value is the width of the smallest rectangle that encloses all the glyphs, taking into account the given extra letter spacing.

      This method can be used to size a text area. The given text will fit perfectly in an area of that width when drawn with `VectorGraphicsPainter` methods.

      Note that the measure includes the gaps between the glyphs (side bearings and extra letter spacing). For this reason, the measurement for a given string is not equal to the sum of the measurements for each glyph of that string.

      The letter spacing argument specifies the extra space to add between the characters. A positive value will move the characters apart, a negative value will move them together. The default value is 0.

      The specified font size must be positive. If it is less than or equal to 0, the method will return 0.

      Parameters:
        `string` - the string to measure
        `size` - the font size, in pixels
        `letterSpacing` - the extra letter spacing to use, in pixels
      Returns:
        the width of the specified string, in pixels
      Throws:
        `VectorGraphicsException` - if the measure could not be obtained for any reason (see `VectorGraphicsException.getErrorCode()`)
      See Also:
        `measureStringWidth(String, float)`, `VectorGraphicsPainter.drawString(ej.microui.display.GraphicsContext, String, VectorFont, float, Matrix, int, BlendMode, float)`

    - #### measureStringHeight

          public float measureStringHeight​(String string,
                                           float size)

      Returns the height of a string when it is drawn with this font and the given size.

      The returned value is the height of the smallest rectangle that encloses all the glyphs.

      This method can be used to size a text area. The given text will fit perfectly in an area of that height when drawn with `VectorGraphicsPainter` methods. If, instead, you prefer to adjust the size of your area to fit any kind of text, refer to the method `getHeight(float)`.

      The specified font size must be positive. If it is less than or equal to 0, the method will return 0.

      Parameters:
        `string` - the string to measure
        `size` - the font size, in pixels
      Returns:
        the height of the specified string, in pixels
      Throws:
        `VectorGraphicsException` - if the measure could not be obtained for any reason (see `VectorGraphicsException.getErrorCode()`)
      See Also:
        `getHeight(float)`, `VectorGraphicsPainter.drawString(ej.microui.display.GraphicsContext, String, VectorFont, float, float, float)`

    - #### getFont

          public Font getFont​(int size)

      Retrieves a fixed-sized font from this vector font.

      Beware that using the resulting `Font` to draw a string while the `VectorFont` is being closed may result in a undefined behavior.

      Parameters:
        `size` - the desired size
      Returns:
        the fixed-sized font
      See Also:
        `Painter.drawString(ej.microui.display.GraphicsContext, String, Font, int, int)`