QFont Class Reference


The QFont class specifies a font used for drawing text. More...

#include <qfont.h>

List of all member functions.

Public Members

Static Public Members

Protected Members

Related Functions

(Note that these are not member functions.)

Detailed Description

The QFont class specifies a font used for drawing text.

A QFont has a series of attributes that can be set to specify an abstract font. When actual drawing of text is done Qt will select a font in the underlying window system that matches the abstract font as close as possible. The most important attributes are family, point size, weight and italic.

One of the QFont constructors take exactly these attributes as arguments:

    void MyWidget::paintEvent( QPaintEvent * )
    {
        QPainter p;
        p.begin( this );
                                        // times, 12pt, normal
        p.setFont( QFont( "times" ) );
        p.drawText( 10, 20, "Text1" );
                                        // helvetica, 18pt, normal
        p.setFont( QFont( "helvetica", 18 ) );
        p.drawText( 10, 120, "Text2" );
                                        // courier, 24pt, bold
        p.setFont( QFont( "courier", 24, QFont::Bold ) );
        p.drawText( 10, 220, "Text3" );
                                        // lucida, 36pt, bold, italic
        p.setFont( QFont( "lucida", 36, QFont::Bold, TRUE ) );
        p.drawText( 10, 320, "Text4" );

        p.end();
    }

In general font handling and loading are costly operations that put a heavy load on the window system, this is especially true for X11. The QFont class has an internal sharing and reference count mechanism in order to speed up copies so QFonts may be passed around as arguments, and it has a lazy loading mechanism and does not load a font until it really has to. It also caches previously loaded fonts and under X it caches previously matched font attribute combinations.

Note that the functions returning attribute values in QFont return the values previously set, not the attributes of the actual window system font used for drawing. To get information about the actual font use QFontInfo.

To get font size information use the class QFontMetrics.

QFont objects make use of implicit sharing.

See also: QApplication::setFont(), QWidget::setFont() and QPainter::setFont().

Examples: xshape/xshape.cpp picture/makepic.cpp drawdemo/drawdemo.cpp widgets/widgets.cpp


Member Function Documentation

QFont::QFont ( const QFont &font)

Constructs a font that is a copy of font.

QFont::QFont ( const char *family, int pointSize = 12, int weight = Normal, bool italic = FALSE)

Constructs a font object with the specified family, pointSize, weight and italic settings. If pointSize is less than or equal to 0 it is set to 1.

See also: setFamily(), setPointSize(), setWeight() and setItalic().

QFont::QFont ()

Constructs a font object that refers to the default font.

QFont::~QFont () [virtual]

Destroys the font object.

bool QFont::bold () const

Returns TRUE if weight() is a value greater than QFont::Normal, otherwise FALSE.

See also: weight(), setBold() and QFontInfo::bold().

void QFont::cacheStatistics () [static]

Internal function that dumps font cache statistics.

QFont::CharSet QFont::charSet() const

Returns the character set by setCharSet().

Use QFontInfo to find the CharSet of the window system font actually used.

See also: setCharSet().

void QFont::cleanup () [static]

Internal function that cleans up the font system.

int QFont::deciPointSize () const [protected]

Returns the point size in 1/10ths of a point.

See also: pointSize().

QString QFont::defaultFamily () const [protected]

Returns the family name that corresponds to the current style hint.

const QFont & QFont::defaultFont () [static]

Returns the system default font.

bool QFont::dirty () const [protected]

Returns TRUE if the font attributes have been changed and the font has to be (re)loaded, or FALSE if no changes have been made.

bool QFont::exactMatch () const

Returns TRUE if a window system font exactly matching the settings of this font is available.

See also: QFontInfo and font matching

const char * QFont::family () const

Returns the family name set by setFamily().

Use QFontInfo to find the family name of the window system font actually used.

Example:

    QFont     font( "Nairobi" );
    QFontInfo info( font );
    debug( "Font family requested is    : \"%s\"", font.family() );
    debug( "Font family actually used is: \"%s\"", info.family() );

See also: setFamily() and substitute().

bool QFont::fixedPitch () const

Returns the value set by setFixedPitch().

Use QFontInfo to find the fixed pitch value of the window system font actually used.

See also: setFixedPitch() and QFontInfo::fixedPitch().

HANDLE QFont::handle ( HANDLE=0) const

Returns a window system handle to the font.

Use of this function is discouraged at present.

void QFont::initialize () [static]

Internal function that initializes the font system.

void QFont::insertSubstitution ( const char *familyName, const char *replacementName) [static]

Inserts a new font family name substitution in the family substitution table.

If familyName already exists in the substitution table, it will be replaced with this new substitution.

See also: removeSubstitution(), listSubstitutions() and substitute().

bool QFont::italic () const

Returns the value set by setItalic().

Use QFontInfo to find the italic value of the window system font actually used.

See also: setItalic().

QString QFont::lastResortFamily () const [protected]

Returns a last resort family name for the font matching algorithm.

See also: lastResortFont().

QString QFont::lastResortFont () const [protected]

Returns a last resort raw font name for the font matching algorithm.

This is used if not even the last resort family is available.

See also: lastResortFamily().

void QFont::listSubstitutions ( QStrList *list) [static]

Returns a sorted list of substituted family names in list.

See also: insertSubstitution(), removeSubstitution() and substitute().

bool QFont::operator!= ( const QFont &f) const

Returns TRUE if the this font is different from f, or FALSE if they are equal.

Two QFonts are different if their font attributes are different. If raw mode is enabled for both fonts, then only the family fields are compared.

See also: operator==().

QFont & QFont::operator= ( const QFont &font)

Assigns font to this font and returns a reference to this font.

bool QFont::operator== ( const QFont &f) const

Returns TRUE if the this font is equal to f, or FALSE if they are different.

Two QFonts are equal if their font attributes are equal. If raw mode is enabled for both fonts, then only the family fields are compared.

See also: operator!=().

int QFont::pointSize () const

Returns the point size set by setPointSize().

Use QFontInfo to find the point size of the window system font actually used.

Example of use:

    QFont     font( "helvetica" );
    QFontInfo info( font );
    font.setPointSize( 53 );
    debug( "Font size requested is    : %d", font.pointSize() );
    debug( "Font size actually used is: %d", info.pointSize() );

See also: setPointSize().

bool QFont::rawMode () const

Returns the value set by setRawMode.

See also: setRawMode().

void QFont::removeSubstitution ( const char *familyName) [static]

Removes a font family name substitution from the family substitution table.

See also: insertSubstitution(), listSubstitutions() and substitute().

void QFont::setBold ( bool enable)

Sets the weight to QFont::Bold if enable is TRUE, or to QFont::Normal if enable is FALSE.

Use setWeight() to set the weight to other values.

See also: bold() and setWeight().

void QFont::setCharSet ( CharSet charset)

Sets the character set (e.g. Latin1).

If the character set is not available another will be used, for most non-trivial applications you will probably not want this to happen since it can totally obscure the text shown to the user when the font is used. This is why the font matching algorithm gives high priority to finding the correct character set.

To ensure that the character set is correct you can use the QFontInfo class.

Example:

    QFont     font( "times", 14 );           // default character set is Latin1
    QFontInfo info( font );
    if ( info.charSet() != Latin1 )          // check actual font
        fatal( "Cannot find a Latin 1 Times font" );

See also: charSet(), QFontInfo and font matching

void QFont::setDefaultFont ( const QFont &f) [static]

Sets the system default font.

void QFont::setFamily ( const char *family)

Sets the family name of the font (e.g. "Helvetica" or "times").

The family name is case insensitive.

If the family is not available a default family will be used instead.

See also: family(), setStyleHint(), QFontInfo and font matching

void QFont::setFixedPitch ( bool enable)

Sets fixed pitch on or off. If the mode selected is not available the other will be used. A fixed pitch font is a font that has constant character pixel width.

See also: fixedPitch(), QFontInfo and font matching

void QFont::setItalic ( bool enable)

Sets italic on or off.

If the mode selected is not available the other will be used.

See also: italic(), QFontInfo and font matching

void QFont::setPointSize ( int pointSize)

Sets the point size (e.g. 12 or 18). If the point size is not available the closest available will be used.

Setting of point sizes less than or equal to 0 will be ignored.

See also: pointSize(), QFontInfo and font matching

void QFont::setRawMode ( bool enable)

Turns raw mode on if enable is TRUE, or turns it off if enable is FALSE.

Calling this function only has effect under X windows. If raw mode is enabled, Qt will search for an X font with a complete font name matching the family name, ignoring all other values set for the QFont. If the font name matches several fonts, Qt will use the first font returned by X. QFontInfo cannot be used to fetch information about a QFont using raw mode (it will return the values set in the QFont for all parameters, including the family name).

Example:

    #if defined(_WS_X11_)
        QFont font( "-*-fixed-*-*-*-*-*-140-75-75-c-*-iso8859-1" );
        font.setRawMode( TRUE );
        if ( !font.exactMatch() )
            debug( "Sorry, could not find the X specific font" );
    #endif

Warning: Do not use raw mode unless you really need it!

See also: rawMode().

void QFont::setStrikeOut ( bool enable)

Sets strike out on or off.

If the mode selected is not available the other will be used.

See also: strikeOut(), QFontInfo and font matching

void QFont::setStyleHint ( StyleHint hint)

Sets the style hint.

The style hint is used by the font matching algorithm when a selected font family cannot be found and is used to find an appropriate default family.

The style hint has a default value of AnyStyle which leaves the task of finding a good default family to the font matching algorithm.

In this example (which is a complete program) the push button will display its text label with the Bavaria font family if this family is available, if not it will display its text label with the Times font family:

    #include <qapp.h>
    #include <qpushbt.h>
    #include <qfont.h>

    int main( int argc, char **argv )
    {
        QApplication app( argc, argv );
        QPushButton  push("Push me");

        QFont font( "Bavaria", 18 );        // preferrred family is Bavaria
        font.setStyleHint( QFont::Times );  // use Times if Bavaria isn't here

        push.setFont( font );
        return app.exec( &push );
    }

See also: styleHint(), QFontInfo and font matching

void QFont::setUnderline ( bool enable)

Sets underline on or off.

If the mode selected is not available the other will be used.

See also: underline(), QFontInfo and font matching.

void QFont::setWeight ( int weight)

Sets the weight (or boldness).

The enum Weight contains the predefined font weights.

Strictly speaking you can use all values in the range [0,99] (where 0 is ultralight and 99 is extremely black), but there is such a thing as asking too much of the underlying window system.

Example:

    QFont font( "courier" );
    font.setWeight( QFont::Bold );

If the specified weight is not available the closest available will be used. Use QFontInfo to check the actual weight.

If you try to set the weight to a value outside the legal range, setWeight() ignores you.

See also: weight(), QFontInfo and font matching

bool QFont::strikeOut () const

Returns the value set by setStrikeOut().

Use QFontInfo to find the strike out value of the window system font actually used.

See also: setStrikeOut() and QFontInfo::strikeOut().

QFont::StyleHint QFont::styleHint() const

Returns the StyleHint set by setStyleHint().

See also: setStyleHint() and QFontInfo::styleHint().

const char * QFont::substitute ( const char *familyName) [static]

Returns the font family name to be used whenever familyName is specified, and not found by the font matching algorithm. The lookup is case insensitive.

If there is no substitution for familyName, then familyName is returned.

Example:

    QFont::insertSubstitution( "NewYork", "London" );
    QFont::insertSubstitution( "Paris",   "Texas" );

    QFont::substitute( "NewYork" );     // returns "London"
    QFont::substitute( "PARIS" );       // returns "Texas"
    QFont::substitute( "Rome" );        // returns "Rome"

    QFont::removeSubstitution( "newyork" );
    QFont::substitute( "NewYork" );     // returns "NewYork"

See also: setFamily(), insertSubstitution() and removeSubstitution().

bool QFont::underline () const

Returns the value set by setUnderline().

Use QFontInfo to find the underline value of the window system font actually used.

See also: setUnderline() and QFontInfo::underline().

int QFont::weight () const

Returns the weight set by setWeight().

Use QFontInfo to find the weight of the window system font actually used.

See also: setWeight() and QFontInfo.


Related Functions

QDataStream & operator<< ( QDataStream &s, const QFont &f)

Writes a font to the stream.

QDataStream & operator>> ( QDataStream &s, QFont &f)

Reads a font from the stream.


This file is part of the Qt toolkit, copyright © 1995-96 Troll Tech, all rights reserved.

It was generated from the following files:


Generated at 16:51, 1996/09/24 for Qt version 1.0 by the webmaster at Troll Tech