QFont(3qt)

NAME
QFont - Font used for drawing text

SYNOPSIS

#include <qfont.h>

  Public Members
enum StyleHint { Helvetica, Times, Courier, OldEnglish, System, AnyStyle, SansSerif = Helvetica, Serif = Times, TypeWriter = Courier, Decorative = OldEnglish}
enum Weight { Light = 25, Normal = 50, DemiBold = 63, Bold = 75, Black = 87 }
enum CharSet { Latin1, ISO_8859_1 = Latin1, AnyCharSet, Latin2, ISO_8859_2 = Latin2, Latin3, ISO_8859_3 = Latin3, Latin4, ISO_8859_4 = Latin4, Latin5, ISO_8859_5 = Latin5, Latin6, ISO_8859_6 = Latin6, Latin7, ISO_8859_7 = Latin7, Latin8, ISO_8859_8 = Latin8, Latin9, ISO_8859_9 = Latin9, KOI8R }
QFont ()
QFont ( const char * family, int pointSize = 12, int weight = Normal, bool italic = FALSE )
QFont ( const char * family, int pointSize, int weight, bool italic, CharSet charSet )
QFont ( const QFont & )
virtual ~QFont ()
QFont& operator= ( const QFont & )
const char* family () const
void setFamily ( const char * )
int pointSize () const
void setPointSize ( int )
int weight () const
void setWeight ( int )
bool bold () const
void setBold ( bool )
bool italic () const
void setItalic ( bool )
bool underline () const
void setUnderline ( bool )
bool strikeOut () const
void setStrikeOut ( bool )
bool fixedPitch () const
void setFixedPitch ( bool )
StyleHint styleHint () const
void setStyleHint ( StyleHint )
CharSet charSet () const
void setCharSet ( CharSet )
bool rawMode () const
void setRawMode ( bool )
bool exactMatch () const
bool operator== ( const QFont & ) const
bool operator!= ( const QFont & ) const
bool isCopyOf ( const QFont & ) const
HANDLE handle ( HANDLE=0 ) const
const char* rawName () const
QString key () const

  Static Public Members
const QFont& defaultFont ()
void setDefaultFont ( const QFont & )
const char* substitute ( const char * familyName )
void insertSubstitution ( const char *, const char * )
void removeSubstitution ( const char * )
void listSubstitutions ( QStrList * )
void initialize ()
void cleanup ()
void cacheStatistics ()

  Protected Members
bool dirty () const
QString defaultFamily () const
QString lastResortFamily () const
QString lastResortFont () const
int deciPointSize () const

RELATED FUNCTION DOCUMENTATION
(Note that these are not member functions.)
QDataStream & operator<< (QDataStream & s, const QFont & f)
QDataStream & operator>> (QDataStream & s, QFont & f)

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

QFont, more precisely, is a collection of attributes of a font. When Qt needs to draw text, it will look up and load the closest matching installed font and draw using that.

The most important attributes of a QFont are family, point size, weight and italic. There are QFont constructors that take these attributes as arguments, as shown in this example:

    void MyWidget::paintEvent( QPaintEvent * )
    {
        QPainter p( 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" );
    }

The default QFont constructor makes a copy of the default font.

You can also change these attributes of an existing QFont object using functions such as setFamily(), setPointSize(), setWeight() and setItalic().

There are also some less-used attributes. setUnderline() decides whether the font is underlined or not; setStrikeOut() can be used to get overstrike (a horizontal line through the middle of the characters); setFixedPitch() determines whether Qt should give preference to fixed-pitch or variable-pitch fonts when it needs to choose an installed font; setStyleHint() can be used to offer more general help to the font matching algorithm, and on X11 setRawMode() can be used to bypass the entire font matching and use an X11 XLFD.

Of course there is also a reader function for each of these set*() functions. Note that the reader functions return the values previously set, not the attributes of the actual window system font that will be used for drawing. You can get information about the font that will be used for drawing by using QFontInfo, but be aware that QFontInfo may be slow and that its results depend on what fonts are installed.

In general font handling and loading are costly operations, especially on X11. The QFont class contains extensive optimizations to make copying of QFont objects fast, and to cache the results of the slow window system functions it uses.

QFont also offers a few static functions, mostly to tune the font matching algorithm: You can control what happens if a font's family isn't installed using insertSubstitution() and removeSubstitution(), ask what happens for a single family uing substitute() and you can get a complete list of the fallback families using listSubstitutions().

cacheStatistics() offers cache effectiveness information; this is useful mostly for debugging.

Finally, setDefaultFont() allows you to set the default font. The default default font is chosen at application startup from a set of common installed fonts that support the correct character set. Of course, the initialization algorithm has a default, too: The default default default font!

For more general information on fonts, see the comp.fonts FAQ.

See also: QFontMetrics, QFontInfo, QApplication::setFont(), QWidget::setFont(), QPainter::setFont(), QFont::StyleHint, QFont::CharSet and QFont::Weight.

Examples: grapher/grapher.cpp desktop/desktop.cpp drawdemo/drawdemo.cpp movies/main.cpp picture/picture.cpp xform/xform.cpp widgets/widgets.cpp

MEMBER FUNCTION DOCUMENTATION

QFont::QFont ()
Constructs a font object that refers to the default font.

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. The character set is copied from the default font and the rest of the settings ser set reasonably.

If pointSize is less than or equal to 0 it is set to 1.

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

QFont::QFont ( const char * family, int pointSize, int weight, bool italic, CharSet charSet )
Constructs a font object with the specified family, pointSize, weight, italic and charSet settings. If pointSize is less than or equal to 0 it is set to 1.

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

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 that is actually used for drawing.

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 the window system handle to the font, for low-level access. Using this function is not portable.

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::isCopyOf ( const QFont & f ) const
Returns TRUE if this font and f are copies of each other, ie. one of them was created as a copy of the other and neither was subsequently modified. This is much stricter than equality.

See also: operator= and operator==.

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::key () const
Returns the font's key, which is a textual representation of the font settings. It is typically used to insert and find fonts in a dictionary or a cache.

See also: QDict and QCache.

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() and deciPointSize().

Examples: xform/xform.cpp

bool QFont::rawMode () const
Returns the value set by setRawMode().

See also: setRawMode().

const char* QFont::rawName () const
Returns the name of the font within the underlying system. Using the return value of this function is usually not portable.

See also: setRawMode() and rawMode().

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 encoding (e.g. Latin1).

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

You can test that the character set is correct using 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" );

In Qt 1.40, the following character set encodings are available:

QFont::Latin1 - ISO 8859-1, common in much of Europe

QFont::Latin2 - ISO 8859-2, less common European character set

QFont::Latin3 - ISO 8859-3, less common European character set

QFont::Latin4 - ISO 8859-4, less common European character set

QFont::Latin5 - ISO 8859-5, Cyrillic

QFont::Latin6 - ISO 8859-6, Arabic

QFont::Latin7 - ISO 8859-7, Greek

QFont::Latin8 - ISO 8859-8, Hebrew

QFont::Latin9 - ISO 8859-9, less common European character set

QFont::KOI8R - KOI8-R, Cyrillic, defined in RFC 1489.

QFont::AnyCharSet - whatever is handiest.

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 is used.

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

Examples: xform/xform.cpp

void QFont::setFixedPitch ( bool enable )
Sets fixed pitch on or off.

A fixed pitch font is a font where all characters have the same width.

See also: fixedPitch(), QFontInfo and font matching

void QFont::setItalic ( bool enable )
Sets italic on or off.

See also: italic(), QFontInfo and font matching

Examples: xform/xform.cpp

void QFont::setPointSize ( int pointSize )
Sets the point size to pointSize. The point size must be greater than zero.

Example:

    QFont font( "courier" );
    font.setPointSize( 18 );

See also: pointSize(), QFontInfo and font matching

Examples: xform/xform.cpp

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() )
            fatal( "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.

See also: strikeOut(), QFontInfo and font matching

Examples: xform/xform.cpp

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 another serif font:

    #include <qapplication.h>
    #include <qpushbutton.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::Serif );  // can also use any serif font
        push.setFont( font );
        return app.exec( &push );
    }

The other available style hints are QFont::SansSerif, QFont::TypeWriter, QFont::OldEnglish, QFont::System

See also: styleHint(), QFontInfo and font matching

Examples: desktop/desktop.cpp

void QFont::setUnderline ( bool enable )
Sets underline on or off.

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

Examples: xform/xform.cpp

void QFont::setWeight ( int weight )
Sets the weight (or boldness).

The enum QFont::Weight contains the predefined font weights:

QFont::Light (25)

QFont::Normal (50)

QFont::DemiBold (63)

QFont::Bold (75)

QFont::Black (87)

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.

See also: weight(), QFontInfo and font matching

Examples: xform/xform.cpp

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 for drawing.

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 FUNCTION DOCUMENTATION

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.

SEE ALSO
http://www.troll.no/qt/qfont.html

COPYRIGHT
Copyright 1992-1997 Troll Tech AS. See the LICENSE file included in the distribution for a complete license statement.

AUTHOR
Generated automatically from the source code.