1
/****************************************************************************
3
** Copyright (C) 1992-2005 Trolltech AS. All rights reserved.
5
** This file is part of the text module of the Qt Toolkit.
7
** This file may be distributed under the terms of the Q Public License
8
** as defined by Trolltech AS of Norway and appearing in the file
9
** LICENSE.QPL included in the packaging of this file.
11
** This file may be distributed and/or modified under the terms of the
12
** GNU General Public License version 2 as published by the Free Software
13
** Foundation and appearing in the file LICENSE.GPL included in the
14
** packaging of this file.
16
** See http://www.trolltech.com/pricing.html or email sales@trolltech.com for
17
** information about Qt Commercial License Agreements.
18
** See http://www.trolltech.com/qpl/ for QPL licensing information.
19
** See http://www.trolltech.com/gpl/ for GPL licensing information.
21
** Contact info@trolltech.com if any conditions of this licensing are
24
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
25
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
27
****************************************************************************/
30
#include "qpaintdevice.h"
31
#include "qfontmetrics.h"
34
#include "qfontengine_p.h"
35
#include <private/qunicodetables_p.h>
38
#include "qx11info_x11.h"
39
extern const QX11Info *qt_x11Info(const QPaintDevice *pd);
42
extern void qt_format_text(const QFont& font, const QRectF &_r,
43
int tf, const QString& str, QRectF *brect,
44
int tabstops, int* tabarray, int tabarraylen,
46
extern int qt_defaultDpi();
48
/*****************************************************************************
49
QFontMetrics member functions
50
*****************************************************************************/
53
\class QFontMetrics qfontmetrics.h
54
\brief The QFontMetrics class provides font metrics information.
59
QFontMetrics functions calculate the size of characters and
60
strings for a given font. There are three ways you can create a
64
\i Calling the QFontMetrics constructor with a QFont creates a
65
font metrics object for a screen-compatible font, i.e. the font
66
cannot be a printer font. If the font is changed
67
later, the font metrics object is \e not updated.
69
(Note: If you use a printer font the values returned may be
70
inaccurate. Printer fonts are not always accessible so the nearest
71
screen font is used if a printer font is supplied.)
73
\i QWidget::fontMetrics() returns the font metrics for a widget's
74
font. This is equivalent to QFontMetrics(widget->font()). If the
75
widget's font is changed later, the font metrics object is \e not
78
\i QPainter::fontMetrics() returns the font metrics for a
79
painter's current font. If the painter's font is changed later, the
80
font metrics object is \e not updated.
83
Once created, the object provides functions to access the
84
individual metrics of the font, its characters, and for strings
87
There are several functions that operate on the font: ascent(),
88
descent(), height(), leading() and lineSpacing() return the basic
89
size properties of the font. The underlinePos(), overlinePos(),
90
strikeOutPos() and lineWidth() functions, return the properties of
91
the line that underlines, overlines or strikes out the
92
characters. These functions are all fast.
94
There are also some functions that operate on the set of glyphs in
95
the font: minLeftBearing(), minRightBearing() and maxWidth().
96
These are by necessity slow, and we recommend avoiding them if
99
For each character, you can get its width(), leftBearing() and
100
rightBearing() and find out whether it is in the font using
101
inFont(). You can also treat the character as a string, and use
102
the string functions on it.
104
The string functions include width(), to return the width of a
105
string in pixels (or points, for a printer), boundingRect(), to
106
return a rectangle large enough to contain the rendered string,
107
and size(), to return the size of that rectangle.
111
QFont font("times", 24);
112
QFontMetrics fm(font);
113
int pixelsWide = fm.width("What's the width of this text?");
114
int pixelsHigh = fm.height();
117
\sa QFont QFontInfo QFontDatabase
121
\fn QRect QFontMetrics::boundingRect(int x, int y, int width, int height,
122
int flags, const QString &text, int tabstops, int *tabarray) const
125
Returns the bounding rectangle for the given \a text within the
126
rectangle specified by the \a x and \a y coordinates, \a width, and
129
If \c Qt::TextExpandTabs is set in \a flags and \a tabarray is
130
non-null, it specifies a 0-terminated sequence of pixel-positions
131
for tabs; otherwise, if \a tabstops is non-zero, it is used as the
132
tab spacing (in pixels).
136
Constructs a font metrics object for \a font.
138
The font metrics will be compatible with the paintdevice used to
141
The font metrics object holds the information for the font that is
142
passed in the constructor at the time it is created, and is not
143
updated if the font's attributes are changed later.
145
Use QFontMetrics(const QFont &, QPaintDevice *) to get the font
146
metrics that are compatible with a certain paint device.
148
QFontMetrics::QFontMetrics(const QFont &font)
155
Constructs a font metrics object for \a font and \a paintdevice.
157
The font metrics will be compatible with the paintdevice passed.
158
If the \a paintdevice is 0, the metrics will be screen-compatible,
159
ie. the metrics you get if you use the font for drawing text on a
160
\link QWidget widgets\endlink or \link QPixmap pixmaps\endlink,
161
not on a QPicture or QPrinter.
163
The font metrics object holds the information for the font that is
164
passed in the constructor at the time it is created, and is not
165
updated if the font's attributes are changed later.
167
QFontMetrics::QFontMetrics(const QFont &font, QPaintDevice *paintdevice)
169
int dpi = paintdevice ? paintdevice->logicalDpiY() : qt_defaultDpi();
171
const QX11Info *info = qt_x11Info(paintdevice);
172
int screen = info ? info->screen() : 0;
174
const int screen = 0;
176
if (font.d->dpi != dpi || font.d->screen != screen ) {
177
d = new QFontPrivate(*font.d);
188
Constructs a copy of \a fm.
190
QFontMetrics::QFontMetrics(const QFontMetrics &fm)
195
Destroys the font metrics object and frees all allocated
198
QFontMetrics::~QFontMetrics()
205
Assigns the font metrics \a fm.
207
QFontMetrics &QFontMetrics::operator=(const QFontMetrics &fm)
209
qAtomicAssign(d, fm.d);
214
Returns true if \a other is equal to this object; otherwise
217
Two font metrics are considered equal if they were constructed
218
from the same QFont and the paint devices they were constructed
219
for are considered compatible.
223
bool QFontMetrics::operator ==(const QFontMetrics &other)
229
\fn bool QFontMetrics::operator !=(const QFontMetrics &other)
231
Returns true if \a other is not equal to this object; otherwise returns false.
233
Two font metrics are considered equal if they were constructed
234
from the same QFont and the paint devices they were constructed
235
for are considered compatible.
241
Returns the ascent of the font.
243
The ascent of a font is the distance from the baseline to the
244
highest position characters extend to. In practice, some font
245
designers break this rule, e.g. when they put more than one accent
246
on top of a character, or to accommodate an unusual character in
247
an exotic language, so it is possible (though rare) that this
248
value will be too small.
252
int QFontMetrics::ascent() const
254
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
255
Q_ASSERT(engine != 0);
256
return qRound(engine->ascent());
261
Returns the descent of the font.
263
The descent is the distance from the base line to the lowest point
264
characters extend to. (Note that this is different from X, which
265
adds 1 pixel.) In practice, some font designers break this rule,
266
e.g. to accommodate an unusual character in an exotic language, so
267
it is possible (though rare) that this value will be too small.
271
int QFontMetrics::descent() const
273
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
274
Q_ASSERT(engine != 0);
275
return qRound(engine->descent());
279
Returns the height of the font.
281
This is always equal to ascent()+descent()+1 (the 1 is for the
284
\sa leading(), lineSpacing()
286
int QFontMetrics::height() const
288
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
289
Q_ASSERT(engine != 0);
290
return qRound(engine->ascent() + engine->descent()) + 1;
294
Returns the leading of the font.
296
This is the natural inter-line spacing.
298
\sa height(), lineSpacing()
300
int QFontMetrics::leading() const
302
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
303
Q_ASSERT(engine != 0);
304
return qRound(engine->leading());
308
Returns the distance from one base line to the next.
310
This value is always equal to leading()+height().
312
\sa height(), leading()
314
int QFontMetrics::lineSpacing() const
316
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
317
Q_ASSERT(engine != 0);
318
return qRound(engine->leading() + engine->ascent() + engine->descent()) + 1;
322
Returns the minimum left bearing of the font.
324
This is the smallest leftBearing(char) of all characters in the
327
Note that this function can be very slow if the font is large.
329
\sa minRightBearing(), leftBearing()
331
int QFontMetrics::minLeftBearing() const
333
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
334
Q_ASSERT(engine != 0);
335
return qRound(engine->minLeftBearing());
339
Returns the minimum right bearing of the font.
341
This is the smallest rightBearing(char) of all characters in the
344
Note that this function can be very slow if the font is large.
346
\sa minLeftBearing(), rightBearing()
348
int QFontMetrics::minRightBearing() const
350
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
351
Q_ASSERT(engine != 0);
352
return qRound(engine->minRightBearing());
356
Returns the width of the widest character in the font.
358
int QFontMetrics::maxWidth() const
360
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
361
Q_ASSERT(engine != 0);
362
return qRound(engine->maxCharWidth());
366
Returns true if character \a ch is a valid character in the font;
367
otherwise returns false.
369
bool QFontMetrics::inFont(QChar ch) const
371
const int script = QUnicodeTables::script(ch);
372
QFontEngine *engine = d->engineForScript(script);
373
Q_ASSERT(engine != 0);
374
if (engine->type() == QFontEngine::Box)
376
return engine->canRender(&ch, 1);
379
/*! \fn int QFontMetrics::leftBearing(QChar ch) const
380
Returns the left bearing of character \a ch in the font.
382
The left bearing is the right-ward distance of the left-most pixel
383
of the character from the logical origin of the character. This
384
value is negative if the pixels of the character extend to the
385
left of the logical origin.
387
See width(QChar) for a graphical description of this metric.
389
\sa rightBearing(), minLeftBearing(), width()
391
int QFontMetrics::leftBearing(QChar ch) const
393
const int script = QUnicodeTables::script(ch);
394
QFontEngine *engine = d->engineForScript(script);
395
Q_ASSERT(engine != 0);
396
if (engine->type() == QFontEngine::Box)
399
QGlyphLayout glyphs[10];
401
engine->stringToCMap(&ch, 1, glyphs, &nglyphs, 0);
402
// ### can nglyphs != 1 happen at all? Not currently I think
403
glyph_metrics_t gi = engine->boundingBox(glyphs[0].glyph);
407
/*! \fn int QFontMetrics::rightBearing(QChar ch) const
408
Returns the right bearing of character \a ch in the font.
410
The right bearing is the left-ward distance of the right-most
411
pixel of the character from the logical origin of a subsequent
412
character. This value is negative if the pixels of the character
413
extend to the right of the width() of the character.
415
See width() for a graphical description of this metric.
417
\sa leftBearing(), minRightBearing(), width()
419
int QFontMetrics::rightBearing(QChar ch) const
421
const int script = QUnicodeTables::script(ch);
422
QFontEngine *engine = d->engineForScript(script);
423
Q_ASSERT(engine != 0);
424
if (engine->type() == QFontEngine::Box)
427
QGlyphLayout glyphs[10];
429
engine->stringToCMap(&ch, 1, glyphs, &nglyphs, 0);
430
// ### can nglyphs != 1 happen at all? Not currently I think
431
glyph_metrics_t gi = engine->boundingBox(glyphs[0].glyph);
432
return qRound(gi.xoff - gi.x - gi.width);
436
Returns the width in pixels of the first \a len characters of \a
437
str. If \a len is negative (the default), the entire string is
440
Note that this value is \e not equal to boundingRect().width();
441
boundingRect() returns a rectangle describing the pixels this
442
string will cover whereas width() returns the distance to where
443
the next string should be drawn.
447
int QFontMetrics::width(const QString &str, int len) const
454
QTextEngine layout(str, d);
455
layout.ignoreBidi = true;
457
return qRound(layout.width(0, len));
460
/*! \fn int QFontMetrics::width(QChar ch) const
464
\img bearings.png Bearings
466
Returns the logical width of character \a ch in pixels. This is a
467
distance appropriate for drawing a subsequent character after \a
470
Some of the metrics are described in the image to the right. The
471
central dark rectangles cover the logical width() of each
472
character. The outer pale rectangles cover the leftBearing() and
473
rightBearing() of each character. Notice that the bearings of "f"
474
in this particular font are both negative, while the bearings of
475
"o" are both positive.
477
\warning This function will produce incorrect results for Arabic
478
characters or non-spacing marks in the middle of a string, as the
479
glyph shaping and positioning of marks that happens when
480
processing strings cannot be taken into account. Use charWidth()
481
instead if you aren't looking for the width of isolated
484
\sa boundingRect(), charWidth()
486
int QFontMetrics::width(QChar ch) const
488
if (::category(ch) == QChar::Mark_NonSpacing)
491
const int script = QUnicodeTables::script(ch);
492
QFontEngine *engine = d->engineForScript(script);
493
Q_ASSERT(engine != 0);
495
QGlyphLayout glyphs[8];
497
engine->stringToCMap(&ch, 1, glyphs, &nglyphs, 0);
498
return qRound(glyphs[0].advance.x());
502
Returns the width of the character at position \a pos in the
505
The whole string is needed, as the glyph drawn may change
506
depending on the context (the letter before and after the current
507
one) for some languages (e.g. Arabic).
509
This function also takes non spacing marks and ligatures into
512
int QFontMetrics::charWidth(const QString &str, int pos) const
514
if (pos < 0 || pos > (int)str.length())
517
const QChar &ch = str.unicode()[pos];
518
const int script = QUnicodeTables::script(ch);
521
if (script != QUnicodeTables::Common) {
522
// complex script shaping. Have to do some hard work
523
int from = qMax(0, pos - 8);
524
int to = qMin((int)str.length(), pos + 8);
525
QString cstr = QString::fromRawData(str.unicode()+from, to-from);
526
QTextEngine layout(cstr, d);
527
layout.ignoreBidi = true;
529
width = qRound(layout.width(pos-from, 1));
530
} else if (::category(ch) == QChar::Mark_NonSpacing) {
533
QFontEngine *engine = d->engineForScript(script);
534
Q_ASSERT(engine != 0);
536
QGlyphLayout glyphs[8];
538
engine->stringToCMap(&ch, 1, glyphs, &nglyphs, 0);
539
width = qRound(glyphs[0].advance.x());
545
Returns the bounding rectangle of the characters in the string
546
specified by \a str, which is the set of pixels the text would
547
cover if drawn at (0, 0).
549
Note that the bounding rectangle may extend to the left of (0, 0),
550
e.g. for italicized fonts, and that the text output may cover \e
551
all pixels in the bounding rectangle.
553
Newline characters are processed as normal characters, \e not as
556
Due to the different actual character heights, the height of the
557
bounding rectangle of e.g. "Yes" and "yes" may be different.
559
\sa width(), QPainter::boundingRect()
561
QRect QFontMetrics::boundingRect(const QString &str) const
563
if (str.length() == 0)
566
QTextEngine layout(str, d);
567
layout.ignoreBidi = true;
569
glyph_metrics_t gm = layout.boundingBox(0, str.length());
570
return QRect(qRound(gm.x), qRound(gm.y), qRound(gm.width), qRound(gm.height));
574
Returns the bounding rectangle of the character \a ch relative to
575
the left-most point on the base line.
577
Note that the bounding rectangle may extend to the left of (0, 0),
578
e.g. for italicized fonts, and that the text output may cover \e
579
all pixels in the bounding rectangle.
581
Note that the rectangle usually extends both above and below the
586
QRect QFontMetrics::boundingRect(QChar ch) const
588
const int script = QUnicodeTables::script(ch);
589
QFontEngine *engine = d->engineForScript(script);
590
Q_ASSERT(engine != 0);
592
QGlyphLayout glyphs[10];
594
engine->stringToCMap(&ch, 1, glyphs, &nglyphs, 0);
595
glyph_metrics_t gm = engine->boundingBox(glyphs[0].glyph);
596
return QRect(qRound(gm.x), qRound(gm.y), qRound(gm.width), qRound(gm.height));
602
Returns the bounding rectangle of the characters in the string
603
specified by \a str, which is the set of pixels the text would
604
cover if drawn at (0, 0). The drawing, and hence the bounding
605
rectangle, is constrained to the rectangle \a r.
607
The \a flgs argument is the bitwise OR of the following flags:
609
\i \c Qt::AlignLeft aligns to the left border, except for
610
Arabic and Hebrew where it aligns to the right.
611
\i \c Qt::AlignRight aligns to the right border, except for
612
Arabic and Hebrew where it aligns to the left.
613
\i \c Qt::AlignJustify produces justified text.
614
\i \c Qt::AlignHCenter aligns horizontally centered.
615
\i \c Qt::AlignTop aligns to the top border.
616
\i \c Qt::AlignBottom aligns to the bottom border.
617
\i \c Qt::AlignVCenter aligns vertically centered
618
\i \c Qt::AlignCenter (== \c{Qt::AlignHCenter | Qt::AlignVCenter})
619
\i \c Qt::TextSingleLine ignores newline characters in the text.
620
\i \c Qt::TextExpandTabs expands tabs (see below)
621
\i \c Qt::TextShowMnemonic interprets "&x" as \underline{x}, i.e. underlined.
622
\i \c Qt::TextWordBreak breaks the text to fit the rectangle.
625
Qt::Horizontal alignment defaults to \c Qt::AlignLeft and vertical
626
alignment defaults to \c Qt::AlignTop.
628
If several of the horizontal or several of the vertical alignment
629
flags are set, the resulting alignment is undefined.
631
These flags are defined in \c qnamespace.h.
633
If \c Qt::TextExpandTabs is set in \a flgs, then: if \a tabarray is
634
non-null, it specifies a 0-terminated sequence of pixel-positions
635
for tabs; otherwise if \a tabstops is non-zero, it is used as the
636
tab spacing (in pixels).
638
Note that the bounding rectangle may extend to the left of (0, 0),
639
e.g. for italicized fonts, and that the text output may cover \e
640
all pixels in the bounding rectangle.
642
Newline characters are processed as linebreaks.
644
Despite the different actual character heights, the heights of the
645
bounding rectangles of "Yes" and "yes" are the same.
647
The bounding rectangle returned by this function is somewhat larger
648
than that calculated by the simpler boundingRect() function. This
649
function uses the \link minLeftBearing() maximum left \endlink and
650
\link minRightBearing() right \endlink font bearings as is
651
necessary for multi-line text to align correctly. Also,
652
fontHeight() and lineSpacing() are used to calculate the height,
653
rather than individual character heights.
655
\sa width(), QPainter::boundingRect(), Qt::Alignment
657
QRect QFontMetrics::boundingRect(const QRect &r, int flgs, const QString& str, int tabstops, int *tabarray) const
661
while (tabarray[tabarraylen])
666
qt_format_text(QFont(d), rr, flgs|Qt::TextDontPrint, str, &rb, tabstops, tabarray, tabarraylen, 0);
672
Returns the size in pixels of \a text.
674
The \a flgs argument is the bitwise OR of the following flags:
676
\i \c Qt::TextSingleLine ignores newline characters.
677
\i \c Qt::TextExpandTabs expands tabs (see below)
678
\i \c Qt::TextShowMnemonic interprets "&x" as \underline{x}, i.e. underlined.
679
\i \c Qt::TextWordBreak breaks the text to fit the rectangle.
682
These flags are defined in \c qnamespace.h.
684
If \c Qt::TextExpandTabs is set in \a flgs, then: if \a tabarray is
685
non-null, it specifies a 0-terminated sequence of pixel-positions
686
for tabs; otherwise if \a tabstops is non-zero, it is used as the
687
tab spacing (in pixels).
689
Newline characters are processed as linebreaks.
691
Despite the different actual character heights, the heights of the
692
bounding rectangles of "Yes" and "yes" are the same.
696
QSize QFontMetrics::size(int flgs, const QString &text, int tabstops, int *tabarray) const
698
return boundingRect(QRect(0,0,0,0), flgs, text, tabstops, tabarray).size();
702
Returns the distance from the base line to where an underscore
705
\sa overlinePos(), strikeOutPos(), lineWidth()
707
int QFontMetrics::underlinePos() const
709
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
710
Q_ASSERT(engine != 0);
712
return qRound(engine->underlinePosition());
716
Returns the distance from the base line to where an overline
719
\sa underlinePos(), strikeOutPos(), lineWidth()
721
int QFontMetrics::overlinePos() const
727
Returns the distance from the base line to where the strikeout
728
line should be drawn.
730
\sa underlinePos(), overlinePos(), lineWidth()
732
int QFontMetrics::strikeOutPos() const
734
int pos = ascent() / 3;
735
return pos > 0 ? pos : 1;
739
Returns the width of the underline and strikeout lines, adjusted
740
for the point size of the font.
742
\sa underlinePos(), overlinePos(), strikeOutPos()
744
int QFontMetrics::lineWidth() const
746
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
747
Q_ASSERT(engine != 0);
748
return qRound(engine->lineThickness());
754
/*****************************************************************************
755
QFontMetricsF member functions
756
*****************************************************************************/
759
\class QFontMetricsF qfontmetrics.h
760
\brief The QFontMetricsF class provides font metrics information.
765
QFontMetricsF functions calculate the size of characters and
766
strings for a given font. There are three ways you can create a
767
QFontMetricsF object:
770
\i Calling the QFontMetricsF constructor with a QFont creates a
771
font metrics object for a screen-compatible font, i.e. the font
772
cannot be a printer font. If the font is changed
773
later, the font metrics object is \e not updated.
775
(Note: If you use a printer font the values returned may be
776
inaccurate. Printer fonts are not always accessible so the nearest
777
screen font is used if a printer font is supplied.)
779
\i QWidget::fontMetrics() returns the font metrics for a widget's
780
font. This is equivalent to QFontMetricsF(widget->font()). If the
781
widget's font is changed later, the font metrics object is \e not
784
\i QPainter::fontMetrics() returns the font metrics for a
785
painter's current font. If the painter's font is changed later, the
786
font metrics object is \e not updated.
789
Once created, the object provides functions to access the
790
individual metrics of the font, its characters, and for strings
791
rendered in the font.
793
There are several functions that operate on the font: ascent(),
794
descent(), height(), leading() and lineSpacing() return the basic
795
size properties of the font. The underlinePos(), overlinePos(),
796
strikeOutPos() and lineWidth() functions, return the properties of
797
the line that underlines, overlines or strikes out the
798
characters. These functions are all fast.
800
There are also some functions that operate on the set of glyphs in
801
the font: minLeftBearing(), minRightBearing() and maxWidth().
802
These are by necessity slow, and we recommend avoiding them if
805
For each character, you can get its width(), leftBearing() and
806
rightBearing() and find out whether it is in the font using
807
inFont(). You can also treat the character as a string, and use
808
the string functions on it.
810
The string functions include width(), to return the width of a
811
string in pixels (or points, for a printer), boundingRect(), to
812
return a rectangle large enough to contain the rendered string,
813
and size(), to return the size of that rectangle.
817
QFont font("times", 24);
818
QFontMetricsF fm(font);
819
int pixelsWide = fm.width("What's the width of this text?");
820
int pixelsHigh = fm.height();
823
\sa QFont QFontInfo QFontDatabase
827
\fn QFontMetricsF::QFontMetricsF(const QFontMetrics &fontMetrics)
829
Constructs a font metrics object with floating point precision
830
from the given \a fontMetrics object.
834
\fn QFontMetricsF &QFontMetricsF::operator=(const QFontMetrics &fontMetrics)
836
Assigns \a fontMetrics to this font metrics object.
840
Constructs a font metrics object for \a font.
842
The font metrics will be compatible with the paintdevice used to
845
The font metrics object holds the information for the font that is
846
passed in the constructor at the time it is created, and is not
847
updated if the font's attributes are changed later.
849
Use QFontMetricsF(const QFont &, QPaintDevice *) to get the font
850
metrics that are compatible with a certain paint device.
852
QFontMetricsF::QFontMetricsF(const QFont &font)
859
Constructs a font metrics object for \a font and \a paintdevice.
861
The font metrics will be compatible with the paintdevice passed.
862
If the \a paintdevice is 0, the metrics will be screen-compatible,
863
ie. the metrics you get if you use the font for drawing text on a
864
\link QWidget widgets\endlink or \link QPixmap pixmaps\endlink,
865
not on a QPicture or QPrinter.
867
The font metrics object holds the information for the font that is
868
passed in the constructor at the time it is created, and is not
869
updated if the font's attributes are changed later.
871
QFontMetricsF::QFontMetricsF(const QFont &font, QPaintDevice *paintdevice)
873
int dpi = paintdevice ? paintdevice->logicalDpiY() : qt_defaultDpi();
875
int screen = paintdevice ? qt_x11Info(paintdevice)->screen() : 0;
877
const int screen = 0;
879
if (font.d->dpi != dpi || font.d->screen != screen ) {
880
d = new QFontPrivate(*font.d);
891
Constructs a copy of \a fm.
893
QFontMetricsF::QFontMetricsF(const QFontMetricsF &fm)
898
Destroys the font metrics object and frees all allocated
901
QFontMetricsF::~QFontMetricsF()
908
Assigns the font metrics \a fm to this font metrics object.
910
QFontMetricsF &QFontMetricsF::operator=(const QFontMetricsF &fm)
912
qAtomicAssign(d, fm.d);
917
Returns true if the font metrics are equal to the \a other font
918
metrics; otherwise returns false.
920
Two font metrics are considered equal if they were constructed from the
921
same QFont and the paint devices they were constructed for are
922
considered to be compatible.
924
bool QFontMetricsF::operator ==(const QFontMetricsF &other)
930
\fn bool QFontMetricsF::operator !=(const QFontMetricsF &other);
932
Returns true if the font metrics are not equal to the \a other font
933
metrics; otherwise returns false.
939
Returns the ascent of the font.
941
The ascent of a font is the distance from the baseline to the
942
highest position characters extend to. In practice, some font
943
designers break this rule, e.g. when they put more than one accent
944
on top of a character, or to accommodate an unusual character in
945
an exotic language, so it is possible (though rare) that this
946
value will be too small.
950
qreal QFontMetricsF::ascent() const
952
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
953
Q_ASSERT(engine != 0);
954
return engine->ascent();
959
Returns the descent of the font.
961
The descent is the distance from the base line to the lowest point
962
characters extend to. (Note that this is different from X, which
963
adds 1 pixel.) In practice, some font designers break this rule,
964
e.g. to accommodate an unusual character in an exotic language, so
965
it is possible (though rare) that this value will be too small.
969
qreal QFontMetricsF::descent() const
971
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
972
Q_ASSERT(engine != 0);
973
return engine->descent();
977
Returns the height of the font.
979
This is always equal to ascent()+descent()+1 (the 1 is for the
982
\sa leading(), lineSpacing()
984
qreal QFontMetricsF::height() const
986
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
987
Q_ASSERT(engine != 0);
989
return engine->ascent() + engine->descent() + 1.0;
993
Returns the leading of the font.
995
This is the natural inter-line spacing.
997
\sa height(), lineSpacing()
999
qreal QFontMetricsF::leading() const
1001
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
1002
Q_ASSERT(engine != 0);
1003
return engine->leading();
1007
Returns the distance from one base line to the next.
1009
This value is always equal to leading()+height().
1011
\sa height(), leading()
1013
qreal QFontMetricsF::lineSpacing() const
1015
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
1016
Q_ASSERT(engine != 0);
1017
return engine->leading() + engine->ascent() + engine->descent() + 1.0;
1021
Returns the minimum left bearing of the font.
1023
This is the smallest leftBearing(char) of all characters in the
1026
Note that this function can be very slow if the font is large.
1028
\sa minRightBearing(), leftBearing()
1030
qreal QFontMetricsF::minLeftBearing() const
1032
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
1033
Q_ASSERT(engine != 0);
1034
return engine->minLeftBearing();
1038
Returns the minimum right bearing of the font.
1040
This is the smallest rightBearing(char) of all characters in the
1043
Note that this function can be very slow if the font is large.
1045
\sa minLeftBearing(), rightBearing()
1047
qreal QFontMetricsF::minRightBearing() const
1049
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
1050
Q_ASSERT(engine != 0);
1051
return engine->minRightBearing();
1055
Returns the width of the widest character in the font.
1057
qreal QFontMetricsF::maxWidth() const
1059
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
1060
Q_ASSERT(engine != 0);
1061
return engine->maxCharWidth();
1065
Returns true if character \a ch is a valid character in the font;
1066
otherwise returns false.
1068
bool QFontMetricsF::inFont(QChar ch) const
1070
const int script = QUnicodeTables::script(ch);
1071
QFontEngine *engine = d->engineForScript(script);
1072
Q_ASSERT(engine != 0);
1073
if (engine->type() == QFontEngine::Box)
1075
return engine->canRender(&ch, 1);
1078
/*! \fn int QFontMetricsF::leftBearing(QChar ch) const
1079
Returns the left bearing of character \a ch in the font.
1081
The left bearing is the right-ward distance of the left-most pixel
1082
of the character from the logical origin of the character. This
1083
value is negative if the pixels of the character extend to the
1084
left of the logical origin.
1086
See width(QChar) for a graphical description of this metric.
1088
\sa rightBearing(), minLeftBearing(), width()
1090
qreal QFontMetricsF::leftBearing(QChar ch) const
1092
const int script = QUnicodeTables::script(ch);
1093
QFontEngine *engine = d->engineForScript(script);
1094
Q_ASSERT(engine != 0);
1095
if (engine->type() == QFontEngine::Box)
1098
QGlyphLayout glyphs[10];
1100
engine->stringToCMap(&ch, 1, glyphs, &nglyphs, 0);
1101
// ### can nglyphs != 1 happen at all? Not currently I think
1102
glyph_metrics_t gi = engine->boundingBox(glyphs[0].glyph);
1106
/*! \fn int QFontMetricsF::rightBearing(QChar ch) const
1107
Returns the right bearing of character \a ch in the font.
1109
The right bearing is the left-ward distance of the right-most
1110
pixel of the character from the logical origin of a subsequent
1111
character. This value is negative if the pixels of the character
1112
extend to the right of the width() of the character.
1114
See width() for a graphical description of this metric.
1116
\sa leftBearing(), minRightBearing(), width()
1118
qreal QFontMetricsF::rightBearing(QChar ch) const
1120
const int script = QUnicodeTables::script(ch);
1121
QFontEngine *engine = d->engineForScript(script);
1122
Q_ASSERT(engine != 0);
1123
if (engine->type() == QFontEngine::Box)
1126
QGlyphLayout glyphs[10];
1128
engine->stringToCMap(&ch, 1, glyphs, &nglyphs, 0);
1129
// ### can nglyphs != 1 happen at all? Not currently I think
1130
glyph_metrics_t gi = engine->boundingBox(glyphs[0].glyph);
1131
return gi.xoff - gi.x - gi.width;
1135
\fn qreal QFontMetricsF::width(const QString &text) const
1137
Returns the width in pixels of the characters in the given \a text.
1139
Note that this value is \e not equal to the width returned by
1140
boundingRect().width() because boundingRect() returns a rectangle
1141
describing the pixels this string will cover whereas width()
1142
returns the distance to where the next string should be drawn.
1146
qreal QFontMetricsF::width(const QString &str) const
1148
QTextEngine layout(str, d);
1149
layout.ignoreBidi = true;
1151
return layout.width(0, str.length());
1154
/*! \fn int QFontMetricsF::width(QChar ch) const
1158
\img bearings.png Bearings
1160
Returns the logical width of character \a ch in pixels. This is a
1161
distance appropriate for drawing a subsequent character after \a
1164
Some of the metrics are described in the image to the right. The
1165
central dark rectangles cover the logical width() of each
1166
character. The outer pale rectangles cover the leftBearing() and
1167
rightBearing() of each character. Notice that the bearings of "f"
1168
in this particular font are both negative, while the bearings of
1169
"o" are both positive.
1171
\warning This function will produce incorrect results for Arabic
1172
characters or non-spacing marks in the middle of a string, as the
1173
glyph shaping and positioning of marks that happens when
1174
processing strings cannot be taken into account. Use charWidth()
1175
instead if you aren't looking for the width of isolated
1180
qreal QFontMetricsF::width(QChar ch) const
1182
if (::category(ch) == QChar::Mark_NonSpacing)
1185
const int script = QUnicodeTables::script(ch);
1186
QFontEngine *engine = d->engineForScript(script);
1187
Q_ASSERT(engine != 0);
1189
QGlyphLayout glyphs[8];
1191
engine->stringToCMap(&ch, 1, glyphs, &nglyphs, 0);
1192
return glyphs[0].advance.x();
1196
\fn QRectF QFontMetricsF::boundingRect(const QString &text) const
1198
Returns the bounding rectangle of the characters in the given
1199
\a text. This is the set of pixels the text would cover if drawn
1202
Note that the bounding rectangle may extend to the left of (0, 0),
1203
e.g. for italicized fonts, and that the text output may cover \e
1204
all pixels in the bounding rectangle.
1206
Newline characters are processed as normal characters, \e not as
1209
Due to the different actual character heights, the height of the
1210
bounding rectangle of e.g. "Yes" and "yes" may be different.
1212
\sa width(), QPainter::boundingRect()
1214
QRectF QFontMetricsF::boundingRect(const QString &str) const
1216
int len = str.length();
1220
QTextEngine layout(str, d);
1221
layout.ignoreBidi = true;
1223
glyph_metrics_t gm = layout.boundingBox(0, len);
1224
return QRectF(gm.x, gm.y, gm.width, gm.height);
1228
Returns the bounding rectangle of the character \a ch relative to
1229
the left-most point on the base line.
1231
Note that the bounding rectangle may extend to the left of (0, 0),
1232
e.g. for italicized fonts, and that the text output may cover \e
1233
all pixels in the bounding rectangle.
1235
Note that the rectangle usually extends both above and below the
1240
QRectF QFontMetricsF::boundingRect(QChar ch) const
1242
const int script = QUnicodeTables::script(ch);
1243
QFontEngine *engine = d->engineForScript(script);
1244
Q_ASSERT(engine != 0);
1246
QGlyphLayout glyphs[10];
1248
engine->stringToCMap(&ch, 1, glyphs, &nglyphs, 0);
1249
glyph_metrics_t gm = engine->boundingBox(glyphs[0].glyph);
1250
return QRectF(gm.x, gm.y, gm.width, gm.height);
1254
\fn QRectF QFontMetricsF::boundingRect(const QRectF &rect, int flags, const QString &text, int tabstops, int *tabarray) const
1257
Returns the bounding rectangle of the characters in the given \a text.
1258
This is the set of pixels the text would cover if drawn when constrained
1259
to the bounding rectangle specified by \a rect.
1261
The \a flags argument is the bitwise OR of the following flags:
1263
\i \c Qt::AlignLeft aligns to the left border, except for
1264
Arabic and Hebrew where it aligns to the right.
1265
\i \c Qt::AlignRight aligns to the right border, except for
1266
Arabic and Hebrew where it aligns to the left.
1267
\i \c Qt::AlignJustify produces justified text.
1268
\i \c Qt::AlignHCenter aligns horizontally centered.
1269
\i \c Qt::AlignTop aligns to the top border.
1270
\i \c Qt::AlignBottom aligns to the bottom border.
1271
\i \c Qt::AlignVCenter aligns vertically centered
1272
\i \c Qt::AlignCenter (== \c{Qt::AlignHCenter | Qt::AlignVCenter})
1273
\i \c Qt::TextSingleLine ignores newline characters in the text.
1274
\i \c Qt::TextExpandTabs expands tabs (see below)
1275
\i \c Qt::TextShowMnemonic interprets "&x" as \underline{x}, i.e. underlined.
1276
\i \c Qt::TextWordBreak breaks the text to fit the rectangle.
1279
Qt::Horizontal alignment defaults to \c Qt::AlignLeft and vertical
1280
alignment defaults to \c Qt::AlignTop.
1282
If several of the horizontal or several of the vertical alignment
1283
flags are set, the resulting alignment is undefined.
1285
These flags are defined in \l{Qt::AlignmentFlag}.
1287
If \c Qt::TextExpandTabs is set in \a flags, the following behavior is
1288
used to interpret tab characters in the text:
1290
\i If \a tabarray is non-null, it specifies a 0-terminated sequence of
1291
pixel-positions for tabs in the text.
1292
\i If \a tabstops is non-zero, it is used as the tab spacing (in pixels).
1295
Note that the bounding rectangle may extend to the left of (0, 0),
1296
e.g. for italicized fonts.
1298
Newline characters are processed as line breaks.
1300
Despite the different actual character heights, the heights of the
1301
bounding rectangles of "Yes" and "yes" are the same.
1303
The bounding rectangle returned by this function is somewhat larger
1304
than that calculated by the simpler boundingRect() function. This
1305
function uses the \link minLeftBearing() maximum left \endlink and
1306
\link minRightBearing() right \endlink font bearings as is
1307
necessary for multi-line text to align correctly. Also,
1308
fontHeight() and lineSpacing() are used to calculate the height,
1309
rather than individual character heights.
1311
\sa width(), QPainter::boundingRect(), Qt::Alignment
1313
QRectF QFontMetricsF::boundingRect(const QRectF &r, int flgs, const QString& str,
1314
int tabstops, int *tabarray) const
1318
while (tabarray[tabarraylen])
1322
qt_format_text(QFont(d), r, flgs|Qt::TextDontPrint, str, &rb, tabstops, tabarray, tabarraylen, 0);
1328
\fn QSizeF QFontMetricsF::size(int flags, const QString &text, int tabstops, int *tabarray) const
1330
Returns the size in pixels of the characters in the given \a text.
1332
The \a flags argument is the bitwise OR of the following flags:
1334
\i \c Qt::TextSingleLine ignores newline characters.
1335
\i \c Qt::TextExpandTabs expands tabs (see below)
1336
\i \c Qt::TextShowMnemonic interprets "&x" as \underline{x}, i.e. underlined.
1337
\i \c Qt::TextWordBreak breaks the text to fit the rectangle.
1340
These flags are defined in \l{Qt::TextFlags}.
1342
If \c Qt::TextExpandTabs is set in \a flags, the following behavior is
1343
used to interpret tab characters in the text:
1345
\i If \a tabarray is non-null, it specifies a 0-terminated sequence of
1346
pixel-positions for tabs in the text.
1347
\i If \a tabstops is non-zero, it is used as the tab spacing (in pixels).
1350
Newline characters are processed as line breaks.
1352
Note: Despite the different actual character heights, the heights of the
1353
bounding rectangles of "Yes" and "yes" are the same.
1357
QSizeF QFontMetricsF::size(int flgs, const QString &str, int tabstops, int *tabarray) const
1359
return boundingRect(QRectF(), flgs, str, tabstops, tabarray).size();
1363
Returns the distance from the base line to where an underscore
1366
\sa overlinePos(), strikeOutPos(), lineWidth()
1368
qreal QFontMetricsF::underlinePos() const
1370
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
1371
Q_ASSERT(engine != 0);
1372
return engine->underlinePosition();
1376
Returns the distance from the base line to where an overline
1379
\sa underlinePos(), strikeOutPos(), lineWidth()
1381
qreal QFontMetricsF::overlinePos() const
1383
return ascent() + 1;
1387
Returns the distance from the base line to where the strikeout
1388
line should be drawn.
1390
\sa underlinePos(), overlinePos(), lineWidth()
1392
qreal QFontMetricsF::strikeOutPos() const
1394
return ascent() / 3.;
1398
Returns the width of the underline and strikeout lines, adjusted
1399
for the point size of the font.
1401
\sa underlinePos(), overlinePos(), strikeOutPos()
1403
qreal QFontMetricsF::lineWidth() const
1405
QFontEngine *engine = d->engineForScript(QUnicodeTables::Common);
1406
Q_ASSERT(engine != 0);
1407
return engine->lineThickness();
1411
\fn QSize QFontMetrics::size(int flags, const QString &str, int len,
1412
int tabstops, int *tabarray) const
1417
\fn QRect QFontMetrics::boundingRect(int x, int y, int w, int h, int flags,
1418
const QString& str, int len, int tabstops, int *tabarray) const
1423
\fn QRect QFontMetrics::boundingRect(const QString &text, int len) const
added
removed
src/gui/text/qfontmetrics.cpp
