1QFontMetrics(3qt) QFontMetrics(3qt)
2
6 QFontMetrics - Font metrics information
7
9 #include <qfontmetrics.h>
10 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
45 The QFontMetrics class provides font metrics information.
46 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 <ol type=1>
52 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 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 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 <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 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 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 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 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 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 Example:
97 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 See also QFont, QFontInfo, QFontDatabase, Graphics Classes, and
104 Implicitly and Explicitly Shared Classes.
105
108 Constructs a font metrics object for font.
109 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 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 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
122 This is an overloaded member function, provided for convenience. It
123 behaves essentially like the above function.
124 Constructs a font metrics object for font using the given script.
126
128 Constructs a copy of fm.
129
131 Destroys the font metrics object and frees all allocated resources.
132
134 Returns the ascent of the font.
135 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 See also descent().
144 Examples:
146
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 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 Note that the rectangle usually extends both above and below the base
157 line.
158 Warning: The width of the returned rectangle is not the advance width
160 of the character. Use boundingRect(const QString &) or width() instead.
161 See also width().
163 Example: xform/xform.cpp.
165
167 This is an overloaded member function, provided for convenience. It
168 behaves essentially like the above function.
169 Returns the bounding rectangle that contains the first len characters
171 of string str.
172
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 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 If len is negative (which is the default), the entire string is used.
185 The flgs argument is the bitwise OR of the following flags:
187 AlignAuto aligns to the left border for all languages except Arabic and
189 Hebrew where it aligns to the right.
190 AlignLeft aligns to the left border.
192 AlignRight aligns to the right border.
194 AlignJustify produces justified text.
196 AlignHCenter aligns horizontally centered.
198 AlignTop aligns to the top border.
200 AlignBottom aligns to the bottom border.
202 AlignVCenter aligns vertically centered
204 AlignCenter (== AlignHCenter | AlignVCenter)
206 SingleLine ignores newline characters in the text.
208 ExpandTabs expands tabs (see below)
210 ShowPrefix interprets "&x" as "<u>x</u>", i.e. underlined.
212 WordBreak breaks the text to fit the rectangle.
214 Horizontal alignment defaults to AlignAuto and vertical alignment
216 defaults to AlignTop.
217 If several of the horizontal or several of the vertical alignment flags
219 are set, the resulting alignment is undefined.
220 These flags are defined in qnamespace.h.
222 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 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 Newline characters are processed as linebreaks.
233 Despite the different actual character heights, the heights of the
235 bounding rectangles of "Yes" and "yes" are the same.
236 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 The intern argument should not be used.
245 See also width(), QPainter::boundingRect(), and Qt::AlignmentFlags.
247
249 Returns the width of the character at position pos in the string str.
250 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 This function also takes non spacing marks and ligatures into account.
256
258 Returns the descent of the font.
259 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 See also ascent().
267 Examples:
269
271 Returns the height of the font.
272 This is always equal to ascent()+descent()+1 (the 1 is for the base
274 line).
275 See also leading() and lineSpacing().
277 Examples:
279
281 Returns TRUE if character ch is a valid character in the font;
282 otherwise returns FALSE.
283 Example: qfd/fontdisplayer.cpp.
285
287 Returns the leading of the font.
288 This is the natural inter-line spacing.
290 See also height() and lineSpacing().
292
294 Returns the left bearing of character ch in the font.
295 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 See width(QChar) for a graphical description of this metric.
302 See also rightBearing(), minLeftBearing(), and width().
304 Example: qfd/fontdisplayer.cpp.
306
308 Returns the distance from one base line to the next.
309 This value is always equal to leading()+height().
311 See also height() and leading().
313 Examples:
315
317 Returns the width of the underline and strikeout lines, adjusted for
318 the point size of the font.
319 See also underlinePos(), overlinePos(), and strikeOutPos().
321
323 Returns the width of the widest character in the font.
324 Example: qfd/fontdisplayer.cpp.
326
328 Returns the minimum left bearing of the font.
329 This is the smallest leftBearing(char) of all characters in the font.
331 Note that this function can be very slow if the font is large.
333 See also minRightBearing() and leftBearing().
335 Example: qfd/fontdisplayer.cpp.
337
339 Returns the minimum right bearing of the font.
340 This is the smallest rightBearing(char) of all characters in the font.
342 Note that this function can be very slow if the font is large.
344 See also minLeftBearing() and rightBearing().
346 Example: qfd/fontdisplayer.cpp.
348
350 Assigns the font metrics fm.
351
353 Returns the distance from the base line to where an overline should be
354 drawn.
355 See also underlinePos(), strikeOutPos(), and lineWidth().
357
359 Returns the right bearing of character ch in the font.
360 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 See width() for a graphical description of this metric.
367 See also leftBearing(), minRightBearing(), and width().
369 Example: qfd/fontdisplayer.cpp.
371
373 tabstops = 0, int * tabarray = 0, QTextParag ** intern = 0 ) const
374 Returns the size in pixels of the first len characters of str.
375 If len is negative (the default), the entire string is used.
377 The flgs argument is the bitwise OR of the following flags:
379 SingleLine ignores newline characters.
381 ExpandTabs expands tabs (see below)
383 ShowPrefix interprets "&x" as "<u>x</u>", i.e. underlined.
385 WordBreak breaks the text to fit the rectangle.
387 These flags are defined in qnamespace.h.
389 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 Newline characters are processed as linebreaks.
396 Despite the different actual character heights, the heights of the
398 bounding rectangles of "Yes" and "yes" are the same.
399 The intern argument should not be used.
401 See also boundingRect().
403
405 Returns the distance from the base line to where the strikeout line
406 should be drawn.
407 See also underlinePos(), overlinePos(), and lineWidth().
409
411 Returns the distance from the base line to where an underscore should
412 be drawn.
413 See also overlinePos(), strikeOutPos(), and lineWidth().
415
417 [Image Omitted]
418 Returns the logical width of character ch in pixels. This is a distance
420 appropriate for drawing a subsequent character after ch.
421 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 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 See also boundingRect() and charWidth().
435 Examples:
437
439 This is an overloaded member function, provided for convenience. It
440 behaves essentially like the above function.
441 Returns the width of the first len characters of string str.
443
445 This is an overloaded member function, provided for convenience. It
446 behaves essentially like the above function.
447 This function is obsolete. It is provided to keep old source working.
449 We strongly advise against using it in new code.
450 Provided to aid porting from Qt 1.x.
452
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
464 Generated automatically from the source code.
465
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 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 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).
480Trolltech AS 2 February 2007 QFontMetrics(3qt)