juce::Typeface Class Reference

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

#include <juce_Typeface.h>

Inheritance diagram for juce::Typeface:

Collaboration diagram for juce::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
	~Typeface () override
	Destructor.
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.
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.
void	decReferenceCount () noexcept
	Decreases the object's reference count.
bool	decReferenceCountWithoutDeleting () noexcept
	Decreases the object's reference count.
int	getColourGlyphFormats () const
	Returns an int with bits set indicating the format of colour glyphs contained in the typeface.
EdgeTable *	getEdgeTableForGlyph (TypefaceMetricsKind, int glyphNumber, const AffineTransform &transform, float normalisedHeight)
Rectangle< float >	getGlyphBounds (TypefaceMetricsKind, int glyphNumber) const
	Returns glyph bounds, normalised to a font height of 1.0.
void	getGlyphPositions (TypefaceMetricsKind, const String &text, Array< int > &glyphs, Array< float > &xOffsets, float normalisedHeight=1.0f, float horizontalScale=1.0f)
std::vector< GlyphLayer >	getLayersForGlyph (TypefaceMetricsKind, int glyphNumber, const AffineTransform &) const
	Returns the layers that should be painted in order to display this glyph.
TypefaceMetrics	getMetrics (TypefaceMetricsKind) const
	Returns information about the horizontal metrics of this font.
const String &	getName () const noexcept
	Returns the font family of the typeface.
virtual Native	getNativeDetails () const =0
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.
void	getOutlineForGlyph (TypefaceMetricsKind, int glyphNumber, Path &path) const
	Returns the outline for a glyph.
int	getReferenceCount () const noexcept
	Returns the object's current reference count.
float	getStringWidth (TypefaceMetricsKind, const String &text, float normalisedHeight=1.0f, float horizontalScale=1.0f)
const String &	getStyle () const noexcept
	Returns the font style of the typeface.
std::vector< FontFeatureTag >	getSupportedFeatures () const
	Returns the OpenType features supported by this typeface.
void	incReferenceCount () noexcept
	Increments the object's reference count.

Static Public Member Functions
static void	clearTypefaceCache ()
	Clears any fonts that are currently cached in memory.
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 Typeface::Ptr	findSystemTypeface ()
	Returns the system's default UI font.
static void	scanFolderForFonts (const File &folder)
	On some platforms, this allows a specific path to be scanned.
static void	setTypefaceCacheSize (int numFontsToCache)
	Changes the number of fonts that are cached in memory.

Protected Member Functions
void	resetReferenceCount () noexcept
	Resets the reference count to zero without deleting the object.

Private Attributes
String	name
Atomic< int >	refCount { 0 }
String	style

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

@tags{Graphics}

Member Typedef Documentation

Ptr

using juce::Typeface::Ptr = ReferenceCountedObjectPtr<Typeface>

A handy typedef for a pointer to a typeface.

Member Enumeration Documentation

ColourGlyphFormat

enum juce::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()

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

noexcept

~Typeface()

juce::Typeface::~Typeface ( )

override

Destructor.

Member Function Documentation

applyVerticalHintingTransform()

void juce::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.

clearTypefaceCache()

static void juce::Typeface::clearTypefaceCache ( )

static

Clears any fonts that are currently cached in memory.

createSystemFallback()

virtual Typeface::Ptr juce::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

createSystemTypefaceFor() [1/3]

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

static

Creates a new system typeface.

createSystemTypefaceFor() [2/3]

static Ptr juce::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 juce::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.

decReferenceCount()

void juce::ReferenceCountedObject::decReferenceCount ( )

inlinenoexceptinherited

Decreases the object's reference count.

If the count gets to zero, the object will be deleted.

References jassert.

decReferenceCountWithoutDeleting()

bool juce::ReferenceCountedObject::decReferenceCountWithoutDeleting ( )

inlinenoexceptinherited

Decreases the object's reference count.

If the count gets to zero, the object will not be deleted, but this method will return true, allowing the caller to take care of deletion.

References jassert.

findSystemTypeface()

static Typeface::Ptr juce::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.

getColourGlyphFormats()

int juce::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;

getEdgeTableForGlyph()

EdgeTable * juce::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.

getGlyphBounds()

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

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

getGlyphPositions()

void juce::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!

getLayersForGlyph()

std::vector< GlyphLayer > juce::Typeface::getLayersForGlyph	(	TypefaceMetricsKind	,
		int	glyphNumber,
		const AffineTransform &
	)		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.

getMetrics()

TypefaceMetrics juce::Typeface::getMetrics

(

TypefaceMetricsKind

)

const

Returns information about the horizontal metrics of this font.

getName()

const String & juce::Typeface::getName ( ) const

inlinenoexcept

Returns the font family of the typeface.

See also

Font::getTypefaceName

getNativeDetails()

virtual Native juce::Typeface::getNativeDetails ( ) const

pure virtual

At the moment, this is a way to get at the hb_font_t that backs this typeface. The typeface's hb_font_t has a size of 1 pt (i.e. 1 pt per em). This is only for internal use!

getNominalGlyphForCodepoint()

std::optional< uint32_t > juce::Typeface::getNominalGlyphForCodepoint

(

juce_wchar

)

const

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

getOutlineForGlyph()

void juce::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.

getReferenceCount()

int juce::ReferenceCountedObject::getReferenceCount ( ) const

inlinenoexceptinherited

Returns the object's current reference count.

getStringWidth()

float juce::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!

getStyle()

const String & juce::Typeface::getStyle ( ) const

inlinenoexcept

Returns the font style of the typeface.

See also

Font::getTypefaceStyle

getSupportedFeatures()

std::vector< FontFeatureTag > juce::Typeface::getSupportedFeatures

(

)

const

Returns the OpenType features supported by this typeface.

This method returns a list of all OpenType font features (such as ligatures, small caps, stylistic alternates, etc.) that are available in the current typeface.

See also

FontFeatureTag, FontFeatureSetting, FontOptions, Font

incReferenceCount()

void juce::ReferenceCountedObject::incReferenceCount ( )

inlinenoexceptinherited

Increments the object's reference count.

This is done automatically by the smart pointer, but is public just in case it's needed for nefarious purposes.

resetReferenceCount()

void juce::ReferenceCountedObject::resetReferenceCount ( )

inlineprotectednoexceptinherited

Resets the reference count to zero without deleting the object.

You should probably never need to use this!

scanFolderForFonts()

static void juce::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.

setTypefaceCacheSize()

static void juce::Typeface::setTypefaceCacheSize ( int  numFontsToCache )

static

Changes the number of fonts that are cached in memory.

Member Data Documentation

name

String juce::Typeface::name

private

refCount

Atomic<int> juce::ReferenceCountedObject::refCount { 0 }

privateinherited

style

String juce::Typeface::style

private

---

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

• juce_Typeface.h