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).

Method Summary

Modifier and Type	Method and 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

Method Detail

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 Closeable

Specified by:

close in interface AutoCloseable

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())

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)

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)

isClosed

public boolean isClosed()

Returns whether this font has been closed or not.

Returns:

true if the font has been closed, false otherwise

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)

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)

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)