Loading...
Searching...
No Matches
juce::Typeface Class Referenceabstract

## 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.
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 &) 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 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.
std::vector< FontFeatureTag > | getSupportedFeatures () const
| Returns the OpenType features supported by this typeface.
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 Typeface().

Referenced by Typeface().

## Member Functions

## getName()

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

inline noexcept

Returns the font family of the typeface.

See also
  Font::getTypefaceName

## getStyle()

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

inline noexcept

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.

## 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!

## 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!

## 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.

## getGlyphBounds()

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

Returns glyph bounds, normalised to a font height of 1.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.

## 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.

## 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;
juce::Typeface::colourGlyphFormatBitmap
@ colourGlyphFormatBitmap
The typeface includes glyphs represented as bitmaps (normally PNGs).
Definition juce_Typeface.h:271
juce::Typeface::colourGlyphFormatCOLRv0
@ colourGlyphFormatCOLRv0
The typeface uses the COLRv0 format, with support for flat colours.
Definition juce_Typeface.h:273
juce::Typeface::colourGlyphFormatSvg
@ colourGlyphFormatSvg
The typeface includes glyphs represented as SVGs.
Definition juce_Typeface.h:272

## 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.

## 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.

## 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

## 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, FontOptions, Font

## getNativeDetails()

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

pure virtual

### Purchase

Get JUCE

### Discover

What's New in JUCE Features

### Learn

Documentaion Tutorials Made with JUCE Resources

### Support

JUCE Forum Newsletter Archive

### About

Contact Us JUCE Legal JUCE Licensing FAQ

### Events

Audio Developer Conference
© Raw Material Software Limited