Contents

• Public Types
• Public Functions
• Static Public Members
• Detailed Description

Detailed Description

TheQRawFont class provides access to a single physical instance of a font.

Note:QRawFont is a low level class. For most purposesQFont 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'sQFont 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 theQRawFont class exists.

AQRawFont 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 theQGlyphRun 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 Symbian and Linux platforms and CoreText on Mac OS X. For other font back-ends, the APIs will be disabled.

QRawFont can be constructed in a number of ways:

• It can be constructed by calling QTextLayout::glyphs() or QTextFragment::glyphs(). The returned QGlyphs objects will containQRawFont objects which represent the actual fonts used to render each portion of the text.
• It can be constructed by passing aQFont object toQRawFont::fromFont(). The function will return aQRawFont object representing the font that will be selected as response to theQFont query and the selected writing system.
• It can be constructed by passing a file name orQByteArray directly to theQRawFont constructor, or by callingloadFromFile() orloadFromData(). In this case, the font will not be registered inQFontDatabase, and it will not be available as part of regular font selection.

QRawFont is considered local to the thread in which it is constructed (either using a constructor, or by callingloadFromData() orloadFromFile()). TheQRawFont 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 theQStaticText 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.

Member Type Documentation

enum QRawFont::AntialiasingType

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

Member Function Documentation

QRawFont::QRawFont()

Constructs an invalidQRawFont.

QRawFont::QRawFont(constQString & fileName,qreal pixelSize,QFont::HintingPreference hintingPreference = QFont::PreferDefaultHinting)

Constructs aQRawFont representing the font contained in the file referenced byfileName for the size (in pixels) given bypixelSize, and using the hinting preference specified byhintingPreference.

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

QRawFont::QRawFont(constQByteArray & fontData,qreal pixelSize,QFont::HintingPreference hintingPreference = QFont::PreferDefaultHinting)

Constructs aQRawFont representing the font contained in the suppliedfontData for the size (in pixels) given bypixelSize, and using the hinting preference specified byhintingPreference.

Note:The data must contain a TrueType or OpenType font.

QRawFont::QRawFont(constQRawFont & other)

Creates aQRawFont which is a copy ofother.

QRawFont::~QRawFont()

Destroys theQRawFont

QVector<QPointF> QRawFont::advancesForGlyphIndexes(constQVector<quint32> & glyphIndexes) const

Returns theQRawFont's advances for each of theglyphIndexes 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.

See alsoQTextLine::horizontalAdvance() andQFontMetricsF::width().

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

Returns theQRawFont's advances for each of theglyphIndexes 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 arrayglyphIndexes while the results are returned throughadvances, both of them must havenumGlyphs elements.

See alsoQTextLine::horizontalAdvance() andQFontMetricsF::width().

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

This function returns a rasterized image of the glyph at the givenglyphIndex in the underlying font, using thetransform specified. If theQRawFont is not valid, this function will return an invalidQImage.

IfantialiasingType is set toQRawFont::SubPixelAntialiasing, then the resulting image will be inQImage::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 ofQImage::Format_Indexed8 and each pixel will contain the opacity of the pixel in the rasterization.

See alsopathForGlyph() andQPainter::drawGlyphRun().

qreal QRawFont::ascent() const

Returns the ascent of thisQRawFont in pixel units.

See alsoQFontMetricsF::ascent().

qreal QRawFont::averageCharWidth() const

Returns the average character width of thisQRawFont in pixel units.

See alsoQFontMetricsF::averageCharWidth().

qreal QRawFont::descent() const

Returns the descent of thisQRawFont in pixel units.

See alsoQFontMetricsF::descent().

QString QRawFont::familyName() const

Returns the family name of thisQRawFont.

QByteArray QRawFont::fontTable(constchar * tagName) const

Retrieves the sfnt table namedtagName 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. ThetagName must be four characters long and should be formatted in the default endianness of the current platform.

[static]QRawFont QRawFont::fromFont(constQFont & font,QFontDatabase::WritingSystem writingSystem = QFontDatabase::Any)

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

bool QRawFont::glyphIndexesForChars(constQChar * 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 likeglyphIndexesForString() except it take an array (chars), the results will be returned thoughglyphIndexes array and number of glyphs will be set innumGlyphs. The size ofglyphIndexes array must be at leastnumChars, if that's still not enough, this function will return false, then you can resizeglyphIndexes from the size returned innumGlyphs.

See alsoglyphIndexesForString(),advancesForGlyphIndexes(),QGlyphRun,QTextLayout::glyphRuns(), andQTextFragment::glyphRuns().

QVector<quint32> QRawFont::glyphIndexesForString(constQString & text) const

Converts the string of unicode points given bytext to glyph indexes using the CMAP table in the underlying font, and returns a vector 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 useQTextLayout to lay out and shape the text, then call QTextLayout::glyphs() to get the set of glyph index list andQRawFont pairs.

See alsoadvancesForGlyphIndexes(),glyphIndexesForChars(),QGlyphRun,QTextLayout::glyphRuns(), andQTextFragment::glyphRuns().

QFont::HintingPreference QRawFont::hintingPreference() const

Returns the hinting preference used to construct thisQRawFont.

See alsoQFont::hintingPreference().

bool QRawFont::isValid() const

Returns true if theQRawFont is valid and false otherwise.

qreal QRawFont::leading() const

Returns the leading of thisQRawFont in pixel units.

See alsoQFontMetricsF::leading().

void QRawFont::loadFromData(constQByteArray & fontData,qreal pixelSize,QFont::HintingPreference hintingPreference)

Replaces the currentQRawFont with the font contained in the suppliedfontData for the size (in pixels) given bypixelSize, and using the hinting preference specified byhintingPreference.

ThefontData must contain a TrueType or OpenType font.

See alsoloadFromFile().

void QRawFont::loadFromFile(constQString & fileName,qreal pixelSize,QFont::HintingPreference hintingPreference)

Replaces the currentQRawFont with the contents of the file referenced byfileName for the size (in pixels) given bypixelSize, and using the hinting preference specified byhintingPreference.

The file must reference a TrueType or OpenType font.

See alsoloadFromData().

qreal QRawFont::maxCharWidth() const

Returns the width of the widest character in the font.

See alsoQFontMetricsF::maxWidth().

QPainterPath QRawFont::pathForGlyph(quint32 glyphIndex) const

This function returns the shape of the glyph at a givenglyphIndex in the underlying font if theQRawFont is valid. Otherwise, it returns an emptyQPainterPath.

The returned glyph will always be unhinted.

See alsoalphaMapForGlyph() andQPainterPath::addText().

qreal QRawFont::pixelSize() const

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

See alsosetPixelSize().

void QRawFont::setPixelSize(qreal pixelSize)

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

See alsopixelSize().

QFont::Style QRawFont::style() const

Returns the style of thisQRawFont.

See alsoQFont::style().

QString QRawFont::styleName() const

Returns the style name of thisQRawFont.

See alsoQFont::styleName().

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 thesupportsCharacter() 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 alsosupportsCharacter().

bool QRawFont::supportsCharacter(QChar character) const

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

See alsosupportedWritingSystems().

bool QRawFont::supportsCharacter(quint32 ucs4) const

This is an overloaded function.

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

See alsosupportedWritingSystems().

qreal QRawFont::unitsPerEm() const

Returns the number of design units define the width and height of the em square for thisQRawFont. 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 alsopixelSize() andsetPixelSize().

int QRawFont::weight() const

Returns the weight of thisQRawFont.

See alsoQFont::weight().

qreal QRawFont::xHeight() const

Returns the xHeight of thisQRawFont in pixel units.

See alsoQFontMetricsF::xHeight().

bool QRawFont::operator!=(constQRawFont & other) const

Returns true if thisQRawFont is not equal toother. Otherwise, returns false.

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

Assignsother to thisQRawFont.

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

Returns true if thisQRawFont is equal toother. Otherwise, returns false.