1QFontMetrics(3qt)                                            QFontMetrics(3qt)
2
3
4

NAME

6       QFontMetrics - Font metrics information
7

SYNOPSIS

9       #include <qfontmetrics.h>
10
11   Public Members
12       QFontMetrics ( const QFont & font )
13       QFontMetrics ( const QFont & font, QFont::Script script )
14       QFontMetrics ( const QFontMetrics & fm )
15       ~QFontMetrics ()
16       QFontMetrics & operator= ( const QFontMetrics & fm )
17       int ascent () const
18       int descent () const
19       int height () const
20       int leading () const
21       int lineSpacing () const
22       int minLeftBearing () const
23       int minRightBearing () const
24       int maxWidth () const
25       bool inFont ( QChar ch ) const
26       int leftBearing ( QChar ch ) const
27       int rightBearing ( QChar ch ) const
28       int width ( const QString & str, int len = -1 ) const
29       int width ( QChar ch ) const
30       int width ( char c ) const  (obsolete)
31       int charWidth ( const QString & str, int pos ) const
32       QRect boundingRect ( const QString & str, int len = -1 ) const
33       QRect boundingRect ( QChar ch ) const
34       QRect boundingRect ( int x, int y, int w, int h, int flgs, const
35           QString & str, int len = -1, int tabstops = 0, int * tabarray = 0,
36           QTextParag ** intern = 0 ) const
37       QSize size ( int flgs, const QString & str, int len = -1, int tabstops
38           = 0, int * tabarray = 0, QTextParag ** intern = 0 ) const
39       int underlinePos () const
40       int overlinePos () const
41       int strikeOutPos () const
42       int lineWidth () const
43

DESCRIPTION

45       The QFontMetrics class provides font metrics information.
46
47       QFontMetrics functions calculate the size of characters and strings for
48       a given font. There are three ways you can create a QFontMetrics
49       object:
50
51       <ol type=1>
52
53       1      Calling the QFontMetrics constructor with a QFont creates a font
54              metrics object for a screen-compatible font, i.e. the font
55              cannot be a printer font<sup>*</sup>. If the font is changed
56              later, the font metrics object is not updated.
57
58       2      QWidget::fontMetrics() returns the font metrics for a widget's
59              font. This is equivalent to QFontMetrics(widget->font()). If the
60              widget's font is changed later, the font metrics object is not
61              updated.
62
63       3      QPainter::fontMetrics() returns the font metrics for a painter's
64              current font. If the painter's font is changed later, the font
65              metrics object is not updated.
66
67       <sup>*</sup> If you use a printer font the values returned may be
68       inaccurate. Printer fonts are not always accessible so the nearest
69       screen font is used if a printer font is supplied.
70
71       Once created, the object provides functions to access the individual
72       metrics of the font, its characters, and for strings rendered in the
73       font.
74
75       There are several functions that operate on the font: ascent(),
76       descent(), height(), leading() and lineSpacing() return the basic size
77       properties of the font. The underlinePos(), overlinePos(),
78       strikeOutPos() and lineWidth() functions, return the properties of the
79       line that underlines, overlines or strikes out the characters. These
80       functions are all fast.
81
82       There are also some functions that operate on the set of glyphs in the
83       font: minLeftBearing(), minRightBearing() and maxWidth(). These are by
84       necessity slow, and we recommend avoiding them if possible.
85
86       For each character, you can get its width(), leftBearing() and
87       rightBearing() and find out whether it is in the font using inFont().
88       You can also treat the character as a string, and use the string
89       functions on it.
90
91       The string functions include width(), to return the width of a string
92       in pixels (or points, for a printer), boundingRect(), to return a
93       rectangle large enough to contain the rendered string, and size(), to
94       return the size of that rectangle.
95
96       Example:
97
98           QFont font( "times", 24 );
99           QFontMetrics fm( font );
100           int pixelsWide = fm.width( "What's the width of this text?" );
101           int pixelsHigh = fm.height();
102
103       See also QFont, QFontInfo, QFontDatabase, Graphics Classes, and
104       Implicitly and Explicitly Shared Classes.
105

MEMBER FUNCTION DOCUMENTATION

QFontMetrics::QFontMetrics ( const QFont & font )

108       Constructs a font metrics object for font.
109
110       The font must be screen-compatible, i.e. a font you use when drawing
111       text in widgets or pixmaps, not QPicture or QPrinter.
112
113       The font metrics object holds the information for the font that is
114       passed in the constructor at the time it is created, and is not updated
115       if the font's attributes are changed later.
116
117       Use QPainter::fontMetrics() to get the font metrics when painting. This
118       will give correct results also when painting on paint device that is
119       not screen-compatible.
120

QFontMetrics::QFontMetrics ( const QFont & font, QFont::Script script )

122       This is an overloaded member function, provided for convenience. It
123       behaves essentially like the above function.
124
125       Constructs a font metrics object for font using the given script.
126

QFontMetrics::QFontMetrics ( const QFontMetrics & fm )

128       Constructs a copy of fm.
129

QFontMetrics::~QFontMetrics ()

131       Destroys the font metrics object and frees all allocated resources.
132

int QFontMetrics::ascent () const

134       Returns the ascent of the font.
135
136       The ascent of a font is the distance from the baseline to the highest
137       position characters extend to. In practice, some font designers break
138       this rule, e.g. when they put more than one accent on top of a
139       character, or to accommodate an unusual character in an exotic
140       language, so it is possible (though rare) that this value will be too
141       small.
142
143       See also descent().
144
145       Examples:
146

QRect QFontMetrics::boundingRect ( QChar ch ) const

148       Returns the rectangle that is covered by ink if the character specified
149       by ch were to be drawn at the origin of the coordinate system.
150
151       Note that the bounding rectangle may extend to the left of (0, 0), e.g.
152       for italicized fonts, and that the text output may cover all pixels in
153       the bounding rectangle. For a space character the rectangle will
154       usually be empty.
155
156       Note that the rectangle usually extends both above and below the base
157       line.
158
159       Warning: The width of the returned rectangle is not the advance width
160       of the character. Use boundingRect(const QString &) or width() instead.
161
162       See also width().
163
164       Example: xform/xform.cpp.
165

QRect QFontMetrics::boundingRect ( const QString & str, int len = -1 ) const

167       This is an overloaded member function, provided for convenience. It
168       behaves essentially like the above function.
169
170       Returns the bounding rectangle that contains the first len characters
171       of string str.
172

QRect QFontMetrics::boundingRect ( int x, int y, int w, int h, int flgs, const

174       QString & str, int len = -1, int tabstops = 0, int * tabarray = 0,
175       QTextParag ** intern = 0 ) const
176       This is an overloaded member function, provided for convenience. It
177       behaves essentially like the above function.
178
179       Returns the bounding rectangle of the first len characters of str,
180       which is the set of pixels the text would cover if drawn at (0, 0). The
181       drawing, and hence the bounding rectangle, is constrained to the
182       rectangle (x, y, w, h).
183
184       If len is negative (which is the default), the entire string is used.
185
186       The flgs argument is the bitwise OR of the following flags:
187
188       AlignAuto aligns to the left border for all languages except Arabic and
189       Hebrew where it aligns to the right.
190
191       AlignLeft aligns to the left border.
192
193       AlignRight aligns to the right border.
194
195       AlignJustify produces justified text.
196
197       AlignHCenter aligns horizontally centered.
198
199       AlignTop aligns to the top border.
200
201       AlignBottom aligns to the bottom border.
202
203       AlignVCenter aligns vertically centered
204
205       AlignCenter (== AlignHCenter | AlignVCenter)
206
207       SingleLine ignores newline characters in the text.
208
209       ExpandTabs expands tabs (see below)
210
211       ShowPrefix interprets "&x" as "<u>x</u>", i.e. underlined.
212
213       WordBreak breaks the text to fit the rectangle.
214
215       Horizontal alignment defaults to AlignAuto and vertical alignment
216       defaults to AlignTop.
217
218       If several of the horizontal or several of the vertical alignment flags
219       are set, the resulting alignment is undefined.
220
221       These flags are defined in qnamespace.h.
222
223       If ExpandTabs is set in flgs, then: if tabarray is non-null, it
224       specifies a 0-terminated sequence of pixel-positions for tabs;
225       otherwise if tabstops is non-zero, it is used as the tab spacing (in
226       pixels).
227
228       Note that the bounding rectangle may extend to the left of (0, 0), e.g.
229       for italicized fonts, and that the text output may cover all pixels in
230       the bounding rectangle.
231
232       Newline characters are processed as linebreaks.
233
234       Despite the different actual character heights, the heights of the
235       bounding rectangles of "Yes" and "yes" are the same.
236
237       The bounding rectangle given by this function is somewhat larger than
238       that calculated by the simpler boundingRect() function. This function
239       uses the maximum left and right font bearings as is necessary for
240       multi-line text to align correctly. Also, fontHeight() and
241       lineSpacing() are used to calculate the height, rather than individual
242       character heights.
243
244       The intern argument should not be used.
245
246       See also width(), QPainter::boundingRect(), and Qt::AlignmentFlags.
247

int QFontMetrics::charWidth ( const QString & str, int pos ) const

249       Returns the width of the character at position pos in the string str.
250
251       The whole string is needed, as the glyph drawn may change depending on
252       the context (the letter before and after the current one) for some
253       languages (e.g. Arabic).
254
255       This function also takes non spacing marks and ligatures into account.
256

int QFontMetrics::descent () const

258       Returns the descent of the font.
259
260       The descent is the distance from the base line to the lowest point
261       characters extend to. (Note that this is different from X, which adds 1
262       pixel.) In practice, some font designers break this rule, e.g. to
263       accommodate an unusual character in an exotic language, so it is
264       possible (though rare) that this value will be too small.
265
266       See also ascent().
267
268       Examples:
269

int QFontMetrics::height () const

271       Returns the height of the font.
272
273       This is always equal to ascent()+descent()+1 (the 1 is for the base
274       line).
275
276       See also leading() and lineSpacing().
277
278       Examples:
279

bool QFontMetrics::inFont ( QChar ch ) const

281       Returns TRUE if character ch is a valid character in the font;
282       otherwise returns FALSE.
283
284       Example: qfd/fontdisplayer.cpp.
285

int QFontMetrics::leading () const

287       Returns the leading of the font.
288
289       This is the natural inter-line spacing.
290
291       See also height() and lineSpacing().
292

int QFontMetrics::leftBearing ( QChar ch ) const

294       Returns the left bearing of character ch in the font.
295
296       The left bearing is the right-ward distance of the left-most pixel of
297       the character from the logical origin of the character. This value is
298       negative if the pixels of the character extend to the left of the
299       logical origin.
300
301       See width(QChar) for a graphical description of this metric.
302
303       See also rightBearing(), minLeftBearing(), and width().
304
305       Example: qfd/fontdisplayer.cpp.
306

int QFontMetrics::lineSpacing () const

308       Returns the distance from one base line to the next.
309
310       This value is always equal to leading()+height().
311
312       See also height() and leading().
313
314       Examples:
315

int QFontMetrics::lineWidth () const

317       Returns the width of the underline and strikeout lines, adjusted for
318       the point size of the font.
319
320       See also underlinePos(), overlinePos(), and strikeOutPos().
321

int QFontMetrics::maxWidth () const

323       Returns the width of the widest character in the font.
324
325       Example: qfd/fontdisplayer.cpp.
326

int QFontMetrics::minLeftBearing () const

328       Returns the minimum left bearing of the font.
329
330       This is the smallest leftBearing(char) of all characters in the font.
331
332       Note that this function can be very slow if the font is large.
333
334       See also minRightBearing() and leftBearing().
335
336       Example: qfd/fontdisplayer.cpp.
337

int QFontMetrics::minRightBearing () const

339       Returns the minimum right bearing of the font.
340
341       This is the smallest rightBearing(char) of all characters in the font.
342
343       Note that this function can be very slow if the font is large.
344
345       See also minLeftBearing() and rightBearing().
346
347       Example: qfd/fontdisplayer.cpp.
348

QFontMetrics & QFontMetrics::operator= ( const QFontMetrics & fm )

350       Assigns the font metrics fm.
351

int QFontMetrics::overlinePos () const

353       Returns the distance from the base line to where an overline should be
354       drawn.
355
356       See also underlinePos(), strikeOutPos(), and lineWidth().
357

int QFontMetrics::rightBearing ( QChar ch ) const

359       Returns the right bearing of character ch in the font.
360
361       The right bearing is the left-ward distance of the right-most pixel of
362       the character from the logical origin of a subsequent character. This
363       value is negative if the pixels of the character extend to the right of
364       the width() of the character.
365
366       See width() for a graphical description of this metric.
367
368       See also leftBearing(), minRightBearing(), and width().
369
370       Example: qfd/fontdisplayer.cpp.
371

QSize QFontMetrics::size ( int flgs, const QString & str, int len = -1, int

373       tabstops = 0, int * tabarray = 0, QTextParag ** intern = 0 ) const
374       Returns the size in pixels of the first len characters of str.
375
376       If len is negative (the default), the entire string is used.
377
378       The flgs argument is the bitwise OR of the following flags:
379
380       SingleLine ignores newline characters.
381
382       ExpandTabs expands tabs (see below)
383
384       ShowPrefix interprets "&x" as "<u>x</u>", i.e. underlined.
385
386       WordBreak breaks the text to fit the rectangle.
387
388       These flags are defined in qnamespace.h.
389
390       If ExpandTabs is set in flgs, then: if tabarray is non-null, it
391       specifies a 0-terminated sequence of pixel-positions for tabs;
392       otherwise if tabstops is non-zero, it is used as the tab spacing (in
393       pixels).
394
395       Newline characters are processed as linebreaks.
396
397       Despite the different actual character heights, the heights of the
398       bounding rectangles of "Yes" and "yes" are the same.
399
400       The intern argument should not be used.
401
402       See also boundingRect().
403

int QFontMetrics::strikeOutPos () const

405       Returns the distance from the base line to where the strikeout line
406       should be drawn.
407
408       See also underlinePos(), overlinePos(), and lineWidth().
409

int QFontMetrics::underlinePos () const

411       Returns the distance from the base line to where an underscore should
412       be drawn.
413
414       See also overlinePos(), strikeOutPos(), and lineWidth().
415

int QFontMetrics::width ( QChar ch ) const

417                                   [Image Omitted]
418
419       Returns the logical width of character ch in pixels. This is a distance
420       appropriate for drawing a subsequent character after ch.
421
422       Some of the metrics are described in the image to the right. The
423       central dark rectangles cover the logical width() of each character.
424       The outer pale rectangles cover the leftBearing() and rightBearing() of
425       each character. Notice that the bearings of "f" in this particular font
426       are both negative, while the bearings of" o" are both positive.
427
428       Warning: This function will produce incorrect results for Arabic
429       characters or non spacing marks in the middle of a string, as the glyph
430       shaping and positioning of marks that happens when processing strings
431       cannot be taken into account. Use charWidth() instead if you aren't
432       looking for the width of isolated characters.
433
434       See also boundingRect() and charWidth().
435
436       Examples:
437

int QFontMetrics::width ( const QString & str, int len = -1 ) const

439       This is an overloaded member function, provided for convenience. It
440       behaves essentially like the above function.
441
442       Returns the width of the first len characters of string str.
443

int QFontMetrics::width ( char c ) const

445       This is an overloaded member function, provided for convenience. It
446       behaves essentially like the above function.
447
448       This function is obsolete. It is provided to keep old source working.
449       We strongly advise against using it in new code.
450
451       Provided to aid porting from Qt 1.x.
452
453

SEE ALSO

455       http://doc.trolltech.com/qfontmetrics.html
456       http://www.trolltech.com/faq/tech.html
457
459       Copyright 1992-2007 Trolltech ASA, http://www.trolltech.com.  See the
460       license file included in the distribution for a complete license
461       statement.
462

AUTHOR

464       Generated automatically from the source code.
465

BUGS

467       If you find a bug in Qt, please report it as described in
468       http://doc.trolltech.com/bughowto.html.  Good bug reports help us to
469       help you. Thank you.
470
471       The definitive Qt documentation is provided in HTML format; it is
472       located at $QTDIR/doc/html and can be read using Qt Assistant or with a
473       web browser. This man page is provided as a convenience for those users
474       who prefer man pages, although this format is not officially supported
475       by Trolltech.
476
477       If you find errors in this manual page, please report them to qt-
478       bugs@trolltech.com.  Please include the name of the manual page
479       (qfontmetrics.3qt) and the Qt version (3.3.8).
480
481
482
483Trolltech AS                    2 February 2007              QFontMetrics(3qt)
Impressum