Typeface Class Reference

A typeface represents a size-independent font. More...

#include <juce_Typeface.h>

Inheritance diagram for Typeface:

Public Types
enum	ColourGlyphFormat { colourGlyphFormatBitmap = 1 << 0 , colourGlyphFormatSvg = 1 << 1 , colourGlyphFormatCOLRv0 = 1 << 2 , colourGlyphFormatCOLRv1 = 1 << 3 }
	Kinds of colour glyph format that may be implemented by a particular typeface. More...
using	Ptr = ReferenceCountedObjectPtr<Typeface>
	A handy typedef for a pointer to a typeface.

Public Member Functions
	Typeface (const String &name, const String &newStyle) noexcept
const String &	getName () const noexcept
	Returns the font family of the typeface.
const String &	getStyle () const noexcept
	Returns the font style of the typeface.
	~Typeface () override
	Destructor.
TypefaceMetrics	getMetrics (TypefaceMetricsKind) const
	Returns information about the horizontal metrics of this font.
float	getStringWidth (TypefaceMetricsKind, const String &text, float normalisedHeight=1.0f, float horizontalScale=1.0f)
void	getGlyphPositions (TypefaceMetricsKind, const String &text, Array< int > &glyphs, Array< float > &xOffsets, float normalisedHeight=1.0f, float horizontalScale=1.0f)
void	getOutlineForGlyph (TypefaceMetricsKind, int glyphNumber, Path &path) const
	Returns the outline for a glyph.
Rectangle< float >	getGlyphBounds (TypefaceMetricsKind, int glyphNumber) const
	Returns glyph bounds, normalised to a font height of 1.0.
EdgeTable *	getEdgeTableForGlyph (TypefaceMetricsKind, int glyphNumber, const AffineTransform &transform, float normalisedHeight)
std::vector< GlyphLayer >	getLayersForGlyph (TypefaceMetricsKind, int glyphNumber, const AffineTransform &, float normalisedHeight) const
	Returns the layers that should be painted in order to display this glyph.
int	getColourGlyphFormats () const
	Returns an int with bits set indicating the format of colour glyphs contained in the typeface.
void	applyVerticalHintingTransform (float fontHeight, Path &path)
	Makes an attempt at performing a good overall distortion that will scale a font of the given size to align vertically with the pixel grid.
std::optional< uint32_t >	getNominalGlyphForCodepoint (juce_wchar) const
	Returns the glyph index corresponding to the provided codepoint, or nullopt if no such glyph is found.
virtual Native	getNativeDetails () const =0
virtual Typeface::Ptr	createSystemFallback (const String &text, const String &language) const =0
	Attempts to locate a font with a similar style that is capable of displaying the requested string.
Public Member Functions inherited from ReferenceCountedObject
void	incReferenceCount () noexcept
	Increments the object's reference count.
void	decReferenceCount () noexcept
	Decreases the object's reference count.
bool	decReferenceCountWithoutDeleting () noexcept
	Decreases the object's reference count.
int	getReferenceCount () const noexcept
	Returns the object's current reference count.

Static Public Member Functions
static Ptr	createSystemTypefaceFor (const Font &font)
	Creates a new system typeface.
static Ptr	createSystemTypefaceFor (const void *fontFileData, size_t fontFileDataSize)
	Attempts to create a font from some raw font file data (e.g.
static Ptr	createSystemTypefaceFor (Span< const std::byte >)
	Attempts to create a font from some raw font file data (e.g.
static void	setTypefaceCacheSize (int numFontsToCache)
	Changes the number of fonts that are cached in memory.
static void	clearTypefaceCache ()
	Clears any fonts that are currently cached in memory.
static void	scanFolderForFonts (const File &folder)
	On some platforms, this allows a specific path to be scanned.
static Typeface::Ptr	findSystemTypeface ()
	Returns the system's default UI font.

Additional Inherited Members
Protected Member Functions inherited from ReferenceCountedObject
	ReferenceCountedObject ()=default
	Creates the reference-counted object (with an initial ref count of zero).
	ReferenceCountedObject (const ReferenceCountedObject &) noexcept
	Copying from another object does not affect this one's reference-count.
	ReferenceCountedObject (ReferenceCountedObject &&) noexcept
	Copying from another object does not affect this one's reference-count.
ReferenceCountedObject &	operator= (const ReferenceCountedObject &) noexcept
	Copying from another object does not affect this one's reference-count.
ReferenceCountedObject &	operator= (ReferenceCountedObject &&) noexcept
	Copying from another object does not affect this one's reference-count.
virtual	~ReferenceCountedObject ()
	Destructor.
void	resetReferenceCount () noexcept
	Resets the reference count to zero without deleting the object.

Detailed Description

A typeface represents a size-independent font.

This base class is abstract, but calling createSystemTypefaceFor() will return a platform-specific subclass that can be used.

Normally you should never need to deal directly with Typeface objects - the Font class does everything you typically need for rendering text.

See also

Font

Member Typedef Documentation

Ptr

using Typeface::Ptr = ReferenceCountedObjectPtr<Typeface>

A handy typedef for a pointer to a typeface.

Member Enumeration Documentation

ColourGlyphFormat

enum Typeface::ColourGlyphFormat

Kinds of colour glyph format that may be implemented by a particular typeface.

Most typefaces are monochromatic, and do not support any colour formats. Emoji fonts are likely to implement one or more colour font formats.

At this time, JUCE is able to render only bitmap and COLRv0 fonts. If you allow users to customise fonts, you may wish to hide or otherwise prevent users from selecting fonts that use unsupported colour formats.

Enumerator
colourGlyphFormatBitmap	The typeface includes glyphs represented as bitmaps (normally PNGs)
colourGlyphFormatSvg	The typeface includes glyphs represented as SVGs.
colourGlyphFormatCOLRv0	The typeface uses the COLRv0 format, with support for flat colours.
colourGlyphFormatCOLRv1	The typeface uses the COLRv1 format, with support for gradients and blending modes.

Constructor & Destructor Documentation

Typeface()

Typeface::Typeface ( const String & name, const String & newStyle )

noexcept

~Typeface()

Typeface::~Typeface ( )

override

Destructor.

Member Function Documentation

getName()

const String & Typeface::getName ( ) const

noexcept

Returns the font family of the typeface.

See also

Font::getTypefaceName

References name.

getStyle()

const String & Typeface::getStyle ( ) const

noexcept

Returns the font style of the typeface.

See also

Font::getTypefaceStyle

createSystemTypefaceFor() [1/3]

static Ptr Typeface::createSystemTypefaceFor ( const Font & font )

static

Creates a new system typeface.

createSystemTypefaceFor() [2/3]

static Ptr Typeface::createSystemTypefaceFor ( const void * fontFileData, size_t fontFileDataSize )

static

Attempts to create a font from some raw font file data (e.g.

a TTF or OTF file image). The system will take its own internal copy of the data, so you can free the block once this method has returned.

The typeface will remain registered with the system for as long as there is at least one owner of the returned Ptr. This allows typefaces registered with createSystemTypefaceFor to be created using just a typeface family name, e.g. in font fallback lists.

createSystemTypefaceFor() [3/3]

static Ptr Typeface::createSystemTypefaceFor ( Span< const std::byte > )

static

Attempts to create a font from some raw font file data (e.g.

a TTF or OTF file image). The system will take its own internal copy of the data.

The typeface will remain registered with the system for as long as there is at least one owner of the returned Ptr. This allows typefaces registered with createSystemTypefaceFor to be created using just a typeface family name, e.g. in font fallback lists.

getMetrics()

TypefaceMetrics Typeface::getMetrics ( TypefaceMetricsKind ) const

nodiscard

Returns information about the horizontal metrics of this font.

getStringWidth()

float Typeface::getStringWidth	(	TypefaceMetricsKind	,
		const String &	text,
		float	normalisedHeight = 1.0f,
		float	horizontalScale = 1.0f )

Deprecated

This function has several shortcomings:

• The height parameter is specified in JUCE units rather than in points.
• The result is computed assuming that ligatures and other font features will not be used when rendering the string. There's also no way of specifying a language used for the string, which may affect the widths of CJK text.
• If the typeface doesn't contain suitable glyphs for all characters in the string, missing characters will be substituted with the notdef/tofu glyph instead of attempting to use a different font that contains suitable glyphs.

Measures the width of a line of text. You should never need to call this!

getGlyphPositions()

void Typeface::getGlyphPositions	(	TypefaceMetricsKind	,
		const String &	text,
		Array< int > &	glyphs,
		Array< float > &	xOffsets,
		float	normalisedHeight = 1.0f,
		float	horizontalScale = 1.0f )

Deprecated

This function has several shortcomings:

• The height parameter is specified in JUCE units rather than in points.
• Ligatures are deliberately ignored, which will lead to ugly results if the positions are used to paint text using latin scripts, and potentially illegible results for other scripts. There's also no way of specifying a language used for the string, which may affect the rendering of CJK text.
• If the typeface doesn't contain suitable glyphs for all characters in the string, missing characters will be substituted with the notdef/tofu glyph instead of attempting to use a different font that contains suitable glyphs.

Converts a line of text into its glyph numbers and their positions. You should never need to call this!

getOutlineForGlyph()

void Typeface::getOutlineForGlyph	(	TypefaceMetricsKind	,
		int	glyphNumber,
		Path &	path ) const

Returns the outline for a glyph.

The path returned will be normalised to a font height of 1.0.

getGlyphBounds()

Rectangle< float > Typeface::getGlyphBounds	(	TypefaceMetricsKind	,
		int	glyphNumber ) const

Returns glyph bounds, normalised to a font height of 1.0.

getEdgeTableForGlyph()

EdgeTable * Typeface::getEdgeTableForGlyph	(	TypefaceMetricsKind	,
		int	glyphNumber,
		const AffineTransform &	transform,
		float	normalisedHeight )

Deprecated

Returns a new EdgeTable that contains the path for the given glyph, with the specified transform applied.

This is only capable of returning monochromatic glyphs. In fonts that contain multiple glyph styles with fallbacks (COLRv1, COLRv0, monochromatic), this will always return the monochromatic variant.

The height is specified in JUCE font-height units.

getLayersForGlyph() has better support for multilayer and bitmap glyphs, so it should be preferred in new code.

getLayersForGlyph()

std::vector< GlyphLayer > Typeface::getLayersForGlyph	(	TypefaceMetricsKind	,
		int	glyphNumber,
		const AffineTransform &	,
		float	normalisedHeight ) const

Returns the layers that should be painted in order to display this glyph.

Layers should be painted in the same order as they are returned, i.e. layer[0], layer[1] etc.

This should generally be preferred to getEdgeTableForGlyph, as it is more flexible. Currently, this only supports COLRv0 and bitmap fonts (no SVG or COLRv1). Support for SVG and COLRv1 may be added in the future, depending on demand. However, this would require significant additions to JUCE's rendering code, so it has been omitted for now.

The height is specified in JUCE font-height units.

getColourGlyphFormats()

int Typeface::getColourGlyphFormats

(

)

const

Returns an int with bits set indicating the format of colour glyphs contained in the typeface.

If the typeface has no colour glyphs, no bits will be set. Otherwise, one or more bits will be set depending on the format of the colour glyph information. You can use a bitwise-and operation with the members of the ColourGlyphFormat enum to determine whether a particular format is supported.

const auto isMonochrome   = typeface->getColourGlyphFormats() == 0;
const auto isSvg          = (typeface->getColourGlyphFormats() & Typeface::colourGlyphFormatSvg) != 0;
const auto isSimpleColour = (typeface->getColourGlyphFormats() & (Typeface::colourGlyphFormatBitmap | Typeface::colourGlyphFormatCOLRv0)) != 0;

setTypefaceCacheSize()

static void Typeface::setTypefaceCacheSize ( int numFontsToCache )

static

Changes the number of fonts that are cached in memory.

clearTypefaceCache()

static void Typeface::clearTypefaceCache ( )

static

Clears any fonts that are currently cached in memory.

scanFolderForFonts()

static void Typeface::scanFolderForFonts ( const File & folder )

static

On some platforms, this allows a specific path to be scanned.

On macOS you can load .ttf and .otf files, otherwise this is only available when using FreeType.

applyVerticalHintingTransform()

void Typeface::applyVerticalHintingTransform	(	float	fontHeight,
		Path &	path )

Makes an attempt at performing a good overall distortion that will scale a font of the given size to align vertically with the pixel grid.

The path should be an unscaled (i.e. normalised to height of 1.0) path for a glyph.

getNominalGlyphForCodepoint()

std::optional< uint32_t > Typeface::getNominalGlyphForCodepoint

(

juce_wchar

)

const

Returns the glyph index corresponding to the provided codepoint, or nullopt if no such glyph is found.

getNativeDetails()

virtual Native Typeface::getNativeDetails ( ) const

pure virtual

createSystemFallback()

virtual Typeface::Ptr Typeface::createSystemFallback ( const String & text, const String & language ) const

pure virtual

Attempts to locate a font with a similar style that is capable of displaying the requested string.

This uses system facilities, so will produce different results depending on the operating system and installed fonts. If it's important that your app uses the same fonts on all platforms, then you probably shouldn't use the results of this function.

Note that this accepts a string instead of a single codepoint because the OS may take combining marks and variation selectors into account when selecting an appropriate font. As an example, many fonts include a 'text'/'outline' version of the smiley face emoji. macOS may return Helvetica if the smiley emoji codepoint is passed on its own, but will return the emoji font if the emoji codepoint is followed by the variation-selector-16 codepoint.

To specify your own fallback fonts:

• ensure your preferred fonts provide coverage of all languages/scripts/codepoints that you may need to display
• bundle the fonts in your product, e.g. as binary data and register them when your product starts
• use Font::setPreferredFallbackFamilies() to specify that the bundled fonts should be used before requesting a fallback font from the system

Parameters

text	the returned font will normally be capable of displaying the majority of codepoints in this string
language	BCP 47 language code of the text that includes this codepoint

Returns

nullptr if no fallback could be created

findSystemTypeface()

static Typeface::Ptr Typeface::findSystemTypeface ( )

static

Returns the system's default UI font.

This will differ depending on the platform.

On Linux/fontconfig, this returns the typeface mapped to the name "system-ui", or nullptr if no such font exists.

On Windows, this queries SystemParametersInfo with the key SPI_GETNONCLIENTMETRICS, and returns the lfMessageFont that is returned, or nullptr if the font cannot be found.

On macOS and iOS, this returns the result of CTFontCreateUIFontForLanguage() for the kCTFontUIFontSystem typeface.

On Android 29+, this will use AFontMatcher to return the "system-ui" font. On earlier Android versions, this will attempt to return the Roboto font.

NOTE: The metrics of the system typeface may be significantly different from the metrics of the sans-serif font that JUCE would normally select to be the default font. This is especially evident on Windows: For Segoe UI (the Windows system typeface) the sum of ascender and descender is somewhat larger than the em-size of the font, but for Verdana (the JUCE default sans-serif font on Windows) the sum of ascender and descender is closer to the em-size. When the size of a font is set via FontOptions::withHeight() or Font::setHeight(), JUCE will scale fonts based on the sum of ascender and descender, so switching to Segoe UI might cause text to render at a much smaller size than with Verdana. You may get better results by setting font sizes in points using FontOptions::withFontHeight() and Font::setPointHeight(). When using points, Segoe UI still renders slightly smaller than Verdana, but the differences are less pronounced.

---

The documentation for this class was generated from the following file:

• juce_Typeface.h