juce::Typeface Class Reference

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

---

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

• juce_graphics/fonts/juce_Typeface.h

Inheritance 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
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.
void	getOutlineForGlyph (int glyphNumber, Path &path) const
	Returns the outline for a glyph.
Rectangle< float >	getGlyphBounds (int glyphNumber) const
	Returns glyph bounds, normalised to a point size of 1.0.
std::vector< GlyphLayer >	getLayersForGlyph (int glyphNumber, const AffineTransform &) 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.
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 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.
virtual Typeface::Ptr	cloneWithVariableSettings (Span< const FontVariableSetting > settings) const =0
	Creates and returns a copy of this typeface configured with the specified variable font settings.
std::vector< FontFeatureTag >	getSupportedFeatures () const
	Returns the OpenType features supported by this typeface.
Span< const FontFeatureTag >	getSupportedVariables () const &
	Returns the OpenType variable settings supported by this typeface.
Span< const FontFeatureTag >	getSupportedVariables () const &&=delete
std::optional< float >	getDefaultValueForVariable (FontFeatureTag variableTag) const
	Returns the default value for a specific variable font axis, or std::nullopt if the variable is not supported by this font.
std::optional< Range< float > >	getRangeForVariable (FontFeatureTag variableTag) const
	Returns the valid range for a specific variable font axis, or std::nullopt if the variable is not supported by this font.
Span< const String >	getInstanceNames () const &
	Returns the predefined named instances supported by this variable typeface.
Span< const String >	getInstanceNames () const &&=delete
Span< const FontVariableSetting >	getNamedInstanceConfiguration (StringRef instanceName) const &
	Returns the variable font axis settings for a specific named instance.
Span< const FontVariableSetting >	getNamedInstanceConfiguration (StringRef instanceName) const &&=delete
Span< const FontVariableSetting >	getConfiguredVariables () const &
	Returns the OpenType variable settings this typeface was configured with.
Span< const FontVariableSetting >	getConfiguredVariables () const &&=delete
virtual const Native *	getNativeDetails () const =0
Public Member Functions inherited from juce::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.

Protected Member Functions
	Typeface (const String &, const String &)
Protected Member Functions inherited from juce::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.

Member Typedef Documentation

Ptr

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

A handy typedef for a pointer to a typeface.

Member Enums

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.

Constructors and Destructors

~Typeface()

juce::Typeface::~Typeface ( )

override

Destructor.

Typeface()

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

protected

References JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR, and Typeface().

Referenced by Typeface().

Member Functions

getName()

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

inlinenoexcept

Returns the font family of the typeface.

See also

Font::getTypefaceName

getStyle()

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

inlinenoexcept

Returns the font style of the typeface.

See also

Font::getTypefaceStyle

createSystemTypefaceFor() [1/3]

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

static

Creates a new system typeface.

createSystemTypefaceFor() [2/3]

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]

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.

getMetrics()

TypefaceMetrics juce::Typeface::getMetrics ( TypefaceMetricsKind ) const

nodiscard

Returns information about the horizontal metrics of this font.

getOutlineForGlyph()

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

Returns the outline for a glyph.

The path returned will be normalised to a point size of 1.0.

getGlyphBounds()

Rectangle< float > juce::Typeface::getGlyphBounds

(

int

glyphNumber

)

const

Returns glyph bounds, normalised to a point size of 1.0.

getLayersForGlyph()

std::vector< GlyphLayer > juce::Typeface::getLayersForGlyph	(	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.

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;

setTypefaceCacheSize()

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

static

Changes the number of fonts that are cached in memory.

clearTypefaceCache()

void juce::Typeface::clearTypefaceCache ( )

static

Clears any fonts that are currently cached in memory.

scanFolderForFonts()

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.

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.

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

cloneWithVariableSettings()

virtual Typeface::Ptr juce::Typeface::cloneWithVariableSettings ( Span< const FontVariableSetting > settings ) const

nodiscardpure virtual

Creates and returns a copy of this typeface configured with the specified variable font settings.

Variable fonts (also known as OpenType Font Variations) allow a single font file to contain multiple design variations along one or more axes, such as weight, width, slant, optical size, and custom axes defined by the font designer. This method creates a new typeface instance with the specified axis values applied. Any variable settings applied to the original typeface will be replaced in the returned instance.

This method does not check or cache typefaces, calling this twice with the same settings will return a unique pointer.

Parameters

settings

the variable settings to apply to configure the new typeface instance.

Returns

A unique Typeface::Ptr or nullptr if this typeface is not a variable typeface.

See also

getSupportedVariables, getRangeForVariable, getDefaultValueForVariable

findSystemTypeface()

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.

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

getSupportedVariables() [1/2]

Span< const FontFeatureTag > juce::Typeface::getSupportedVariables ( ) const &

nodiscard

Returns the OpenType variable settings supported by this typeface.

The returned tags are in sorted order.

See also

FontFeatureTag, FontFeatureSetting, cloneWithVariableSettings

Referenced by getSupportedVariables().

getSupportedVariables() [2/2]

Span< const FontFeatureTag > juce::Typeface::getSupportedVariables ( ) const &&

nodiscarddelete

References getSupportedVariables().

getDefaultValueForVariable()

std::optional< float > juce::Typeface::getDefaultValueForVariable ( FontFeatureTag variableTag ) const

nodiscard

Returns the default value for a specific variable font axis, or std::nullopt if the variable is not supported by this font.

Variable fonts define a default value for each axis, which represents the normal or regular style of the typeface. For example, a variable font's 'wght' (weight) axis might have a default value of 400 (Regular weight).

See also

getSupportedVariables, getRangeForVariable, cloneWithVariableSettings

References getDefaultValueForVariable().

Referenced by getDefaultValueForVariable().

getRangeForVariable()

std::optional< Range< float > > juce::Typeface::getRangeForVariable ( FontFeatureTag variableTag ) const

nodiscard

Returns the valid range for a specific variable font axis, or std::nullopt if the variable is not supported by this font.

See also

getSupportedVariables, getDefaultValueForVariable, cloneWithVariableSettings

References getRangeForVariable().

Referenced by getRangeForVariable().

getInstanceNames() [1/2]

Span< const String > juce::Typeface::getInstanceNames ( ) const &

nodiscard

Returns the predefined named instances supported by this variable typeface.

References getInstanceNames().

Referenced by getInstanceNames(), and getInstanceNames().

getInstanceNames() [2/2]

Span< const String > juce::Typeface::getInstanceNames ( ) const &&

nodiscarddelete

References getInstanceNames().

getNamedInstanceConfiguration() [1/2]

Span< const FontVariableSetting > juce::Typeface::getNamedInstanceConfiguration ( StringRef instanceName ) const &

nodiscard

Returns the variable font axis settings for a specific named instance.

Many variable fonts include predefined named instances that represent common design variations, such as "Bold", "Light", "Condensed", etc. Each named instance is a collection of axis values that together define a specific style.

Named instances provide a convenient way to access commonly-used variations without needing to know the specific axis values.

Parameters

instanceName

The name of the instance to query. Use getInstanceNames() to get the available instance names for this typeface.

Returns

A span of FontVariableSetting objects that define the axis values for this named instance. The settings will be sorted by tag. Returns an empty span if the instance name is not found or if this is not a variable font.

See also

getInstanceNames, getSupportedVariables, cloneWithVariableSettings

References getNamedInstanceConfiguration().

Referenced by getNamedInstanceConfiguration(), and getNamedInstanceConfiguration().

getNamedInstanceConfiguration() [2/2]

Span< const FontVariableSetting > juce::Typeface::getNamedInstanceConfiguration ( StringRef instanceName ) const &&

nodiscarddelete

References getNamedInstanceConfiguration().

getConfiguredVariables() [1/2]

Span< const FontVariableSetting > juce::Typeface::getConfiguredVariables ( ) const &

nodiscard

Returns the OpenType variable settings this typeface was configured with.

The returned variables will be sorted by tag.

References getConfiguredVariables().

Referenced by getConfiguredVariables(), and getConfiguredVariables().

getConfiguredVariables() [2/2]

Span< const FontVariableSetting > juce::Typeface::getConfiguredVariables ( ) const &&

nodiscarddelete

References getConfiguredVariables().

getNativeDetails()

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

pure virtual

References getNativeDetails().

Referenced by getNativeDetails().