QtBase  v6.3.1
Public Types | Public Member Functions | Static Public Member Functions | Friends | Related Functions | List of all members
QRawFont Class Reference

The QRawFont class provides access to a single physical instance of a font. More...

#include <qrawfont.h>

Public Types

enum  AntialiasingType { PixelAntialiasing , SubPixelAntialiasing }
 
enum  LayoutFlag { SeparateAdvances = 0 , KernedAdvances = 1 , UseDesignMetrics = 2 }
 

Public Member Functions

 QRawFont ()
 
 QRawFont (const QString &fileName, qreal pixelSize, QFont::HintingPreference hintingPreference=QFont::PreferDefaultHinting)
 
 QRawFont (const QByteArray &fontData, qreal pixelSize, QFont::HintingPreference hintingPreference=QFont::PreferDefaultHinting)
 
 QRawFont (const QRawFont &other)
 
QRawFontoperator= (const QRawFont &other)
 
 ~QRawFont ()
 
void swap (QRawFont &other) noexcept
 
bool isValid () const
 
bool operator== (const QRawFont &other) const
 
bool operator!= (const QRawFont &other) const
 
QString familyName () const
 
QString styleName () const
 
QFont::Style style () const
 
int weight () const
 
QList< quint32glyphIndexesForString (const QString &text) const
 
QList< QPointFadvancesForGlyphIndexes (const QList< quint32 > &glyphIndexes) const
 
QList< QPointFadvancesForGlyphIndexes (const QList< quint32 > &glyphIndexes, LayoutFlags layoutFlags) const
 
bool glyphIndexesForChars (const QChar *chars, int numChars, quint32 *glyphIndexes, int *numGlyphs) const
 
bool advancesForGlyphIndexes (const quint32 *glyphIndexes, QPointF *advances, int numGlyphs) const
 
bool advancesForGlyphIndexes (const quint32 *glyphIndexes, QPointF *advances, int numGlyphs, LayoutFlags layoutFlags) const
 
QImage alphaMapForGlyph (quint32 glyphIndex, AntialiasingType antialiasingType=SubPixelAntialiasing, const QTransform &transform=QTransform()) const
 
QPainterPath pathForGlyph (quint32 glyphIndex) const
 
QRectF boundingRect (quint32 glyphIndex) const
 
void setPixelSize (qreal pixelSize)
 
qreal pixelSize () const
 
QFont::HintingPreference hintingPreference () const
 
qreal ascent () const
 
qreal capHeight () const
 
qreal descent () const
 
qreal leading () const
 
qreal xHeight () const
 
qreal averageCharWidth () const
 
qreal maxCharWidth () const
 
qreal lineThickness () const
 
qreal underlinePosition () const
 
qreal unitsPerEm () const
 
void loadFromFile (const QString &fileName, qreal pixelSize, QFont::HintingPreference hintingPreference)
 
void loadFromData (const QByteArray &fontData, qreal pixelSize, QFont::HintingPreference hintingPreference)
 
bool supportsCharacter (uint ucs4) const
 
bool supportsCharacter (QChar character) const
 
QList< QFontDatabase::WritingSystemsupportedWritingSystems () const
 
QByteArray fontTable (const char *tagName) const
 

Static Public Member Functions

static QRawFont fromFont (const QFont &font, QFontDatabase::WritingSystem writingSystem=QFontDatabase::Any)
 

Friends

class QRawFontPrivate
 
class QTextLayout
 
class QTextEngine
 

Related Functions

(Note that these are not member functions.)

size_t qHash (const QRawFont &font, size_t seed) noexcept
 

Detailed Description

The QRawFont class provides access to a single physical instance of a font.

Since
4.8 \inmodule QtGui
Note
QRawFont is a low level class. For most purposes QFont is a more appropriate class.

Most commonly, when presenting text in a user interface, the exact fonts used to render the characters is to some extent unknown. This can be the case for several reasons: For instance, the actual, physical fonts present on the target system could be unexpected to the developers, or the text could contain user selected styles, sizes or writing systems that are not supported by font chosen in the code.

Therefore, Qt's QFont class really represents a query for fonts. When text is interpreted, Qt will do its best to match the text to the query, but depending on the support, different fonts can be used behind the scenes.

For most use cases, this is both expected and necessary, as it minimizes the possibility of text in the user interface being undisplayable. In some cases, however, more direct control over the process might be useful. It is for these use cases the QRawFont class exists.

A QRawFont object represents a single, physical instance of a given font in a given pixel size. I.e. in the typical case it represents a set of TrueType or OpenType font tables and uses a user specified pixel size to convert metrics into logical pixel units. It can be used in combination with the QGlyphRun class to draw specific glyph indexes at specific positions, and also have accessors to some relevant data in the physical font.

QRawFont only provides support for the main font technologies: GDI and DirectWrite on Windows platforms, FreeType on Linux platforms and CoreText on \macos. For other font back-ends, the APIs will be disabled.

QRawFont can be constructed in a number of ways: \list

QRawFont is considered local to the thread in which it is constructed (either using a constructor, or by calling loadFromData() or loadFromFile()). The QRawFont cannot be moved to a different thread, but will have to be recreated in the thread in question.

Note
For the requirement of caching glyph indexes and font selections for static text to avoid reshaping and relayouting in the inner loop of an application, a better choice is the QStaticText class, since it optimizes the memory cost of the cache and also provides the possibility of paint engine specific caches for an additional speed-up.

Definition at line 59 of file qrawfont.h.

Member Enumeration Documentation

◆ AntialiasingType

This enum represents the different ways a glyph can be rasterized in the function alphaMapForGlyph().

\value PixelAntialiasing Will rasterize by measuring the coverage of the shape on whole pixels. The returned image contains the alpha values of each pixel based on the coverage of the glyph shape. \value SubPixelAntialiasing Will rasterize by measuring the coverage of each subpixel, returning a separate alpha value for each of the red, green and blue components of each pixel.

Enumerator
PixelAntialiasing 
SubPixelAntialiasing 

Definition at line 62 of file qrawfont.h.

◆ LayoutFlag

Since
5.1

This enum tells the function advancesForGlyphIndexes() how to calculate the advances.

\value SeparateAdvances Will calculate the advance for each glyph separately. \value KernedAdvances Will apply kerning between adjacent glyphs. Note that OpenType GPOS based kerning is currently not supported. \value UseDesignMetrics Use design metrics instead of hinted metrics adjusted to the resolution of the paint device. Can be OR-ed with any of the options above.

Enumerator
SeparateAdvances 
KernedAdvances 
UseDesignMetrics 

Definition at line 67 of file qrawfont.h.

Constructor & Destructor Documentation

◆ QRawFont() [1/4]

QRawFont::QRawFont ( )

Constructs an invalid QRawFont.

Definition at line 148 of file qrawfont.cpp.

◆ QRawFont() [2/4]

QRawFont::QRawFont ( const QString fileName,
qreal  pixelSize,
QFont::HintingPreference  hintingPreference = QFont::PreferDefaultHinting 
)

Constructs a QRawFont representing the font contained in the file referenced by fileName for the size (in pixels) given by pixelSize, and using the hinting preference specified by hintingPreference.

Note
The referenced file must contain a TrueType or OpenType font.

Definition at line 160 of file qrawfont.cpp.

Here is the call graph for this function:

◆ QRawFont() [3/4]

QRawFont::QRawFont ( const QByteArray fontData,
qreal  pixelSize,
QFont::HintingPreference  hintingPreference = QFont::PreferDefaultHinting 
)

Constructs a QRawFont representing the font contained in the supplied fontData for the size (in pixels) given by pixelSize, and using the hinting preference specified by hintingPreference.

Note
The data must contain a TrueType or OpenType font.

Definition at line 175 of file qrawfont.cpp.

Here is the call graph for this function:

◆ QRawFont() [4/4]

QRawFont::QRawFont ( const QRawFont other)

Creates a QRawFont which is a copy of other.

Definition at line 186 of file qrawfont.cpp.

Here is the call graph for this function:

◆ ~QRawFont()

QRawFont::~QRawFont ( )

Destroys the QRawFont

Definition at line 194 of file qrawfont.cpp.

Member Function Documentation

◆ advancesForGlyphIndexes() [1/4]

QList< QPointF > QRawFont::advancesForGlyphIndexes ( const QList< quint32 > &  glyphIndexes) const
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns the QRawFont's advances for each of the glyphIndexes in pixel units. The advances give the distance from the position of a given glyph to where the next glyph should be drawn to make it appear as if the two glyphs are unspaced. The advance of each glyph is calculated separately.

See also
QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance()

Definition at line 171 of file qrawfont.h.

Here is the caller graph for this function:

◆ advancesForGlyphIndexes() [2/4]

QList< QPointF > QRawFont::advancesForGlyphIndexes ( const QList< quint32 > &  glyphIndexes,
LayoutFlags  layoutFlags 
) const
inline
Since
5.1

Returns the QRawFont's advances for each of the glyphIndexes in pixel units. The advances give the distance from the position of a given glyph to where the next glyph should be drawn to make it appear as if the two glyphs are unspaced. How the advances are calculated is controlled by layoutFlags.

Note
When KernedAdvances is requested, this function will apply kerning rules from the TrueType table {KERN}, if this is available in the font. In many modern fonts, kerning is handled through OpenType rules or AAT rules, which requires a full shaping step to be applied. To get the results of fully shaping the text, use \l{QTextLayout}.
See also
QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance(), QTextLayout::glyphRuns()

◆ advancesForGlyphIndexes() [3/4]

bool QRawFont::advancesForGlyphIndexes ( const quint32 glyphIndexes,
QPointF advances,
int  numGlyphs 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns the QRawFont's advances for each of the glyphIndexes in pixel units. The advances give the distance from the position of a given glyph to where the next glyph should be drawn to make it appear as if the two glyphs are unspaced. The glyph indexes are given with the array glyphIndexes while the results are returned through advances, both of them must have numGlyphs elements. The advance of each glyph is calculated separately

See also
QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance()

Definition at line 655 of file qrawfont.cpp.

Here is the call graph for this function:

◆ advancesForGlyphIndexes() [4/4]

bool QRawFont::advancesForGlyphIndexes ( const quint32 glyphIndexes,
QPointF advances,
int  numGlyphs,
LayoutFlags  layoutFlags 
) const
Since
5.1

Returns the QRawFont's advances for each of the glyphIndexes in pixel units. The advances give the distance from the position of a given glyph to where the next glyph should be drawn to make it appear as if the two glyphs are unspaced. The glyph indexes are given with the array glyphIndexes while the results are returned through advances, both of them must have numGlyphs elements. How the advances are calculated is controlled by layoutFlags.

Note
When KernedAdvances is requested, this function will apply kerning rules from the TrueType table {KERN}, if this is available in the font. In many modern fonts, kerning is handled through OpenType rules or AAT rules, which requires a full shaping step to be applied. To get the results of fully shaping the text, use \l{QTextLayout}.
See also
QTextLine::horizontalAdvance(), QFontMetricsF::horizontalAdvance(), QTextLayout::glyphRuns()

Definition at line 619 of file qrawfont.cpp.

Here is the call graph for this function:

◆ alphaMapForGlyph()

QImage QRawFont::alphaMapForGlyph ( quint32  glyphIndex,
AntialiasingType  antialiasingType = SubPixelAntialiasing,
const QTransform transform = QTransform() 
) const

This function returns a rasterized image of the glyph at the given glyphIndex in the underlying font, using the transform specified. If the QRawFont is not valid, this function will return an invalid QImage.

If the font is a color font, then the resulting image will contain the rendered glyph at the current pixel size. In this case, the antialiasingType will be ignored.

Otherwise, if antialiasingType is set to QRawFont::SubPixelAntialiasing, then the resulting image will be in QImage::Format_RGB32 and the RGB values of each pixel will represent the subpixel opacities of the pixel in the rasterization of the glyph. Otherwise, the image will be in the format of QImage::Format_Indexed8 and each pixel will contain the opacity of the pixel in the rasterization.

See also
pathForGlyph(), QPainter::drawGlyphRun()

Definition at line 277 of file qrawfont.cpp.

Here is the call graph for this function:

◆ ascent()

qreal QRawFont::ascent ( ) const

Returns the ascent of this QRawFont in pixel units.

The ascent of a font is the distance from the baseline to the highest position characters extend to. In practice, some font designers break this rule, e.g. when they put more than one accent on top of a character, or to accommodate an unusual character in an exotic language, so it is possible (though rare) that this value will be too small.

See also
QFontMetricsF::ascent()

Definition at line 350 of file qrawfont.cpp.

Here is the call graph for this function:

◆ averageCharWidth()

qreal QRawFont::averageCharWidth ( ) const

Returns the average character width of this QRawFont in pixel units.

See also
QFontMetricsF::averageCharWidth()

Definition at line 416 of file qrawfont.cpp.

Here is the call graph for this function:

◆ boundingRect()

QRectF QRawFont::boundingRect ( quint32  glyphIndex) const

Returns the smallest rectangle containing the glyph with the given glyphIndex.

Since
5.0

Definition at line 820 of file qrawfont.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ capHeight()

qreal QRawFont::capHeight ( ) const

Returns the cap height of this QRawFont in pixel units.

Since
5.8

The cap height of a font is the height of a capital letter above the baseline. It specifically is the height of capital letters that are flat - such as H or I - as opposed to round letters such as O, or pointed letters like A, both of which may display overshoot.

See also
QFontMetricsF::capHeight()

Definition at line 367 of file qrawfont.cpp.

Here is the call graph for this function:

◆ descent()

qreal QRawFont::descent ( ) const

Returns the descent of this QRawFont in pixel units.

The descent is the distance from the base line to the lowest point characters extend to. In practice, some font designers break this rule, e.g. to accommodate an unusual character in an exotic language, so it is possible (though rare) that this value will be too small.

See also
QFontMetricsF::descent()

Definition at line 382 of file qrawfont.cpp.

Here is the call graph for this function:

◆ familyName()

QString QRawFont::familyName ( ) const

Returns the family name of this QRawFont.

Definition at line 477 of file qrawfont.cpp.

Here is the call graph for this function:

◆ fontTable()

QByteArray QRawFont::fontTable ( const char *  tagName) const

Retrieves the sfnt table named tagName from the underlying physical font, or an empty byte array if no such table was found. The returned font table's byte order is Big Endian, like the sfnt format specifies. The tagName must be four characters long and should be formatted in the default endianness of the current platform.

Definition at line 676 of file qrawfont.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ fromFont()

QRawFont QRawFont::fromFont ( const QFont font,
QFontDatabase::WritingSystem  writingSystem = QFontDatabase::Any 
)
static

Fetches the physical representation based on a font query. The physical font returned is the font that will be preferred by Qt in order to display text in the selected writingSystem.

Warning
This function is potentially expensive and should not be called in performance sensitive code.

Definition at line 757 of file qrawfont.cpp.

Here is the call graph for this function:

◆ glyphIndexesForChars()

bool QRawFont::glyphIndexesForChars ( const QChar chars,
int  numChars,
quint32 glyphIndexes,
int *  numGlyphs 
) const

Converts a string of unicode points to glyph indexes using the CMAP table in the underlying font. The function works like glyphIndexesForString() except it take an array (chars), the results will be returned though glyphIndexes array and number of glyphs will be set in numGlyphs. The size of glyphIndexes array must be at least numChars, if that's still not enough, this function will return false, then you can resize glyphIndexes from the size returned in numGlyphs.

See also
glyphIndexesForString(), advancesForGlyphIndexes(), QGlyphRun, QTextLayout::glyphRuns(), QTextFragment::glyphRuns()

Definition at line 554 of file qrawfont.cpp.

◆ glyphIndexesForString()

QList< quint32 > QRawFont::glyphIndexesForString ( const QString text) const

Converts the string of unicode points given by text to glyph indexes using the CMAP table in the underlying font, and returns a list containing the result.

Note that, in cases where there are other tables in the font that affect the shaping of the text, the returned glyph indexes will not correctly represent the rendering of the text. To get the correctly shaped text, you can use QTextLayout to lay out and shape the text, then call QTextLayout::glyphs() to get the set of glyph index list and QRawFont pairs.

See also
advancesForGlyphIndexes(), glyphIndexesForChars(), QGlyphRun, QTextLayout::glyphRuns(), QTextFragment::glyphRuns()

Definition at line 525 of file qrawfont.cpp.

Here is the call graph for this function:

◆ hintingPreference()

QFont::HintingPreference QRawFont::hintingPreference ( ) const

Returns the hinting preference used to construct this QRawFont.

See also
QFont::hintingPreference()

Definition at line 665 of file qrawfont.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ isValid()

bool QRawFont::isValid ( ) const

Returns true if the QRawFont is valid and false otherwise.

Definition at line 218 of file qrawfont.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ leading()

qreal QRawFont::leading ( ) const

Returns the leading of this QRawFont in pixel units.

This is the natural inter-line spacing.

See also
QFontMetricsF::leading()

Definition at line 406 of file qrawfont.cpp.

Here is the call graph for this function:

◆ lineThickness()

qreal QRawFont::lineThickness ( ) const

Returns the thickness for drawing lines (underline, overline, etc.) along with text drawn in this font.

Definition at line 460 of file qrawfont.cpp.

Here is the call graph for this function:

◆ loadFromData()

void QRawFont::loadFromData ( const QByteArray fontData,
qreal  pixelSize,
QFont::HintingPreference  hintingPreference 
)

Replaces the current QRawFont with the font contained in the supplied fontData for the size (in pixels) given by pixelSize, and using the hinting preference specified by hintingPreference.

The fontData must contain a TrueType or OpenType font.

See also
loadFromFile()

Definition at line 250 of file qrawfont.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ loadFromFile()

void QRawFont::loadFromFile ( const QString fileName,
qreal  pixelSize,
QFont::HintingPreference  hintingPreference 
)

Replaces the current QRawFont with the contents of the file referenced by fileName for the size (in pixels) given by pixelSize, and using the hinting preference specified by hintingPreference.

The file must reference a TrueType or OpenType font.

See also
loadFromData()

Definition at line 232 of file qrawfont.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ maxCharWidth()

qreal QRawFont::maxCharWidth ( ) const

Returns the width of the widest character in the font.

See also
QFontMetricsF::maxWidth()

Definition at line 426 of file qrawfont.cpp.

Here is the call graph for this function:

◆ operator!=()

bool QRawFont::operator!= ( const QRawFont other) const
inline

Returns true if this QRawFont is not equal to other. Otherwise, returns false.

Definition at line 91 of file qrawfont.h.

Here is the call graph for this function:

◆ operator=()

QRawFont & QRawFont::operator= ( const QRawFont other)

Assigns other to this QRawFont.

Definition at line 201 of file qrawfont.cpp.

Here is the call graph for this function:

◆ operator==()

bool QRawFont::operator== ( const QRawFont other) const

Returns true if this QRawFont is equal to other. Otherwise, returns false.

Definition at line 314 of file qrawfont.cpp.

Here is the call graph for this function:

◆ pathForGlyph()

QPainterPath QRawFont::pathForGlyph ( quint32  glyphIndex) const

This function returns the shape of the glyph at a given glyphIndex in the underlying font if the QRawFont is valid. Otherwise, it returns an empty QPainterPath.

The returned glyph will always be unhinted.

See also
alphaMapForGlyph(), QPainterPath::addText()

Definition at line 300 of file qrawfont.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ pixelSize()

qreal QRawFont::pixelSize ( ) const

Returns the pixel size set for this QRawFont. The pixel size affects how glyphs are rasterized, the size of glyphs returned by pathForGlyph(), and is used to convert internal metrics from design units to logical pixel units.

See also
setPixelSize()

Definition at line 438 of file qrawfont.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ setPixelSize()

void QRawFont::setPixelSize ( qreal  pixelSize)

Sets the pixel size with which this font should be rendered to pixelSize.

Definition at line 794 of file qrawfont.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ style()

QFont::Style QRawFont::style ( ) const

Returns the style of this QRawFont.

See also
QFont::style()

Definition at line 497 of file qrawfont.cpp.

Here is the call graph for this function:

◆ styleName()

QString QRawFont::styleName ( ) const

Returns the style name of this QRawFont.

See also
QFont::styleName()

Definition at line 487 of file qrawfont.cpp.

Here is the call graph for this function:

◆ supportedWritingSystems()

QList< QFontDatabase::WritingSystem > QRawFont::supportedWritingSystems ( ) const

Returns a list of writing systems supported by the font according to designer supplied information in the font file. Please note that this does not guarantee support for a specific unicode point in the font. You can use the supportsCharacter() to check support for a single, specific character.

Note
The list is determined based on the unicode ranges and codepage ranges set in the font's OS/2 table and requires such a table to be present in the underlying font file.
See also
supportsCharacter()

Definition at line 695 of file qrawfont.cpp.

Here is the call graph for this function:

◆ supportsCharacter() [1/2]

bool QRawFont::supportsCharacter ( QChar  character) const

Returns true if the font has a glyph that corresponds to the given character.

See also
supportedWritingSystems()

Definition at line 730 of file qrawfont.cpp.

Here is the call graph for this function:

◆ supportsCharacter() [2/2]

bool QRawFont::supportsCharacter ( uint  ucs4) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Returns true if the font has a glyph that corresponds to the UCS-4 encoded character ucs4.

See also
supportedWritingSystems()

Definition at line 742 of file qrawfont.cpp.

Here is the call graph for this function:
Here is the caller graph for this function:

◆ swap()

void QRawFont::swap ( QRawFont other)
inlinenoexcept
Since
5.0

Swaps this raw font with other. This function is very fast and never fails.

Definition at line 86 of file qrawfont.h.

Here is the call graph for this function:

◆ underlinePosition()

qreal QRawFont::underlinePosition ( ) const

Returns the position from baseline for drawing underlines below the text rendered with this font.

Definition at line 469 of file qrawfont.cpp.

Here is the call graph for this function:

◆ unitsPerEm()

qreal QRawFont::unitsPerEm ( ) const

Returns the number of design units define the width and height of the em square for this QRawFont. This value is used together with the pixel size when converting design metrics to pixel units, as the internal metrics are specified in design units and the pixel size gives the size of 1 em in pixels.

See also
pixelSize(), setPixelSize()

Definition at line 451 of file qrawfont.cpp.

Here is the call graph for this function:

◆ weight()

int QRawFont::weight ( ) const

Returns the weight of this QRawFont.

See also
QFont::weight()

Definition at line 507 of file qrawfont.cpp.

Here is the call graph for this function:

◆ xHeight()

qreal QRawFont::xHeight ( ) const

Returns the xHeight of this QRawFont in pixel units.

This is often but not always the same as the height of the character 'x'.

See also
QFontMetricsF::xHeight()

Definition at line 394 of file qrawfont.cpp.

Here is the call graph for this function:

Friends And Related Function Documentation

◆ qHash()

size_t qHash ( const QRawFont font,
size_t  seed 
)
related

Returns the hash value for font. If specified, seed is used to initialize the hash.

Since
5.8

Definition at line 326 of file qrawfont.cpp.

◆ QRawFontPrivate

friend class QRawFontPrivate
friend

Definition at line 149 of file qrawfont.h.

◆ QTextEngine

friend class QTextEngine
friend

Definition at line 151 of file qrawfont.h.

◆ QTextLayout

friend class QTextLayout
friend

Definition at line 150 of file qrawfont.h.


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