1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtGui module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
44 #if !defined(QT_NO_RAWFONT)
46 #include "qglyphrun.h"
47 #include "qglyphrun_p.h"
54 \brief The QGlyphRun class provides direct access to the internal glyphs in a font.
60 When Qt displays a string of text encoded in Unicode, it will first convert the Unicode points
61 into a list of glyph indexes and a list of positions based on one or more fonts. The Unicode
62 representation of the text and the QFont object will in this case serve as a convenient
63 abstraction that hides the details of what actually takes place when displaying the text
64 on-screen. For instance, by the time the text actually reaches the screen, it may be represented
65 by a set of fonts in addition to the one specified by the user, e.g. in case the originally
66 selected font did not support all the writing systems contained in the text.
68 Under certain circumstances, it can be useful as an application developer to have more low-level
69 control over which glyphs in a specific font are drawn to the screen. This could for instance
70 be the case in applications that use an external font engine and text shaper together with Qt.
71 QGlyphRun provides an interface to the raw data needed to get text on the screen. It
72 contains a list of glyph indexes, a position for each glyph and a font.
74 It is the user's responsibility to ensure that the selected font actually contains the
75 provided glyph indexes.
77 QTextLayout::glyphRuns() or QTextFragment::glyphRuns() can be used to convert unicode encoded
78 text into a list of QGlyphRun objects, and QPainter::drawGlyphRun() can be used to draw the
81 \note Please note that QRawFont is considered local to the thread in which it is constructed.
82 This in turn means that a new QRawFont will have to be created and set on the QGlyphRun if it is
83 moved to a different thread. If the QGlyphRun contains a reference to a QRawFont from a different
84 thread than the current, it will not be possible to draw the glyphs using a QPainter, as the
85 QRawFont is considered invalid and inaccessible in this case.
89 \enum QGlyphRun::GlyphRunFlag
92 This enum describes flags that alter the way the run of glyphs might be presented or behave in
93 a visual layout. The layout which generates the glyph runs can set these flags based on relevant
94 internal data, to retain information needed to present the text as intended by the user of the
97 \value Overline Indicates that the glyphs should be visualized together with an overline.
98 \value Underline Indicates that the glyphs should be visualized together with an underline.
99 \value StrikeOut Indicates that the glyphs should be struck out visually.
100 \value RightToLeft Indicates that the glyphs are ordered right to left. This can affect the
101 positioning of other screen elements that are relative to the glyph run, such as an inline
103 \value SplitLigature Indicates that the glyph run splits a ligature glyph. This means
104 that a ligature glyph is included in the run, but the characters represented by it corresponds
105 only to part of that ligature. The glyph run's boundingRect() function can in this case be used
106 to retrieve the area covered by glyphs that correspond to the characters represented by the
107 glyph run. When visualizing the glyphs, care needs to be taken to clip to this bounding rect to
108 ensure that only the corresponding part of the ligature is painted. In particular, this can be
109 the case when retrieving a glyph run from a QTextLayout for a specific character range, e.g.
110 when retrieving the selected area of a QTextLayout.
114 Constructs an empty QGlyphRun object.
116 QGlyphRun::QGlyphRun() : d(new QGlyphRunPrivate)
121 Constructs a QGlyphRun object which is a copy of \a other.
123 QGlyphRun::QGlyphRun(const QGlyphRun &other)
129 Destroys the QGlyphRun.
131 QGlyphRun::~QGlyphRun()
133 // Required for QExplicitlySharedDataPointer
139 void QGlyphRun::detach()
141 if (d->ref.load() != 1)
146 Assigns \a other to this QGlyphRun object.
148 QGlyphRun &QGlyphRun::operator=(const QGlyphRun &other)
155 Compares \a other to this QGlyphRun object. Returns true if the list of glyph indexes,
156 the list of positions and the font are all equal, otherwise returns false.
158 bool QGlyphRun::operator==(const QGlyphRun &other) const
163 if ((d->glyphIndexDataSize != other.d->glyphIndexDataSize)
164 || (d->glyphPositionDataSize != other.d->glyphPositionDataSize)) {
168 if (d->glyphIndexData != other.d->glyphIndexData) {
169 for (int i = 0; i < d->glyphIndexDataSize; ++i) {
170 if (d->glyphIndexData[i] != other.d->glyphIndexData[i])
174 if (d->glyphPositionData != other.d->glyphPositionData) {
175 for (int i = 0; i < d->glyphPositionDataSize; ++i) {
176 if (d->glyphPositionData[i] != other.d->glyphPositionData[i])
181 return (d->flags == other.d->flags && d->rawFont == other.d->rawFont);
185 \fn bool QGlyphRun::operator!=(const QGlyphRun &other) const
187 Compares \a other to this QGlyphRun object. Returns true if any of the list of glyph
188 indexes, the list of positions or the font are different, otherwise returns false.
192 Returns the font selected for this QGlyphRun object.
196 QRawFont QGlyphRun::rawFont() const
202 Sets the font in which to look up the glyph indexes to the \a rawFont
205 \sa rawFont(), setGlyphIndexes()
207 void QGlyphRun::setRawFont(const QRawFont &rawFont)
210 d->rawFont = rawFont;
214 Returns the glyph indexes for this QGlyphRun object.
216 \sa setGlyphIndexes(), setPositions()
218 QVector<quint32> QGlyphRun::glyphIndexes() const
220 if (d->glyphIndexes.constData() == d->glyphIndexData) {
221 return d->glyphIndexes;
223 QVector<quint32> indexes(d->glyphIndexDataSize);
224 memcpy(indexes.data(), d->glyphIndexData, d->glyphIndexDataSize * sizeof(quint32));
230 Set the glyph indexes for this QGlyphRun object to \a glyphIndexes. The glyph indexes must
231 be valid for the selected font.
233 void QGlyphRun::setGlyphIndexes(const QVector<quint32> &glyphIndexes)
236 d->glyphIndexes = glyphIndexes; // Keep a reference to the QVector to avoid copying
237 d->glyphIndexData = glyphIndexes.constData();
238 d->glyphIndexDataSize = glyphIndexes.size();
242 Returns the position of the edge of the baseline for each glyph in this set of glyph indexes.
244 QVector<QPointF> QGlyphRun::positions() const
246 if (d->glyphPositions.constData() == d->glyphPositionData) {
247 return d->glyphPositions;
249 QVector<QPointF> glyphPositions(d->glyphPositionDataSize);
250 memcpy(glyphPositions.data(), d->glyphPositionData,
251 d->glyphPositionDataSize * sizeof(QPointF));
252 return glyphPositions;
257 Sets the positions of the edge of the baseline for each glyph in this set of glyph indexes to
260 void QGlyphRun::setPositions(const QVector<QPointF> &positions)
263 d->glyphPositions = positions; // Keep a reference to the vector to avoid copying
264 d->glyphPositionData = positions.constData();
265 d->glyphPositionDataSize = positions.size();
269 Clears all data in the QGlyphRun object.
271 void QGlyphRun::clear()
274 d->rawFont = QRawFont();
277 setPositions(QVector<QPointF>());
278 setGlyphIndexes(QVector<quint32>());
282 Sets the glyph indexes and positions of this QGlyphRun to use the first \a size
283 elements in the arrays \a glyphIndexArray and \a glyphPositionArray. The data is
284 \e not copied. The caller must guarantee that the arrays are not deleted as long
285 as this QGlyphRun and any copies of it exists.
287 \sa setGlyphIndexes(), setPositions()
289 void QGlyphRun::setRawData(const quint32 *glyphIndexArray, const QPointF *glyphPositionArray,
293 d->glyphIndexes.clear();
294 d->glyphPositions.clear();
296 d->glyphIndexData = glyphIndexArray;
297 d->glyphPositionData = glyphPositionArray;
298 d->glyphIndexDataSize = d->glyphPositionDataSize = size;
302 Returns true if this QGlyphRun should be painted with an overline decoration.
304 \sa setOverline(), flags()
306 bool QGlyphRun::overline() const
308 return d->flags & Overline;
312 Indicates that this QGlyphRun should be painted with an overline decoration if \a overline is true.
313 Otherwise the QGlyphRun should be painted with no overline decoration.
315 \sa overline(), setFlag(), setFlags()
317 void QGlyphRun::setOverline(bool overline)
319 setFlag(Overline, overline);
323 Returns true if this QGlyphRun should be painted with an underline decoration.
325 \sa setUnderline(), flags()
327 bool QGlyphRun::underline() const
329 return d->flags & Underline;
333 Indicates that this QGlyphRun should be painted with an underline decoration if \a underline is
334 true. Otherwise the QGlyphRun should be painted with no underline decoration.
336 \sa underline(), setFlag(), setFlags()
338 void QGlyphRun::setUnderline(bool underline)
340 setFlag(Underline, underline);
344 Returns true if this QGlyphRun should be painted with a strike out decoration.
346 \sa setStrikeOut(), flags()
348 bool QGlyphRun::strikeOut() const
350 return d->flags & StrikeOut;
354 Indicates that this QGlyphRun should be painted with an strike out decoration if \a strikeOut is
355 true. Otherwise the QGlyphRun should be painted with no strike out decoration.
357 \sa strikeOut(), setFlag(), setFlags()
359 void QGlyphRun::setStrikeOut(bool strikeOut)
361 setFlag(StrikeOut, strikeOut);
365 Returns true if this QGlyphRun contains glyphs that are painted from the right to the left.
368 \sa setRightToLeft(), flags()
370 bool QGlyphRun::isRightToLeft() const
372 return d->flags & RightToLeft;
376 Indicates that this QGlyphRun contains glyphs that should be ordered from the right to left
377 if \a rightToLeft is true. Otherwise the order of the glyphs is assumed to be left to right.
380 \sa isRightToLeft(), setFlag(), setFlags()
382 void QGlyphRun::setRightToLeft(bool rightToLeft)
384 setFlag(RightToLeft, rightToLeft);
388 Returns the flags set for this QGlyphRun.
391 \sa setFlag(), setFlag()
393 QGlyphRun::GlyphRunFlags QGlyphRun::flags() const
399 If \a enabled is true, then \a flag is enabled; otherwise, it is disabled.
402 \sa flags(), setFlags()
404 void QGlyphRun::setFlag(GlyphRunFlag flag, bool enabled)
406 if (d->flags.testFlag(flag) == enabled)
417 Sets the flags of this QGlyphRun to \a flags.
420 \sa setFlag(), flags()
422 void QGlyphRun::setFlags(GlyphRunFlags flags)
424 if (d->flags == flags)
432 Sets the bounding rect of the glyphs in this QGlyphRun to be \a boundingRect. This rectangle
433 will be returned by boundingRect() unless it is empty, in which case the bounding rectangle of the
434 glyphs in the glyph run will be returned instead.
436 \note Unless you are implementing text shaping, you should not have to use this function.
437 It is used specifically when the QGlyphRun should represent an area which is smaller than the
438 area of the glyphs it contains. This could happen e.g. if the glyph run is retrieved by calling
439 QTextLayout::glyphRuns() and the specified range only includes part of a ligature (where two or
440 more characters are combined to a single glyph.) When this is the case, the bounding rect should
441 only include the appropriate part of the ligature glyph, based on a calculation of the average
442 width of the characters in the ligature.
444 In order to support such a case (an example is selections which should be drawn with a different
445 color than the main text color), it is necessary to clip the painting mechanism to the rectangle
446 returned from boundingRect() to avoid drawing the entire ligature glyph.
452 void QGlyphRun::setBoundingRect(const QRectF &boundingRect)
455 d->boundingRect = boundingRect;
459 Returns the smallest rectangle that contains all glyphs in this QGlyphRun. If a bounding rect
460 has been set using setBoundingRect(), then this will be returned. Otherwise the bounding rect
461 will be calculated based on the font metrics of the glyphs in the glyph run.
465 QRectF QGlyphRun::boundingRect() const
467 if (!d->boundingRect.isEmpty())
468 return d->boundingRect;
470 qreal minX, minY, maxX, maxY;
471 minX = minY = maxX = maxY = 0;
473 for (int i=0; i<qMin(d->glyphPositions.size(), d->glyphIndexes.size()); ++i) {
474 QRectF glyphRect = d->rawFont.boundingRect(d->glyphIndexes.at(i));
475 glyphRect.translate(d->glyphPositions.at(i));
478 minX = glyphRect.left();
479 minY = glyphRect.top();
480 maxX = glyphRect.right();
481 maxY = glyphRect.bottom();
483 minX = qMin(glyphRect.left(), minX);
484 minY = qMin(glyphRect.top(), minY);
485 maxX = qMax(glyphRect.right(),maxX);
486 maxY = qMax(glyphRect.bottom(), maxY);
490 return QRectF(QPointF(minX, minY), QPointF(maxX, maxY));
494 Returns true if the QGlyphRun does not contain any glyphs.
498 bool QGlyphRun::isEmpty() const
500 return d->glyphIndexes.isEmpty();
505 #endif // QT_NO_RAWFONT