Package ej.microui.display

## Class Font

- java.lang.Object
- - ej.microui.display.Font

-     public abstract class Font
      extends Object

  A `Font` defines how characters are drawn on a `GraphicsContext`.

  A font has a set of identifiers. An identifier is an integer which specifies whether the font is able to render specific languages and alphabets. A value has been assigned to the built-in identifiers: see `FontIdentifiers`. Custom identifiers may be defined in order to identify or find a specific font. For example, a font which contains some special characters like arrows or emojis can be tagged by the font creator with a specific identifier.

  A font has a style, which is a combination of the following style constants: `STYLE_PLAIN`, `STYLE_BOLD` and `SYTLE_ITALIC`.

  A font has a descriptor, which is a string describing the font.

  Fonts can not be created by applications and are rather retrieved from the implementation environment. An application can get the list of all the fonts, the default font or a font with a specific path.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `STYLE_BOLD` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
    `static int` | `STYLE_ITALIC` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
    `static int` | `STYLE_PLAIN` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `Font​(Format format, byte[] fontData)` | Creates a font.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected int` | `charsWidth​(char[] chars, int offset, int length)` | Computes the width of the given char array.
    `int` | `charWidth​(char character)` | Returns the width of a character when it is drawn using this font.
    `protected void` | `drawChars​(GraphicsContext gc, char[] chars, int offset, int length, int x, int y)` | Draws a char array with this font at a position.
    `static Font[]` | `getAllFonts()` | Returns an array containing all the fonts of the system.
    `abstract int` | `getBaselinePosition()` | Returns the vertical distance in pixels between the top of this font and its baseline.
    `static Font` | `getDefaultFont()` | Returns the default font of the system.
    `String` | `getDescriptor()` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
    `static Font` | `getFont​(String path)` | Returns the font matching a given path.
    `abstract int` | `getHeight()` | Returns the height of a line of text when it is drawn using this font.
    `int[]` | `getIdentifiers()` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
    `int` | `getStyle()` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
    `boolean` | `isBold()` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
    `boolean` | `isIdentifierSupported​(int identifier)` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
    `boolean` | `isItalic()` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
    `boolean` | `isMonospaced()` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
    `boolean` | `isPlain()` | Deprecated. only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
    `int` | `stringWidth​(String string)` | Returns the width of a string when it is drawn using this font.
    `int` | `substringWidth​(String string, int offset, int length)` | Returns the width of a part of a string when it is drawn using this font.

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

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

- - ### Field Detail

    - #### STYLE_PLAIN

          @Deprecated
          public static final int STYLE_PLAIN

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      See Also:
        Constant Field Values

    - #### STYLE_BOLD

          @Deprecated
          public static final int STYLE_BOLD

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      See Also:
        Constant Field Values

    - #### STYLE_ITALIC

          @Deprecated
          public static final int STYLE_ITALIC

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Font

          protected Font​(Format format,
                         byte[] fontData)

      Creates a font.

      The format must be a custom font format, a value between `Format.CUSTOM_0` and `Format.CUSTOM_7`.

      The given byte array is used to identify and to use a font in the native world.

      Parameters:
        `format` - the custom font format
        `fontData` - the data of this font
      Throws:
        `IllegalArgumentException` - if the format is not a custom format.

  - ### Method Detail

    - #### getAllFonts

          public static Font[] getAllFonts()

      Returns an array containing all the fonts of the system.
      Returns:
        an array containing all the fonts.
      Throws:
        `MicroUIException` - if MicroUI is not started.

    - #### getDefaultFont

          public static Font getDefaultFont()

      Returns the default font of the system.
      Returns:
        the default font.
      Throws:
        `MicroUIException` - if no font is declared in the system.
        `MicroUIException` - if MicroUI is not started.

    - #### getFont

          public static Font getFont​(String path)

      Returns the font matching a given path.
      Parameters:
        `path` - the path of the desired font.
      Returns:
        the font matching the given path.
      Throws:
        `MicroUIException` - if the resource path does not start with "/".
        `MicroUIException` - if no font matches the given path.
        `MicroUIException` - if MicroUI is not started.

    - #### charWidth

          public int charWidth​(char character)

      Returns the width of a character when it is drawn using this font.

      The width is the horizontal space that would be occupied if the given character were drawn using this font. It also includes the horizontal space that would be added after the character to separate it appropriately from the following characters.

      This method only supports characters in the range U+0000 to U+FFFF. It does not handle characters with code points greater than U+FFFF, which are represented as a pair of char values (referred to as "surrogate pair").

      Parameters:
        `character` - the character to measure.
      Returns:
        the width of the given character.

    - #### stringWidth

          public int stringWidth​(String string)

      Returns the width of a string when it is drawn using this font.

      The width is the horizontal space that would be occupied if the given string were drawn using this font. It also includes the horizontal space between the characters of the string to separate them appropriately.

      Parameters:
        `string` - the string to measure.
      Returns:
        the width of the given string.

    - #### substringWidth

          public int substringWidth​(String string,
                                    int offset,
                                    int length)

      Returns the width of a part of a string when it is drawn using this font.

      The width is the horizontal space that would be occupied if the given substring were drawn using this font. It also includes the horizontal space between the characters of the substring to separate them appropriately.

      Parameters:
        `string` - the string containing the substring to measure.
        `offset` - the index of the first character in the substring to measure.
        `length` - the number of characters to measure.
      Returns:
        the width of the given substring.
      Throws:
        `StringIndexOutOfBoundsException` - if the given offset and length are out of the string bounds.

    - #### getHeight

          public abstract int getHeight()

      Returns the height of a line of text when it is drawn using this font.

      The height includes the size of the font as well as sufficient spacing below the line of text to separate it appropriately from the following lines.

      Returns:
        height of a line of text with this font.

    - #### getBaselinePosition

          public abstract int getBaselinePosition()

      Returns the vertical distance in pixels between the top of this font and its baseline.
      Returns:
        the baseline of this font.

    - #### charsWidth

          protected int charsWidth​(char[] chars,
                                   int offset,
                                   int length)

      Computes the width of the given char array.
      Parameters:
        `chars` - the char array
        `offset` - the starting offset
        `length` - the length
      Returns:
        the width of the given char array
      See Also:
        `charWidth(char)`, `stringWidth(String)`, `substringWidth(String, int, int)`

    - #### drawChars

          protected void drawChars​(GraphicsContext gc,
                                   char[] chars,
                                   int offset,
                                   int length,
                                   int x,
                                   int y)

      Draws a char array with this font at a position.

      The translation of the graphics context is already applied to the given x and y.

      Parameters:
        `gc` - the graphics context to draw on
        `chars` - the char array
        `offset` - the starting offset
        `length` - the length
        `x` - the x coordinate to draw at
        `y` - the y coordinate to draw at
      See Also:
        `Painter.drawString(GraphicsContext, String, Font, int, int)`, `Painter.drawSubstring(GraphicsContext, String, int, int, Font, int, int)`

    - #### getIdentifiers

          @Deprecated
          public int[] getIdentifiers()

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      Returns an array containing all the identifiers supported by this font.

      An identifier can be either one of the identifier constants specified in this class or an specific identifier value defined by the MicroUI implementation.

      Returns:
        an array containing all the identifier supported by this font.

    - #### isIdentifierSupported

          @Deprecated
          public boolean isIdentifierSupported​(int identifier)

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      Returns whether this font supports the given identifier.
      Parameters:
        `identifier` - the identifier to check.
      Returns:
        `true` if this font supports the given identifier, `false` otherwise.

    - #### getStyle

          @Deprecated
          public int getStyle()

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      Returns the style of this font.

      The returned value is a combination of the following style constants: `STYLE_PLAIN`, `STYLE_BOLD` and `SYTLE_ITALIC`.

      Returns:
        the style of this font.

    - #### getDescriptor

          @Deprecated
          public String getDescriptor()

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      Returns the descriptor of this font.

      This method returns an empty string if this font does not have a descriptor.

      Returns:
        the descriptor of this font.

    - #### isPlain

          @Deprecated
          public boolean isPlain()

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      Returns whether this font is plain.
      Returns:
        `true` if this font is plain, `false` otherwise.

    - #### isBold

          @Deprecated
          public boolean isBold()

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      Returns whether this font is bold.
      Returns:
        `true` if this font is bold, `false` otherwise.

    - #### isItalic

          @Deprecated
          public boolean isItalic()

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      Returns whether this font is italic.
      Returns:
        `true` if this font is italic, `false` otherwise.

    - #### isMonospaced

          @Deprecated
          public boolean isMonospaced()

      Deprecated.
      only available in for fonts retrieved with `getDefaultFont()`, `getFont(String)` or `getAllFonts()`.
      Returns whether this font is monospaced.

      A monospaced font is a font in which every character has the same width.

      Returns:
        `true` if this font is monospaced, `false` otherwise.