Font

#include <font.h>

#include <font_matcher.h>

#include <system_fonts.h>

Summary

Enumerations
Anonymous Enum 26{
  AFONT_WEIGHT_MIN = 0,
  AFONT_WEIGHT_THIN = 100,
  AFONT_WEIGHT_EXTRA_LIGHT = 200,
  AFONT_WEIGHT_LIGHT = 300,
  AFONT_WEIGHT_NORMAL = 400,
  AFONT_WEIGHT_MEDIUM = 500,
  AFONT_WEIGHT_SEMI_BOLD = 600,
  AFONT_WEIGHT_BOLD = 700,
  AFONT_WEIGHT_EXTRA_BOLD = 800,
  AFONT_WEIGHT_BLACK = 900,
  AFONT_WEIGHT_MAX = 1000
} 		enum
Anonymous Enum 27{
  AFAMILY_VARIANT_DEFAULT = 0,
  AFAMILY_VARIANT_COMPACT = 1,
  AFAMILY_VARIANT_ELEGANT = 2
} 		enum

Typedefs
AFont typedef
struct AFont
AFont provides information of the single font configuration.
AFontMatcher typedef
struct AFontMatcher
AFontMatcher performs match operation on given parameters and available font files.
ASystemFontIterator typedef
ASystemFontIterator provides access to the system font configuration.

Functions
AFontMatcher_create()
AFontMatcher *_Nonnull
Select the best font from given parameters.
AFontMatcher_destroy(AFontMatcher *_Nonnull matcher)
void
Destroy the matcher object.
AFontMatcher_match(const AFontMatcher *_Nonnull matcher, const char *_Nonnull familyName, const uint16_t *_Nonnull text, const uint32_t textLength, uint32_t *_Nullable runLengthOut)
AFont *_Nonnull
Performs the matching from the generic font family for the text and select one font.
AFontMatcher_setFamilyVariant(AFontMatcher *_Nonnull matcher, uint32_t familyVariant)
void
Set family variant to matcher.
AFontMatcher_setLocales(AFontMatcher *_Nonnull matcher, const char *_Nonnull languageTags)
void
Set font locales to matcher.
AFontMatcher_setStyle(AFontMatcher *_Nonnull matcher, uint16_t weight, bool italic)
void
Set font style to matcher.
AFont_close(AFont *_Nullable font)
void
Close an AFont.
AFont_getAxisCount(const AFont *_Nonnull font)
size_t
Return a count of font variation settings associated with the current font.
AFont_getAxisTag(const AFont *_Nonnull font, uint32_t axisIndex)
uint32_t
Return an OpenType axis tag associated with the current font.
AFont_getAxisValue(const AFont *_Nonnull font, uint32_t axisIndex)
float
Return an OpenType axis value associated with the current font.
AFont_getCollectionIndex(const AFont *_Nonnull font)
size_t
Return a font collection index value associated with the current font.
AFont_getFontFilePath(const AFont *_Nonnull font)
const char *_Nonnull
Return an absolute path to the current font file.
AFont_getLocale(const AFont *_Nonnull font)
const char *_Nullable
Return a IETF BCP47 compliant language tag associated with the current font.
AFont_getWeight(const AFont *_Nonnull font)
uint16_t
Return a weight value associated with the current font.
AFont_isItalic(const AFont *_Nonnull font)
bool
Return true if the current font is italic, otherwise returns false.
ASystemFontIterator_close(ASystemFontIterator *_Nullable iterator)
void
Close an opened system font iterator, freeing any related resources.
ASystemFontIterator_next(ASystemFontIterator *_Nonnull iterator)
AFont *_Nullable
Move to the next system font.
ASystemFontIterator_open()
ASystemFontIterator *_Nullable
Create a system font iterator.

Enumerations

Anonymous Enum 26

 Anonymous Enum 26
Properties
AFONT_WEIGHT_BLACK

A font weight value for the black weight.

AFONT_WEIGHT_BOLD

A font weight value for the bold weight.

AFONT_WEIGHT_EXTRA_BOLD

A font weight value for the extra-bold weight.

AFONT_WEIGHT_EXTRA_LIGHT

A font weight value for the extra-light weight.

AFONT_WEIGHT_LIGHT

A font weight value for the light weight.

AFONT_WEIGHT_MAX

The maximum value for the font weight value.

AFONT_WEIGHT_MEDIUM

A font weight value for the medium weight.

AFONT_WEIGHT_MIN

The minimum value fot the font weight value.

AFONT_WEIGHT_NORMAL

A font weight value for the normal weight.

AFONT_WEIGHT_SEMI_BOLD

A font weight value for the semi-bold weight.

AFONT_WEIGHT_THIN

A font weight value for the thin weight.

Anonymous Enum 27

 Anonymous Enum 27
Properties
AFAMILY_VARIANT_COMPACT

A family variant value for the compact font family variant.

The compact font family has Latin-based vertical metrics.

AFAMILY_VARIANT_DEFAULT

A family variant value for the system default variant.

AFAMILY_VARIANT_ELEGANT

A family variant value for the elegant font family variant.

The elegant font family may have larger vertical metrics than Latin font.

Typedefs

AFont

struct AFont AFont

AFont provides information of the single font configuration.

AFontMatcher

struct AFontMatcher AFontMatcher

AFontMatcher performs match operation on given parameters and available font files.

This matcher is not a thread-safe object. Do not pass this matcher to other threads.

ASystemFontIterator

struct ASystemFontIterator ASystemFontIterator

ASystemFontIterator provides access to the system font configuration.

ASystemFontIterator is an iterator for all available system font settings. This iterator is not a thread-safe object. Do not pass this iterator to other threads.

Functions

AFontMatcher_create

AFontMatcher *_Nonnull AFontMatcher_create()

Select the best font from given parameters.

Creates a new AFontMatcher object.

Available since API level 29.

AFontMatcher_destroy

void AFontMatcher_destroy(
  AFontMatcher *_Nonnull matcher
)

Destroy the matcher object.

Available since API level 29.

Details
Parameters
matcher
a matcher object. Passing NULL is not allowed.

AFontMatcher_match

AFont *_Nonnull AFontMatcher_match(
  const AFontMatcher *_Nonnull matcher,
  const char *_Nonnull familyName,
  const uint16_t *_Nonnull text,
  const uint32_t textLength,
  uint32_t *_Nullable runLengthOut
)

Performs the matching from the generic font family for the text and select one font.

For more information about generic font families, read W3C spec

Even if no font can render the given text, this function will return a non-null result for drawing Tofu character.

Available since API level 29.

Details
Parameters
matcher
a matcher object. Passing NULL is not allowed.
familyName
a null character terminated font family name
text
a UTF-16 encoded text buffer to be rendered. Do not pass empty string.
textLength
a length of the given text buffer. This must not be zero.
runLengthOut
if not null, the font run length will be filled.
Returns
a font to be used for given text and params. You need to release the returned font by AFont_close when it is no longer needed.

AFontMatcher_setFamilyVariant

void AFontMatcher_setFamilyVariant(
  AFontMatcher *_Nonnull matcher,
  uint32_t familyVariant
)

Set family variant to matcher.

If this function is not called, the matcher performs with AFAMILY_VARIANT_DEFAULT.

Available since API level 29.

Details
Parameters
matcher
a matcher object. Passing NULL is not allowed.
familyVariant

AFontMatcher_setLocales

void AFontMatcher_setLocales(
  AFontMatcher *_Nonnull matcher,
  const char *_Nonnull languageTags
)

Set font locales to matcher.

If this function is not called, the matcher performs with empty locale list.

Available since API level 29.

Details
Parameters
matcher
a matcher object. Passing NULL is not allowed.
languageTags
a null character terminated comma separated IETF BCP47 compliant language tags.

AFontMatcher_setStyle

void AFontMatcher_setStyle(
  AFontMatcher *_Nonnull matcher,
  uint16_t weight,
  bool italic
)

Set font style to matcher.

If this function is not called, the matcher performs with AFONT_WEIGHT_NORMAL with non-italic style.

Available since API level 29.

Details
Parameters
matcher
a matcher object. Passing NULL is not allowed.
weight
a font weight value. Only from 0 to 1000 value is valid
italic
true if italic, otherwise false.

AFont_close

void AFont_close(
  AFont *_Nullable font
)

Close an AFont.

Available since API level 29.

Details
Parameters
font
a font returned by ASystemFontIterator_next or AFontMatchert_match. Do nothing if NULL is passed.

AFont_getAxisCount

size_t AFont_getAxisCount(
  const AFont *_Nonnull font
)

Return a count of font variation settings associated with the current font.

The font variation settings are provided as multiple tag-values pairs.

For example, bold italic font may have following font variation settings: 'wght' 700, 'slnt' -12 In this case, AFont_getAxisCount returns 2 and AFont_getAxisTag and AFont_getAxisValue will return following values. 

AFont* font = ASystemFontIterator_next(ite);

// Returns the number of axes
AFont_getAxisCount(font);  // Returns 2

// Returns the tag-value pair for the first axis.
AFont_getAxisTag(font, 0);  // Returns 'wght'(0x77676874)
AFont_getAxisValue(font, 0);  // Returns 700.0

// Returns the tag-value pair for the second axis.
AFont_getAxisTag(font, 1);  // Returns 'slnt'(0x736c6e74)
AFont_getAxisValue(font, 1);  // Returns -12.0

For more information about font variation settings, read Font Variations Table

Available since API level 29.

Details
Parameters
font
a font object. Passing NULL is not allowed.
Returns
a number of font variation settings.

AFont_getAxisTag

uint32_t AFont_getAxisTag(
  const AFont *_Nonnull font,
  uint32_t axisIndex
)

Return an OpenType axis tag associated with the current font.

See AFont_getAxisCount for more details.

Available since API level 29.

Details
Parameters
font
a font object. Passing NULL is not allowed.
axisIndex
an index to the font variation settings. Passing value larger than or equal to AFont_getAxisCount is not allowed.
Returns
an OpenType axis tag value for the given font variation setting.

AFont_getAxisValue

float AFont_getAxisValue(
  const AFont *_Nonnull font,
  uint32_t axisIndex
)

Return an OpenType axis value associated with the current font.

See AFont_getAxisCount for more details.

Available since API level 29.

Details
Parameters
font
a font object. Passing NULL is not allowed.
axisIndex
an index to the font variation settings. Passing value larger than or equal to AFont_getAxisCount is not allowed.
Returns
a float value for the given font variation setting.

AFont_getCollectionIndex

size_t AFont_getCollectionIndex(
  const AFont *_Nonnull font
)

Return a font collection index value associated with the current font.

In case the target font file is a font collection (e.g. .ttc or .otc), this returns a non-negative value as an font offset in the collection. This always returns 0 if the target font file is a regular font.

Available since API level 29.

Details
Parameters
font
a font object. Passing NULL is not allowed.
Returns
a font collection index.

AFont_getFontFilePath

const char *_Nonnull AFont_getFontFilePath(
  const AFont *_Nonnull font
)

Return an absolute path to the current font file.

Here is a list of font formats returned by this method:

  • OpenType
  • OpenType Font Collection
  • TrueType
  • TrueType Collection
The file extension could be one of *.otf, *.ttf, *.otc or *.ttc.

The font file returned is guaranteed to be opend with O_RDONLY. Note that the returned pointer is valid until AFont_close() is called for the given font.

Available since API level 29.

Details
Parameters
font
a font object. Passing NULL is not allowed.
Returns
a string of the font file path.

AFont_getLocale

const char *_Nullable AFont_getLocale(
  const AFont *_Nonnull font
)

Return a IETF BCP47 compliant language tag associated with the current font.

For information about IETF BCP47, read Locale.forLanguageTag(java.lang.String)")

Note that the returned pointer is valid until AFont_close() is called.

Available since API level 29.

Details
Parameters
font
a font object. Passing NULL is not allowed.
Returns
a IETF BCP47 compliant language tag or nullptr if not available.

AFont_getWeight

uint16_t AFont_getWeight(
  const AFont *_Nonnull font
)

Return a weight value associated with the current font.

The weight values are positive and less than or equal to 1000. Here are pairs of the common names and their values.

Value Name NDK Definition
100 Thin AFONT_WEIGHT_THIN
200 Extra Light (Ultra Light) AFONT_WEIGHT_EXTRA_LIGHT
300 Light AFONT_WEIGHT_LIGHT
400 Normal (Regular) AFONT_WEIGHT_NORMAL
500 Medium AFONT_WEIGHT_MEDIUM
600 Semi Bold (Demi Bold) AFONT_WEIGHT_SEMI_BOLD
700 Bold AFONT_WEIGHT_BOLD
800 Extra Bold (Ultra Bold) AFONT_WEIGHT_EXTRA_BOLD
900 Black (Heavy) AFONT_WEIGHT_BLACK

Note that the weight value may fall in between above values, e.g. 250 weight.

For more information about font weight, read OpenType usWeightClass

Available since API level 29.

Details
Parameters
font
a font object. Passing NULL is not allowed.
Returns
a positive integer less than or equal to AFONT_WEIGHT_MAX is returned.

AFont_isItalic

bool AFont_isItalic(
  const AFont *_Nonnull font
)

Return true if the current font is italic, otherwise returns false.

Available since API level 29.

Details
Parameters
font
a font object. Passing NULL is not allowed.
Returns
true if italic, otherwise false.

ASystemFontIterator_close

void ASystemFontIterator_close(
  ASystemFontIterator *_Nullable iterator
)

Close an opened system font iterator, freeing any related resources.

Available since API level 29.

Details
Parameters
iterator
a pointer of an iterator for the system fonts. Do nothing if NULL is passed.

ASystemFontIterator_next

AFont *_Nullable ASystemFontIterator_next(
  ASystemFontIterator *_Nonnull iterator
)

Move to the next system font.

Available since API level 29.

Details
Parameters
iterator
an iterator for the system fonts. Passing NULL is not allowed.
Returns
a font. If no more font is available, returns nullptr. You need to release the returned font with AFont_close() when it is no longer needed.

ASystemFontIterator_open

ASystemFontIterator *_Nullable ASystemFontIterator_open()

Create a system font iterator.

Use ASystemFontIterator_close() to close the iterator.

Available since API level 29.

Details
Returns
a pointer for a newly allocated iterator, nullptr on failure.