/*
* Java
*
* Copyright 2020-2024 MicroEJ Corp. All rights reserved.
* This library is provided in source code for use, modification and test, subject to license terms.
* Any modification of the source code will break MicroEJ Corp. warranties on the whole library.
*/
package ej.microvg;
import java.io.Closeable;
import ej.microui.display.Font;
import ej.microui.display.Painter;
/**
* 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 {@link #getHeight(float)}.
*
*
*
* 
*/
public class VectorFont implements Closeable {
/**
* Loads a vector font from a path using a simple text layout. Equivalent to calling
* loadFont(resourcePath, false).
*
* @param resourcePath
* the path to get the font from
* @return a vector font
* @throws VectorGraphicsException
* if the font could not be loaded (see {@link VectorGraphicsException#getErrorCode()} for the error
* cause)
*/
public static VectorFont loadFont(String resourcePath) {
throw new VectorGraphicsException();
}
/**
* Loads a vector font from a path using the specified text layout(simple or complex).
*
* @param resourcePath
* the path to get the font from
* @param 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.
*
* @return a vector font
* @throws VectorGraphicsException
* if the font could not be loaded or if complexText is true and no complex layouter is available(see
* {@link VectorGraphicsException#getErrorCode()} for the error cause)
*/
public static VectorFont loadFont(String resourcePath, boolean complexText) {
throw new VectorGraphicsException();
}
/**
* Returns whether this font has been closed or not.
*
* @return {@code true} if the font has been closed, {@code false} otherwise
*/
public boolean isClosed() {
throw new VectorGraphicsException();
}
/**
* 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.
*/
@Override
public void close() {
throw new VectorGraphicsException();
}
/**
* 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
* {@link 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 {@link 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
* {@link #measureStringHeight(String, float)}.
*
* The specified font size must be positive. If it is less than or equal to 0, the method will return 0.
*
* @param size
* the font size, in pixels
* @return the height of this font at given font size, in pixels
* @throws VectorGraphicsException
* if the measure could not be obtained for any reason (see
* {@link VectorGraphicsException#getErrorCode()})
* @see #measureStringHeight(String, float)
* @see VectorGraphicsPainter#drawString(ej.microui.display.GraphicsContext, String, VectorFont, float, float,
* float)
*/
public float getHeight(float size) {
throw new VectorGraphicsException();
}
/**
* 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 {@link VectorFont}).
*
* The specified font size must be positive. If it is less than or equal to 0, the method will return 0.
*
* @param size
* the font size, in pixels
* @return 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
* {@link VectorGraphicsException#getErrorCode()})
*/
public float getBaselinePosition(float size) {
throw new VectorGraphicsException();
}
/**
* 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 {@link 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 {@link #measureStringWidth(String, float, float)} with a letter spacing of 0.
*
*
* 
*
* @param string
* the string to measure
* @param size
* the font size, in pixels
* @return the width of the specified string, in pixels
* @throws VectorGraphicsException
* if the measure could not be obtained for any reason (see
* {@link VectorGraphicsException#getErrorCode()})
* @see #measureStringWidth(String, float, float)
* @see VectorGraphicsPainter#drawString(ej.microui.display.GraphicsContext, String, VectorFont, float, float,
* float)
*/
public float measureStringWidth(String string, float size) {
throw new VectorGraphicsException();
}
/**
* 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 {@link 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.
*
*
*
*
* @param string
* the string to measure
* @param size
* the font size, in pixels
* @param letterSpacing
* the extra letter spacing to use, in pixels
* @return the width of the specified string, in pixels
* @throws VectorGraphicsException
* if the measure could not be obtained for any reason (see
* {@link VectorGraphicsException#getErrorCode()})
* @see #measureStringWidth(String, float)
* @see VectorGraphicsPainter#drawString(ej.microui.display.GraphicsContext, String, VectorFont, float, Matrix, int,
* BlendMode, float)
*/
public float measureStringWidth(String string, float size, float letterSpacing) {
throw new VectorGraphicsException();
}
/**
* 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 {@link VectorGraphicsPainter} methods. If, instead, you prefer to adjust the size of your area to fit
* any kind of text, refer to the method {@link #getHeight(float)}.
*
* The specified font size must be positive. If it is less than or equal to 0, the method will return 0.
*
*
*
*
* @param string
* the string to measure
* @param size
* the font size, in pixels
* @return the height of the specified string, in pixels
* @throws VectorGraphicsException
* if the measure could not be obtained for any reason (see
* {@link VectorGraphicsException#getErrorCode()})
* @see #getHeight(float)
* @see VectorGraphicsPainter#drawString(ej.microui.display.GraphicsContext, String, VectorFont, float, float,
* float)
*/
public float measureStringHeight(String string, float size) {
throw new VectorGraphicsException();
}
/**
* Retrieves a fixed-sized font from this vector font.
*
* Beware that using the resulting {@link Font} to draw a string while the {@link VectorFont} is being closed may
* result in a undefined behavior.
*
* @param size
* the desired size
* @return the fixed-sized font
* @see Painter#drawString(ej.microui.display.GraphicsContext, String, Font, int, int)
*/
public Font getFont(int size) {
throw new VectorGraphicsException();
}
// /**
// * Loads a vector font from an {@link InputStream}.
// *
// * @param stream
// * the input stream providing the font data
// * @param size
// * the number of bytes to read from the input stream
// * @return a vector font
// * @throws VectorGraphicsException
// * if the font could not be loaded (see {@link VectorGraphicsException#getErrorCode()} for the error
// * cause)
// */
// public static VectorFont loadFont(InputStream stream, int size) {
// throw new VectorGraphicsException();
// }
// /**
// * Returns whether a font can be loaded from a resource.
// *
// * This method may be used to know whether calling {@link VectorFont#loadFont(String)} with the given path would
// be
// * successful or not.
// *
// * @param path
// * the resource path
// * @return {@code true} if the font can be loaded, {@code false} otherwise
// * @throws VectorGraphicsException
// * if the path is not a valid path
// */
// public static boolean canLoadFont(String path) {
// throw new VectorGraphicsException();
// }
}