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

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 StringgetName () const noexcept
 Returns the font family of the typeface.
 
const StringgetStyle () 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.
 
EdgeTablegetEdgeTableForGlyph (TypefaceMetricsKind, int glyphNumber, const AffineTransform &transform, float normalisedHeight)
 
std::vector< GlyphLayergetLayersForGlyph (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.
 
ReferenceCountedObjectoperator= (const ReferenceCountedObject &) noexcept
 Copying from another object does not affect this one's reference-count.
 
ReferenceCountedObjectoperator= (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

A handy typedef for a pointer to a typeface.

Member Enumeration Documentation

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

◆ 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
textthe returned font will normally be capable of displaying the majority of codepoints in this string
languageBCP 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:
linkedin facebook pinterest youtube rss twitter instagram facebook-blank rss-blank linkedin-blank pinterest youtube twitter instagram