font QML Value Type

A font configuration. More...

• font is part of Qt Quick Ultralite QML Basic Types.

Properties

• bold : bool
• family : string
• italic : bool
• letterSpacing : int (since Qt Quick Ultralite 2.11)
• pixelSize : int
• pointSize : int
• quality : enumeration (since Qt Quick Ultralite 1.9)
• unicodeCoverage : var (since Qt Quick Ultralite 1.1)
• unicodeCoverageIncludeUpperCase : bool (since Qt Quick Ultralite 2.9)
• weight : enumeration

Detailed Description

A font type describing a font configuration. The available properties are:

• string font.family
• bool font.bold
• bool font.italic
• int font.pointSize
• int font.pixelSize
• var font.unicodeCoverage
• bool font.unicodeCoverageIncludeUpperCase
• enumeration font.weight
• enumeration font.quality
• int font.letterSpacing

When using the Monotype Spark font engine, the font configuration uses the font class mapping rules.

See also Text Rendering and Fonts, Qt.font().

This basic type is provided by the QtQuick import.

Usage example

Text {
    font.family: "Helvetica";
    font.pixelSize: 24;
    font.bold: true
}

Constant font configurations

A constant font configuration refers to a font setup where all subproperties can be resolved to constant values by qmltocpp. The letterSpacing property does not influence whether a font configuration is considered constant. Because of this, it is allowed to use dynamic values (bindings) for letterSpacing even when using the static font engine or StaticText items.

In the following example, all font properties are resolved to constant values by qmltocpp. Note that the bindings reference readonly properties.

readonly property int titlePixelSize: 40
readonly property font myFontConfig: Qt.font({ pixelSize: titlePixelSize })

Text {
    text: "hello world"
    font.pixelSize: titlePixelSize
}

Text {
    text: "hello world 2"
    font: myFontConfig
}

Text {
    text: "hello world 3"
    font.italic: true
}

Qt Quick Ultralite or font engine specific details

Bindings

Starting with version 1.7, it is possible to define bindings on font subproperties with the Spark font engine.

Text {
    text: "Hello world from Qt"
    font.italic: italicSwitch.checked
    font.pixelSize: pixelSizeSlider.value
}

See font bindings example for more details on how binding evaluation map to a font class name in a fontmap file.

Both font engines permit bindings on the font property. For example:

readonly property font fontConf1: Qt.font({ pixelSize: 30 })
readonly property font fontConf2: Qt.font({ pixelSize: 50 })

Text {
    // Binding on font property.
    font: someCondition ? fontConf1 : fontConf2
    text: "some text"
}

This allows runtime font changes with the static engine, albeit without the fine-grained control on font subproperty bindings that is possible with the Spark engine.

Optimizations

The memory usage can be optimized by sharing a font configuration (Text.font) where texts use the same style. See also Qt.font().

Text {
    // Sharing the font configuration with other Text element through a binding.
    font: myText.font
    text: "some text"
}

Constant font configurations are automatically shared in the emitted C++ code.

Assigning

The font basic type in Qt Quick Ultralite is a constant value, therefore assigning to font subproperties is not supported.

// error: Assigning to properties of 'font' is not supported, use bindings
onClicked: myText.font.italic = false

As suggested by the error message, one can use a binding to achieve the same results.

property bool isItalic: true

Text {
    text: "hello world"
    font.italic: isItalic
}

MouseArea {
    anchors.fill: parent
    onClicked: isItalic = false
}

Reading

Reading font subproperties is not implemented.

Property Documentation

bold : bool

Sets whether the font weight is bold.

family : string

Sets the family name of the font. The default font family is set by MCU.Config.defaultFontFamily.

Static font engine

The family name is case insensitive and might include a foundry name, such as "Helvetica [Cronyx]" for example. If the family is available from more than one foundry and the foundry isn't specified, an arbitrary foundry is chosen. If the family isn't available, a family is set using the font matching algorithm.

Spark font engine

The value of MCU.Config.defaultFontFamily QmlProject property is read when using the Fontmap file format. Otherwise, only the font.pixelSize font configuration is used.

italic : bool

Sets whether the font has an italic style.

letterSpacing : int [since Qt Quick Ultralite 2.11]

Sets the letter spacing for the text layout.

Letter spacing changes the default spacing between individual letters in the text layout. A positive value increases the letter spacing by the corresponding pixels; a negative value decreases the spacing.

This property was introduced in Qt Quick Ultralite 2.11.

pixelSize : int

Sets the font size in pixels.

pointSize : int

The pointSize property does not respect screen DPI as documented on the known issues or limitations page. Currently the set value is scaled to 1.5 times. Use font.pixelSize instead.

quality : enumeration [since Qt Quick Ultralite 1.9]

The rendering quality of a font.

The font.quality property allows more fine-grained optimization, by providing hints to render low-quality glyphs.

The requested quality must be one of the predefined values:

Example:

Text {
    font: Qt.font({ quality: Font.QualityVeryHigh })
    text: "..."
}

Optimization

By default, the font compiler generates glyphs for all used characters in all used font configurations. This might result in redundant glyphs being generated. For example:

Text {
    font: Qt.font({ quality: Font.QualityVeryHigh })
    text: "a"
}
Text {
    font: Qt.font({ quality: Font.QualityVeryLow })
    text: "b"
}

In the earlier example, glyphs for the "ab" characters are generated twice, one for VeryHigh and the other for VeryLow quality. This allows binding text property between existing Text items. You can disable this behavior by setting the MCU.Config.autoGenerateGlyphs to OFF.

To set the default font quality for an application, see the MCU.Config.defaultFontQuality QmlProject property.

This property was introduced in Qt Quick Ultralite 1.9.

unicodeCoverage : var [since Qt Quick Ultralite 1.1]

This property is supported in Qt.font() context only.

Use this property in combination with MCU.Config.autoGenerateGlyphs to optimize ROM usage.

The array may contain:

• String literals containing glyphs to add, like "\u1722".
• Unicode block enum values, like Font.UnicodeBlock_Kannada. For the list of supported enum values, see unicode block names.
• A list of pairs indicating a unicode range, like [0x600, 0x61F].

Example:

Text {
    font: Qt.font({
        family: "DejaVu Sans",
        unicodeCoverage: [Font.UnicodeBlock_Kannada, "ᜠᜡ\u1722", [0x600, 0x61F]]
    })
    text: CppSingleton.retrieveText()
}

In the earlier example, the glyphs for many extra unicode codepoints are prerendered for the font configuration used by the Text item. This information is compiled into the application binary. The codepoints in the "Kannada" Unicode block, the codepoint range 0x600 to 0x61F (inclusive), and the individual characters ᜠ, ᜡ, and U+1722 will be included.

Only a single glyph is generated per codepoint, even if the codepoint is contained in several ranges, blocks, strings or equivalent font configurations in other files or modules used by the application. You can repeat the same coverage in various places if that helps the code organization and encapsulation. The tooling excludes the duplicate glyphs.

This property was introduced in Qt Quick Ultralite 1.1.

unicodeCoverageIncludeUpperCase : bool [since Qt Quick Ultralite 2.9]

This property is supported in Qt.font() context only.

Use this property in combination with font.unicodeCoverage to include uppercase variants of codepoints listed in font.unicodeCoverage. If a codepoint does not have an uppercase variant in Unicode, only the lowercase glyph is bundled with the application for that specific codepoint. This function is convenient for situations where an application uses JS string.toUpperCase(). The algorithm that prepares the bundled glyphs uses toUpperCase() to determine what to bundle. The toUpperCase() algorithm doesn't work as expected in a few situations, which you can avoid by using unicodeCoverageIncludeUpperCase to ensure reliable results.

Default value is false.

This property was introduced in Qt Quick Ultralite 2.9.

weight : enumeration

Sets the font's weight. The following enums are supported:

Available under certain Qt licenses.
Find out more.