1 /****************************************************************************
3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the QtGui module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** No Commercial Usage
11 ** This file contains pre-release code and may not be distributed.
12 ** You may use this file in accordance with the terms and conditions
13 ** contained in the Technology Preview License Agreement accompanying
16 ** GNU Lesser General Public License Usage
17 ** Alternatively, this file may be used under the terms of the GNU Lesser
18 ** General Public License version 2.1 as published by the Free Software
19 ** Foundation and appearing in the file LICENSE.LGPL included in the
20 ** packaging of this file. Please review the following information to
21 ** ensure the GNU Lesser General Public License version 2.1 requirements
22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
24 ** In addition, as a special exception, Nokia gives you certain additional
25 ** rights. These rights are described in the Nokia Qt LGPL Exception
26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
28 ** If you have questions regarding the use of this file, please contact
29 ** Nokia at qt-info@nokia.com.
40 ****************************************************************************/
44 #if !defined(QT_NO_RAWFONT)
46 #include "qglyphrun.h"
47 #include "qglyphrun_p.h"
53 \brief The QGlyphRun class provides direct access to the internal glyphs in a font.
59 When Qt displays a string of text encoded in Unicode, it will first convert the Unicode points
60 into a list of glyph indexes and a list of positions based on one or more fonts. The Unicode
61 representation of the text and the QFont object will in this case serve as a convenient
62 abstraction that hides the details of what actually takes place when displaying the text
63 on-screen. For instance, by the time the text actually reaches the screen, it may be represented
64 by a set of fonts in addition to the one specified by the user, e.g. in case the originally
65 selected font did not support all the writing systems contained in the text.
67 Under certain circumstances, it can be useful as an application developer to have more low-level
68 control over which glyphs in a specific font are drawn to the screen. This could for instance
69 be the case in applications that use an external font engine and text shaper together with Qt.
70 QGlyphRun provides an interface to the raw data needed to get text on the screen. It
71 contains a list of glyph indexes, a position for each glyph and a font.
73 It is the user's responsibility to ensure that the selected font actually contains the
74 provided glyph indexes.
76 QTextLayout::glyphRuns() or QTextFragment::glyphRuns() can be used to convert unicode encoded
77 text into a list of QGlyphRun objects, and QPainter::drawGlyphRun() can be used to draw the
80 \note Please note that QRawFont is considered local to the thread in which it is constructed.
81 This in turn means that a new QRawFont will have to be created and set on the QGlyphRun if it is
82 moved to a different thread. If the QGlyphRun contains a reference to a QRawFont from a different
83 thread than the current, it will not be possible to draw the glyphs using a QPainter, as the
84 QRawFont is considered invalid and inaccessible in this case.
89 Constructs an empty QGlyphRun object.
91 QGlyphRun::QGlyphRun() : d(new QGlyphRunPrivate)
96 Constructs a QGlyphRun object which is a copy of \a other.
98 QGlyphRun::QGlyphRun(const QGlyphRun &other)
104 Destroys the QGlyphRun.
106 QGlyphRun::~QGlyphRun()
108 // Required for QExplicitlySharedDataPointer
114 void QGlyphRun::detach()
121 Assigns \a other to this QGlyphRun object.
123 QGlyphRun &QGlyphRun::operator=(const QGlyphRun &other)
130 Compares \a other to this QGlyphRun object. Returns true if the list of glyph indexes,
131 the list of positions and the font are all equal, otherwise returns false.
133 bool QGlyphRun::operator==(const QGlyphRun &other) const
135 return ((d == other.d)
136 || (d->glyphIndexes == other.d->glyphIndexes
137 && d->glyphPositions == other.d->glyphPositions
138 && d->overline == other.d->overline
139 && d->underline == other.d->underline
140 && d->strikeOut == other.d->strikeOut
141 && d->rawFont == other.d->rawFont));
145 Compares \a other to this QGlyphRun object. Returns true if any of the list of glyph
146 indexes, the list of positions or the font are different, otherwise returns false.
148 bool QGlyphRun::operator!=(const QGlyphRun &other) const
150 return !(*this == other);
156 Adds together the lists of glyph indexes and positions in \a other and this QGlyphRun
157 object and returns the result. The font in the returned QGlyphRun will be the same as in
158 this QGlyphRun object.
160 QGlyphRun QGlyphRun::operator+(const QGlyphRun &other) const
162 QGlyphRun ret(*this);
170 Appends the glyph indexes and positions in \a other to this QGlyphRun object and returns
171 a reference to the current object.
173 QGlyphRun &QGlyphRun::operator+=(const QGlyphRun &other)
177 d->glyphIndexes += other.d->glyphIndexes;
178 d->glyphPositions += other.d->glyphPositions;
184 Returns the font selected for this QGlyphRun object.
188 QRawFont QGlyphRun::rawFont() const
194 Sets the font in which to look up the glyph indexes to \a font.
196 \sa rawFont(), setGlyphIndexes()
198 void QGlyphRun::setRawFont(const QRawFont &rawFont)
201 d->rawFont = rawFont;
205 Returns the glyph indexes for this QGlyphRun object.
207 \sa setGlyphIndexes(), setPositions()
209 QVector<quint32> QGlyphRun::glyphIndexes() const
211 return d->glyphIndexes;
215 Set the glyph indexes for this QGlyphRun object to \a glyphIndexes. The glyph indexes must
216 be valid for the selected font.
218 void QGlyphRun::setGlyphIndexes(const QVector<quint32> &glyphIndexes)
221 d->glyphIndexes = glyphIndexes;
225 Returns the position of the edge of the baseline for each glyph in this set of glyph indexes.
227 QVector<QPointF> QGlyphRun::positions() const
229 return d->glyphPositions;
233 Sets the positions of the edge of the baseline for each glyph in this set of glyph indexes to
236 void QGlyphRun::setPositions(const QVector<QPointF> &positions)
239 d->glyphPositions = positions;
243 Clears all data in the QGlyphRun object.
245 void QGlyphRun::clear()
248 d->glyphPositions = QVector<QPointF>();
249 d->glyphIndexes = QVector<quint32>();
250 d->rawFont = QRawFont();
251 d->strikeOut = false;
253 d->underline = false;
257 Returns true if this QGlyphRun should be painted with an overline decoration.
261 bool QGlyphRun::overline() const
267 Indicates that this QGlyphRun should be painted with an overline decoration if \a overline is true.
268 Otherwise the QGlyphRun should be painted with no overline decoration.
272 void QGlyphRun::setOverline(bool overline)
275 d->overline = overline;
279 Returns true if this QGlyphRun should be painted with an underline decoration.
283 bool QGlyphRun::underline() const
289 Indicates that this QGlyphRun should be painted with an underline decoration if \a underline is
290 true. Otherwise the QGlyphRun should be painted with no underline decoration.
294 void QGlyphRun::setUnderline(bool underline)
297 d->underline = underline;
301 Returns true if this QGlyphRun should be painted with a strike out decoration.
305 bool QGlyphRun::strikeOut() const
311 Indicates that this QGlyphRun should be painted with an strike out decoration if \a strikeOut is
312 true. Otherwise the QGlyphRun should be painted with no strike out decoration.
316 void QGlyphRun::setStrikeOut(bool strikeOut)
319 d->strikeOut = strikeOut;
324 #endif // QT_NO_RAWFONT