From ea318d1431c89e647598c510c4245c6571aa5f46 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Thu, 26 Jan 2012 23:32:43 -0600 Subject: Update to latest tqt3 automated conversion --- doc/html/ntqfont.html | 922 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 922 insertions(+) create mode 100644 doc/html/ntqfont.html (limited to 'doc/html/ntqfont.html') diff --git a/doc/html/ntqfont.html b/doc/html/ntqfont.html new file mode 100644 index 000000000..6fad0c182 --- /dev/null +++ b/doc/html/ntqfont.html @@ -0,0 +1,922 @@ + + + + + +TQFont Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQFont Class Reference

+ +

The TQFont class specifies a font used for drawing text. +More... +

#include <ntqfont.h> +

List of all member functions. +

Public Members

+ +

Static Public Members

+ +

Protected Members

+ +

Related Functions

+ +

Detailed Description

+ + +The TQFont class specifies a font used for drawing text. +

+ + + +

When you create a TQFont object you specify various attributes that +you want the font to have. TQt will use the font with the specified +attributes, or if no matching font exists, TQt will use the closest +matching installed font. The attributes of the font that is +actually used are retrievable from a TQFontInfo object. If the +window system provides an exact match exactMatch() returns TRUE. +Use TQFontMetrics to get measurements, e.g. the pixel length of a +string using TQFontMetrics::width(). +

Use TQApplication::setFont() to set the application's default font. +

If a choosen X11 font does not include all the characters that +need to be displayed, TQFont will try to find the characters in the +nearest equivalent fonts. When a TQPainter draws a character from a +font the TQFont will report whether or not it has the character; if +it does not, TQPainter will draw an unfilled square. +

Create TQFonts like this: +

+    TQFont serifFont( "Times", 10, Bold );
+    TQFont sansFont( "Helvetica [Cronyx]", 12 );
+    
+ +

The attributes set in the constructor can also be set later, e.g. +setFamily(), setPointSize(), setPointSizeFloat(), setWeight() and +setItalic(). The remaining attributes must be set after +contstruction, e.g. setBold(), setUnderline(), setOverline(), +setStrikeOut() and setFixedPitch(). TQFontInfo objects should be +created after the font's attributes have been set. A TQFontInfo +object will not change, even if you change the font's +attributes. The corresponding "get" functions, e.g. family(), +pointSize(), etc., return the values that were set, even though +the values used may differ. The actual values are available from a +TQFontInfo object. +

If the requested font family is unavailable you can influence the +font matching algorithm by choosing a +particular TQFont::StyleHint and TQFont::StyleStrategy with +setStyleHint(). The default family (corresponding to the current +style hint) is returned by defaultFamily(). +

The font-matching algorithm has a lastResortFamily() and +lastResortFont() in cases where a suitable match cannot be found. +You can provide substitutions for font family names using +insertSubstitution() and insertSubstitutions(). Substitutions can +be removed with removeSubstitution(). Use substitute() to retrieve +a family's first substitute, or the family name itself if it has +no substitutes. Use substitutes() to retrieve a list of a family's +substitutes (which may be empty). +

Every TQFont has a key() which you can use, for example, as the key +in a cache or dictionary. If you want to store a user's font +preferences you could use TQSettings, writing the font information +with toString() and reading it back with fromString(). The +operator<<() and operator>>() functions are also available, but +they work on a data stream. +

It is possible to set the height of characters shown on the screen +to a specified number of pixels with setPixelSize(); however using +setPointSize() has a similar effect and provides device +independence. +

Under the X Window System you can set a font using its system +specific name with setRawName(). +

Loading fonts can be expensive, especially on X11. TQFont contains +extensive optimizations to make the copying of TQFont objects fast, +and to cache the results of the slow window system functions it +depends upon. +

+The font matching algorithm works as follows: +

    +
  1. The specified font family is searched for. +
  2. If not found, the styleHint() is used to select a replacement +family. +
  3. Each replacement font family is searched for. +
  4. If none of these are found or there was no styleHint(), "helvetica" +will be searched for. +
  5. If "helvetica" isn't found TQt will try the lastResortFamily(). +
  6. If the lastResortFamily() isn't found TQt will try the +lastResortFont() which will always return a name of some kind. +
+

Once a font is found, the remaining attributes are matched in order of +priority: +

    +
  1. fixedPitch() +
  2. pointSize() (see below) +
  3. weight() +
  4. italic() +
+

If you have a font which matches on family, even if none of the +other attributes match, this font will be chosen in preference to +a font which doesn't match on family but which does match on the +other attributes. This is because font family is the dominant +search criteria. +

The point size is defined to match if it is within 20% of the +requested point size. When several fonts match and are only +distinguished by point size, the font with the closest point size +to the one requested will be chosen. +

The actual family, font size, weight and other font attributes +used for drawing text will depend on what's available for the +chosen family under the window system. A TQFontInfo object can be +used to determine the actual values used for drawing the text. +

Examples: +

+    TQFont f("Helvetica");
+    
+ +If you had both an Adobe and a Cronyx Helvetica, you might get +either. +

+    TQFont f1( "Helvetica [Cronyx]" );  // TQt 3.x
+    TQFont f2( "Cronyx-Helvetica" );    // TQt 2.x compatibility
+    
+ +You can specify the foundry you want in the family name. Both fonts, +f1 and f2, in the above example will be set to "Helvetica +[Cronyx]". +

To determine the attributes of the font actually used in the window +system, use a TQFontInfo object, e.g. +

+    TQFontInfo info( f1 );
+    TQString family = info.family();
+    
+ +

To find out font metrics use a TQFontMetrics object, e.g. +

+    TQFontMetrics fm( f1 );
+    int pixelWidth = fm.width( "How many pixels wide is this text?" );
+    int pixelHeight = fm.height();
+    
+ +

For more general information on fonts, see the +comp.fonts FAQ. +Information on encodings can be found from +Roman Czyborra's page. +

See also TQFontMetrics, TQFontInfo, TQFontDatabase, TQApplication::setFont(), TQWidget::font, TQPainter::setFont(), TQFont::StyleHint, TQFont::Weight, Widget Appearance and Style, Graphics Classes, and Implicitly and Explicitly Shared Classes. + +


Member Type Documentation

+

TQFont::Script

+ +

This enum represents Unicode allocated +scripts. For exhaustive coverage see The + Unicode Standard Version 3.0. The following scripts are +supported: +

Modern European alphabetic scripts (left to right): +

Middle Eastern scripts (right to left): +

South and Southeast Asian scripts (left to right with few historical exceptions): +

East Asian scripts (traditionally top-down, right to left, modern +often horizontal left to right): +

Additional scripts that do not fit well into the script categories above: +

Symbols: +

+

TQFont::Stretch

+ +

Predefined stretch values that follow the CSS naming convention. +

See also setStretch() and stretch(). + +

TQFont::StyleHint

+ +

Style hints are used by the font + matching algorithm to find an appropriate default family +if a selected font family is not available. +

+

TQFont::StyleStrategy

+ +

The style strategy tells the font + matching algorithm what type of fonts should be used to +find an appropriate default family. +

The following strategies are available: +

Any of these may be OR-ed with one of these flags: +

+

TQFont::Weight

+ +

TQt uses a weighting scale from 0 to 99 similar to, but not the +same as, the scales used in Windows or CSS. A weight of 0 is +ultralight, whilst 99 will be an extremely black. +

This enum contains the predefined font weights: +

+

Member Function Documentation

+

TQFont::TQFont () +

+Constructs a font object that uses the application's default font. +

See also TQApplication::setFont() and TQApplication::font(). + +

TQFont::TQFont ( const TQString & 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 <= 0 it is set to 1. +

The family name may optionally also include a foundry name, +e.g. "Helvetica [Cronyx]". (The TQt 2.x syntax, i.e. +"Cronyx-Helvetica", is also supported.) 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 will be set using the font + matching algorithm. +

See also Weight, setFamily(), setPointSize(), setWeight(), setItalic(), setStyleHint(), and TQApplication::font(). + +

TQFont::TQFont ( const TQFont & font ) +

+Constructs a font that is a copy of font. + +

TQFont::~TQFont () +

+Destroys the font object and frees all allocated resources. + +

bool TQFont::bold () const +

+ +

Returns TRUE if weight() is a value greater than TQFont::Normal; otherwise returns FALSE. +

See also weight(), setBold(), and TQFontInfo::bold(). + +

Example: chart/optionsform.cpp. +

int TQFont::deciPointSize () const [protected] +

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

The returned value will be -1 if the font size has been specified +in pixels. +

See also pointSize() and pointSizeFloat(). + +

TQString TQFont::defaultFamily () const +

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

See also StyleHint, styleHint(), and setStyleHint(). + +

TQFont TQFont::defaultFont () [static] +

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code. +

Please use TQApplication::font() instead. + +

bool TQFont::dirty () const [protected] +

+Returns TRUE if the font attributes have been changed and the font +has to be (re)loaded; otherwise returns FALSE. + +

bool TQFont::exactMatch () const +

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

See also TQFontInfo. + +

TQString TQFont::family () const +

+Returns the requested font family name, i.e. the name set in the +constructor or the last setFont() call. +

See also setFamily(), substitutes(), and substitute(). + +

Examples: chart/optionsform.cpp and fonts/simple-qfont-demo/viewer.cpp. +

bool TQFont::fixedPitch () const +

+Returns TRUE if fixed pitch has been set; otherwise returns FALSE. +

See also setFixedPitch() and TQFontInfo::fixedPitch(). + +

bool TQFont::fromString ( const TQString & descrip ) +

+Sets this font to match the description descrip. The description +is a comma-separated list of the font attributes, as returned by +toString(). +

See also toString() and operator>>(). + +

HFONT TQFont::handle () const +

+Returns the window system handle to the font, for low-level +access. Using this function is not portable. + +

void TQFont::insertSubstitution ( const TQString & familyName, const TQString & substituteName ) [static] +

+Inserts the family name substituteName into the substitution +table for familyName. +

See also insertSubstitutions(), removeSubstitution(), substitutions(), substitute(), and substitutes(). + +

Example: fonts/simple-qfont-demo/viewer.cpp. +

void TQFont::insertSubstitutions ( const TQString & familyName, const TQStringList & substituteNames ) [static] +

+Inserts the list of families substituteNames into the +substitution list for familyName. +

See also insertSubstitution(), removeSubstitution(), substitutions(), and substitute(). + +

Example: fonts/simple-qfont-demo/viewer.cpp. +

bool TQFont::isCopyOf ( const TQFont & f ) const +

+Returns TRUE if this font and f are copies of each other, i.e. +one of them was created as a copy of the other and neither has +been modified since. This is much stricter than equality. +

See also operator=() and operator==(). + +

bool TQFont::italic () const +

+Returns TRUE if italic has been set; otherwise returns FALSE. +

See also setItalic(). + +

Example: chart/optionsform.cpp. +

TQString TQFont::key () const +

+Returns the font's key, a textual representation of a font. It is +typically used as the key for a cache or dictionary of fonts. +

See also TQMap. + +

TQString TQFont::lastResortFamily () const +

+Returns the "last resort" font family name. +

The current implementation tries a wide variety of common fonts, +returning the first one it finds. Is is possible that no family is +found in which case a null string is returned. +

See also lastResortFont(). + +

TQString TQFont::lastResortFont () const +

+Returns a "last resort" font name for the font matching algorithm. +This is used if the last resort family is not available. It will +always return a name, if necessary returning something like +"fixed" or "system". +

The current implementation tries a wide variety of common fonts, +returning the first one it finds. The implementation may change +at any time, but this function will always return a string +containing something. +

It is theoretically possible that there really isn't a +lastResortFont() in which case TQt will abort with an error +message. We have not been able to identify a case where this +happens. Please report it as a bug if +it does, preferably with a list of the fonts you have installed. +

See also lastResortFamily() and rawName(). + +

bool TQFont::operator!= ( const TQFont & f ) const +

+Returns TRUE if this font is different from f; otherwise +returns FALSE. +

Two TQFonts are considered to be different if their font attributes +are different. If rawMode() is enabled for both fonts, only the +family fields are compared. +

See also operator==(). + +

TQFont & TQFont::operator= ( const TQFont & font ) +

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

bool TQFont::operator== ( const TQFont & f ) const +

+Returns TRUE if this font is equal to f; otherwise returns +FALSE. +

Two TQFonts are considered equal if their font attributes are +equal. If rawMode() is enabled for both fonts, only the family +fields are compared. +

See also operator!=() and isCopyOf(). + +

bool TQFont::overline () const +

+Returns TRUE if overline has been set; otherwise returns FALSE. +

See also setOverline(). + +

int TQFont::pixelSize () const +

+Returns the pixel size of the font if it was set with +setPixelSize(). Returns -1 if the size was set with setPointSize() +or setPointSizeFloat(). +

See also setPixelSize(), pointSize(), TQFontInfo::pointSize(), and TQFontInfo::pixelSize(). + +

int TQFont::pointSize () const +

+Returns the point size of the font. Returns -1 if the font size +was specified in pixels. +

See also setPointSize(), deciPointSize(), and pointSizeFloat(). + +

Examples: chart/optionsform.cpp and fonts/simple-qfont-demo/viewer.cpp. +

float TQFont::pointSizeFloat () const +

+Returns the point size of the font. Returns -1 if the font size was +specified in pixels. +

See also pointSize(), setPointSizeFloat(), pixelSize(), TQFontInfo::pointSize(), and TQFontInfo::pixelSize(). + +

void TQFont::qwsRenderToDisk ( bool all = TRUE ) +

+Saves the glyphs in the font that have previously been accessed as +a TQPF file. If all is TRUE (the default), then before saving, +all glyphs are marked as used. +

If the font is large and you are sure that only a subset of +characters will ever be required on the target device, passing +FALSE for the all parameter can save a significant amount of +disk space. +

Note that this function is only applicable on TQt/Embedded. + +

bool TQFont::rawMode () const +

+Returns TRUE if raw mode is used for font name matching; otherwise +returns FALSE. +

See also setRawMode() and rawName(). + +

TQString TQFont::rawName () const +

+Returns the name of the font within the underlying window system. +

On Windows, this is usually just the family name of a TrueType +font. +

On X11, it is an XLFD (X Logical Font Description). When TQt is +build with Xft support on X11, the return value can be an Xft +pattern or an XLFD. +

Using the return value of this function is usually not portable. +

See also setRawName(). + +

void TQFont::removeSubstitution ( const TQString & familyName ) [static] +

+Removes all the substitutions for familyName. +

See also insertSubstitutions(), insertSubstitution(), substitutions(), and substitute(). + +

TQFont TQFont::resolve ( const TQFont & other ) const +

+Returns a new TQFont that has attributes copied from other. + +

void TQFont::setBold ( bool enable ) +

+ +

If enable is true sets the font's weight to TQFont::Bold; otherwise sets the weight to TQFont::Normal. +

For finer boldness control use setWeight(). +

See also bold() and setWeight(). + +

Examples: menu/menu.cpp and themes/metal.cpp. +

void TQFont::setDefaultFont ( const TQFont & f ) [static] +

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code. +

Please use TQApplication::setFont() instead. + +

void TQFont::setFamily ( const TQString & family ) +

+Sets the family name of the font. The name is case insensitive and +may include a foundry name. +

The family name may optionally also include a foundry name, +e.g. "Helvetica [Cronyx]". (The TQt 2.x syntax, i.e. +"Cronyx-Helvetica", is also supported.) 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 will be set using the font + matching algorithm. +

See also family(), setStyleHint(), and TQFontInfo. + +

void TQFont::setFixedPitch ( bool enable ) +

+If enable is TRUE, sets fixed pitch on; otherwise sets fixed +pitch off. +

See also fixedPitch() and TQFontInfo. + +

void TQFont::setItalic ( bool enable ) +

+If enable is TRUE, italic is set on; otherwise italic is set +off. +

See also italic() and TQFontInfo. + +

Examples: fileiconview/qfileiconview.cpp, fonts/simple-qfont-demo/viewer.cpp, and themes/metal.cpp. +

void TQFont::setOverline ( bool enable ) +

+If enable is TRUE, sets overline on; otherwise sets overline off. +

See also overline() and TQFontInfo. + +

void TQFont::setPixelSize ( int pixelSize ) +

+Sets the font size to pixelSize pixels. +

Using this function makes the font device dependent. Use +setPointSize() or setPointSizeFloat() to set the size of the font +in a device independent manner. +

See also pixelSize(). + +

Example: qwerty/qwerty.cpp. +

void TQFont::setPixelSizeFloat ( float pixelSize ) +

This function is obsolete. It is provided to keep old source working. We strongly advise against using it in new code. +

Sets the logical pixel height of font characters when shown on +the screen to pixelSize. + +

void TQFont::setPointSize ( int pointSize ) +

+Sets the point size to pointSize. The point size must be +greater than zero. +

See also pointSize() and setPointSizeFloat(). + +

Example: fonts/simple-qfont-demo/viewer.cpp. +

void TQFont::setPointSizeFloat ( float pointSize ) +

+Sets the point size to pointSize. The point size must be +greater than zero. The requested precision may not be achieved on +all platforms. +

See also pointSizeFloat(), setPointSize(), and setPixelSize(). + +

void TQFont::setRawMode ( bool enable ) +

+If enable is TRUE, turns raw mode on; otherwise turns raw mode +off. This function only has an effect under X11. +

If raw mode is enabled, TQt will search for an X font with a +complete font name matching the family name, ignoring all other +values set for the TQFont. If the font name matches several fonts, +TQt will use the first font returned by X. TQFontInfo cannot be +used to fetch information about a TQFont using raw mode (it will +return the values set in the TQFont for all parameters, including +the family name). +

Warning: Do not use raw mode unless you really, really need it! In +most (if not all) cases, setRawName() is a much better choice. +

See also rawMode() and setRawName(). + +

void TQFont::setRawName ( const TQString & name ) +

+Sets a font by its system specific name. The function is +particularly useful under X, where system font settings (for +example X resources) are usually available in XLFD (X Logical Font +Description) form only. You can pass an XLFD as name to this +function. +

A font set with setRawName() is still a full-featured TQFont. It can +be queried (for example with italic()) or modified (for example with +setItalic()) and is therefore also suitable for rendering rich text. +

If TQt's internal font database cannot resolve the raw name, the +font becomes a raw font with name as its family. +

Note that the present implementation does not handle wildcards in +XLFDs well, and that font aliases (file fonts.alias in the font +directory on X11) are not supported. +

See also rawName(), setRawMode(), and setFamily(). + +

void TQFont::setStretch ( int factor ) +

+Sets the stretch factor for the font. +

The stretch factor changes the width of all characters in the font +by factor percent. For example, setting factor to 150 +results in all characters in the font being 1.5 times ( ie. 150% ) +wider. The default stretch factor is 100. The minimum stretch +factor is 1, and the maximum stretch factor is 4000. +

The stretch factor is only applied to outline fonts. The stretch +factor is ignored for bitmap fonts. +

NOTE: TQFont cannot stretch XLFD fonts. When loading XLFD fonts on +X11, the stretch factor is matched against a predefined set of +values for the SETWIDTH_NAME field of the XLFD. +

See also stretch() and TQFont::StyleStrategy. + +

void TQFont::setStrikeOut ( bool enable ) +

+If enable is TRUE, sets strikeout on; otherwise sets strikeout +off. +

See also strikeOut() and TQFontInfo. + +

void TQFont::setStyleHint ( StyleHint hint, StyleStrategy strategy = PreferDefault ) +

+Sets the style hint and strategy to hint and strategy, +respectively. +

If these aren't set explicitly the style hint will default to +AnyStyle and the style strategy to PreferDefault. +

TQt does not support style hints on X11 since this information +is not provided by the window system. +

See also StyleHint, styleHint(), StyleStrategy, styleStrategy(), and TQFontInfo. + +

Examples: desktop/desktop.cpp and fonts/simple-qfont-demo/viewer.cpp. +

void TQFont::setStyleStrategy ( StyleStrategy s ) +

+Sets the style strategy for the font to s. +

See also TQFont::StyleStrategy. + +

void TQFont::setUnderline ( bool enable ) +

+If enable is TRUE, sets underline on; otherwise sets underline +off. +

See also underline() and TQFontInfo. + +

Examples: fonts/simple-qfont-demo/viewer.cpp and menu/menu.cpp. +

void TQFont::setWeight ( int weight ) +

+Sets the weight the font to weight, which should be a value +from the TQFont::Weight enumeration. +

See also weight() and TQFontInfo. + +

Example: fonts/simple-qfont-demo/viewer.cpp. +

int TQFont::stretch () const +

+Returns the stretch factor for the font. +

See also setStretch(). + +

bool TQFont::strikeOut () const +

+Returns TRUE if strikeout has been set; otherwise returns FALSE. +

See also setStrikeOut(). + +

StyleHint TQFont::styleHint () const +

+Returns the StyleHint. +

The style hint affects the font + matching algorithm. See TQFont::StyleHint for the list +of strategies. +

See also setStyleHint(), TQFont::StyleStrategy, and TQFontInfo::styleHint(). + +

StyleStrategy TQFont::styleStrategy () const +

+Returns the StyleStrategy. +

The style strategy affects the font + matching algorithm. See TQFont::StyleStrategy for the +list of strategies. +

See also setStyleHint() and TQFont::StyleHint. + +

TQString TQFont::substitute ( const TQString & familyName ) [static] +

+Returns the first family name to be used whenever familyName is +specified. The lookup is case insensitive. +

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

To obtain a list of substitutions use substitutes(). +

See also setFamily(), insertSubstitutions(), insertSubstitution(), and removeSubstitution(). + +

TQStringList TQFont::substitutes ( const TQString & familyName ) [static] +

+Returns a list of family names to be used whenever familyName +is specified. The lookup is case insensitive. +

If there is no substitution for familyName, an empty list is +returned. +

See also substitute(), insertSubstitutions(), insertSubstitution(), and removeSubstitution(). + +

Example: fonts/simple-qfont-demo/viewer.cpp. +

TQStringList TQFont::substitutions () [static] +

+Returns a sorted list of substituted family names. +

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

TQString TQFont::toString () const +

+Returns a description of the font. The description is a +comma-separated list of the attributes, perfectly suited for use +in TQSettings. +

See also fromString() and operator<<(). + +

bool TQFont::underline () const +

+Returns TRUE if underline has been set; otherwise returns FALSE. +

See also setUnderline(). + +

int TQFont::weight () const +

+Returns the weight of the font which is one of the enumerated +values from TQFont::Weight. +

See also setWeight(), Weight, and TQFontInfo. + +


Related Functions

+

TQDataStream & operator<< ( TQDataStream & s, const TQFont & font ) +

+ +

Writes the font font to the data stream s. (toString() +writes to a text stream.) +

See also Format of the TQDataStream operators. + +

TQDataStream & operator>> ( TQDataStream & s, TQFont & font ) +

+ +

Reads the font font from the data stream s. (fromString() +reads from a text stream.) +

See also Format of the TQDataStream operators. + + +


+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.


+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1