src/gui/text/qglyphrun.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtGui module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qglobal.h"
  43
  44 #if !defined(QT_NO_RAWFONT)
  45
  46 #include "qglyphrun.h"
  47 #include "qglyphrun_p.h"
  48 #include <qdebug.h>
  49
  50 QT_BEGIN_NAMESPACE
  51
  52 /*!
  53     \class QGlyphRun
  54     \brief The QGlyphRun class provides direct access to the internal glyphs in a font.
  55     \since 4.8
  56
  57     \ingroup text
  58     \mainclass
  59
  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.
  67
  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.
  73
  74     It is the user's responsibility to ensure that the selected font actually contains the
  75     provided glyph indexes.
  76
  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
  79     glyphs.
  80
  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.
  86 */
  87
  88
  89 /*!
  90     Constructs an empty QGlyphRun object.
  91 */
  92 QGlyphRun::QGlyphRun() : d(new QGlyphRunPrivate)
  93 {
  94 }
  95
  96 /*!
  97     Constructs a QGlyphRun object which is a copy of \a other.
  98 */
  99 QGlyphRun::QGlyphRun(const QGlyphRun &other)
 100 {
 101     d = other.d;
 102 }
 103
 104 /*!
 105     Destroys the QGlyphRun.
 106 */
 107 QGlyphRun::~QGlyphRun()
 108 {
 109     // Required for QExplicitlySharedDataPointer
 110 }
 111
 112 /*!
 113     \internal
 114 */
 115 void QGlyphRun::detach()
 116 {
 117     if (d->ref != 1)
 118         d.detach();
 119 }
 120
 121 /*!
 122     Assigns \a other to this QGlyphRun object.
 123 */
 124 QGlyphRun &QGlyphRun::operator=(const QGlyphRun &other)
 125 {
 126     d = other.d;
 127     return *this;
 128 }
 129
 130 /*!
 131     Compares \a other to this QGlyphRun object. Returns true if the list of glyph indexes,
 132     the list of positions and the font are all equal, otherwise returns false.
 133 */
 134 bool QGlyphRun::operator==(const QGlyphRun &other) const
 135 {
 136     if (d == other.d)
 137         return true;
 138
 139     if ((d->glyphIndexDataSize != other.d->glyphIndexDataSize)
 140      || (d->glyphPositionDataSize != other.d->glyphPositionDataSize)) {
 141         return false;
 142     }
 143
 144     if (d->glyphIndexData != other.d->glyphIndexData) {
 145         for (int i = 0; i < d->glyphIndexDataSize; ++i) {
 146             if (d->glyphIndexData[i] != other.d->glyphIndexData[i])
 147                return false;
 148         }
 149     }
 150     if (d->glyphPositionData != other.d->glyphPositionData) {
 151         for (int i = 0; i < d->glyphPositionDataSize; ++i) {
 152             if (d->glyphPositionData[i] != other.d->glyphPositionData[i])
 153                return false;
 154         }
 155     }
 156
 157     return (d->overline == other.d->overline
 158             && d->underline == other.d->underline
 159             && d->strikeOut == other.d->strikeOut
 160             && d->rawFont == other.d->rawFont);
 161 }
 162
 163 /*!
 164     \fn bool QGlyphRun::operator!=(const QGlyphRun &other) const
 165
 166     Compares \a other to this QGlyphRun object. Returns true if any of the list of glyph
 167     indexes, the list of positions or the font are different, otherwise returns false.
 168 */
 169
 170 /*!
 171     Returns the font selected for this QGlyphRun object.
 172
 173     \sa setRawFont()
 174 */
 175 QRawFont QGlyphRun::rawFont() const
 176 {
 177     return d->rawFont;
 178 }
 179
 180 /*!
 181     Sets the font in which to look up the glyph indexes to the \a rawFont
 182     specified.
 183
 184     \sa rawFont(), setGlyphIndexes()
 185 */
 186 void QGlyphRun::setRawFont(const QRawFont &rawFont)
 187 {
 188     detach();
 189     d->rawFont = rawFont;
 190 }
 191
 192 /*!
 193     Returns the glyph indexes for this QGlyphRun object.
 194
 195     \sa setGlyphIndexes(), setPositions()
 196 */
 197 QVector<quint32> QGlyphRun::glyphIndexes() const
 198 {
 199     if (d->glyphIndexes.constData() == d->glyphIndexData) {
 200         return d->glyphIndexes;
 201     } else {
 202         QVector<quint32> indexes(d->glyphIndexDataSize);
 203         qMemCopy(indexes.data(), d->glyphIndexData, d->glyphIndexDataSize * sizeof(quint32));
 204         return indexes;
 205     }
 206 }
 207
 208 /*!
 209     Set the glyph indexes for this QGlyphRun object to \a glyphIndexes. The glyph indexes must
 210     be valid for the selected font.
 211 */
 212 void QGlyphRun::setGlyphIndexes(const QVector<quint32> &glyphIndexes)
 213 {
 214     detach();
 215     d->glyphIndexes = glyphIndexes; // Keep a reference to the QVector to avoid copying
 216     d->glyphIndexData = glyphIndexes.constData();
 217     d->glyphIndexDataSize = glyphIndexes.size();
 218 }
 219
 220 /*!
 221     Returns the position of the edge of the baseline for each glyph in this set of glyph indexes.
 222 */
 223 QVector<QPointF> QGlyphRun::positions() const
 224 {
 225     if (d->glyphPositions.constData() == d->glyphPositionData) {
 226         return d->glyphPositions;
 227     } else {
 228         QVector<QPointF> glyphPositions(d->glyphPositionDataSize);
 229         qMemCopy(glyphPositions.data(), d->glyphPositionData,
 230                  d->glyphPositionDataSize * sizeof(QPointF));
 231         return glyphPositions;
 232     }
 233 }
 234
 235 /*!
 236     Sets the positions of the edge of the baseline for each glyph in this set of glyph indexes to
 237     \a positions.
 238 */
 239 void QGlyphRun::setPositions(const QVector<QPointF> &positions)
 240 {
 241     detach();
 242     d->glyphPositions = positions; // Keep a reference to the vector to avoid copying
 243     d->glyphPositionData = positions.constData();
 244     d->glyphPositionDataSize = positions.size();
 245 }
 246
 247 /*!
 248     Clears all data in the QGlyphRun object.
 249 */
 250 void QGlyphRun::clear()
 251 {
 252     detach();
 253     d->rawFont = QRawFont();
 254     d->strikeOut = false;
 255     d->overline = false;
 256     d->underline = false;
 257
 258     setPositions(QVector<QPointF>());
 259     setGlyphIndexes(QVector<quint32>());
 260 }
 261
 262 /*!
 263     Sets the glyph indexes and positions of this QGlyphRun to use the first \a size
 264     elements in the arrays \a glyphIndexArray and \a glyphPositionArray. The data is
 265     \e not copied. The caller must guarantee that the arrays are not deleted as long
 266     as this QGlyphRun and any copies of it exists.
 267
 268     \sa setGlyphIndexes(), setPositions()
 269 */
 270 void QGlyphRun::setRawData(const quint32 *glyphIndexArray, const QPointF *glyphPositionArray,
 271                            int size)
 272 {
 273     detach();
 274     d->glyphIndexes.clear();
 275     d->glyphPositions.clear();
 276
 277     d->glyphIndexData = glyphIndexArray;
 278     d->glyphPositionData = glyphPositionArray;
 279     d->glyphIndexDataSize = d->glyphPositionDataSize = size;
 280 }
 281
 282 /*!
 283    Returns true if this QGlyphRun should be painted with an overline decoration.
 284
 285    \sa setOverline()
 286 */
 287 bool QGlyphRun::overline() const
 288 {
 289     return d->overline;
 290 }
 291
 292 /*!
 293   Indicates that this QGlyphRun should be painted with an overline decoration if \a overline is true.
 294   Otherwise the QGlyphRun should be painted with no overline decoration.
 295
 296   \sa overline()
 297 */
 298 void QGlyphRun::setOverline(bool overline)
 299 {
 300     if (d->overline == overline)
 301         return;
 302
 303     detach();
 304     d->overline = overline;
 305 }
 306
 307 /*!
 308    Returns true if this QGlyphRun should be painted with an underline decoration.
 309
 310    \sa setUnderline()
 311 */
 312 bool QGlyphRun::underline() const
 313 {
 314     return d->underline;
 315 }
 316
 317 /*!
 318   Indicates that this QGlyphRun should be painted with an underline decoration if \a underline is
 319   true. Otherwise the QGlyphRun should be painted with no underline decoration.
 320
 321   \sa underline()
 322 */
 323 void QGlyphRun::setUnderline(bool underline)
 324 {
 325     if (d->underline == underline)
 326         return;
 327
 328     detach();
 329     d->underline = underline;
 330 }
 331
 332 /*!
 333    Returns true if this QGlyphRun should be painted with a strike out decoration.
 334
 335    \sa setStrikeOut()
 336 */
 337 bool QGlyphRun::strikeOut() const
 338 {
 339     return d->strikeOut;
 340 }
 341
 342 /*!
 343   Indicates that this QGlyphRun should be painted with an strike out decoration if \a strikeOut is
 344   true. Otherwise the QGlyphRun should be painted with no strike out decoration.
 345
 346   \sa strikeOut()
 347 */
 348 void QGlyphRun::setStrikeOut(bool strikeOut)
 349 {
 350     if (d->strikeOut == strikeOut)
 351         return;
 352
 353     detach();
 354     d->strikeOut = strikeOut;
 355 }
 356
 357 /*!
 358   Sets the bounding rect of the glyphs in this QGlyphRun to be \a boundingRect. This rectangle
 359   will be returned by boundingRect() unless it is empty, in which case the bounding rectangle of the
 360   glyphs in the glyph run will be returned instead.
 361
 362   \note Unless you are implementing text shaping, you should not have to use this function.
 363   It is used specifically when the QGlyphRun should represent an area which is smaller than the
 364   area of the glyphs it contains. This could happen e.g. if the glyph run is retrieved by calling
 365   QTextLayout::glyphRuns() and the specified range only includes part of a ligature (where two or
 366   more characters are combined to a single glyph.) When this is the case, the bounding rect should
 367   only include the appropriate part of the ligature glyph, based on a calculation of the average
 368   width of the characters in the ligature.
 369
 370   In order to support such a case (an example is selections which should be drawn with a different
 371   color than the main text color), it is necessary to clip the painting mechanism to the rectangle
 372   returned from boundingRect() to avoid drawing the entire ligature glyph.
 373
 374   \sa boundingRect()
 375
 376   \since 5.0
 377 */
 378 void QGlyphRun::setBoundingRect(const QRectF &boundingRect)
 379 {
 380     detach();
 381     d->boundingRect = boundingRect;
 382 }
 383
 384 /*!
 385   Returns the smallest rectangle that contains all glyphs in this QGlyphRun. If a bounding rect
 386   has been set using setBoundingRect(), then this will be returned. Otherwise the bounding rect
 387   will be calculated based on the font metrics of the glyphs in the glyph run.
 388
 389   \since 5.0
 390 */
 391 QRectF QGlyphRun::boundingRect() const
 392 {
 393     if (!d->boundingRect.isEmpty())
 394         return d->boundingRect;
 395
 396     qreal minX, minY, maxX, maxY;
 397
 398     for (int i=0; i<qMin(d->glyphPositions.size(), d->glyphIndexes.size()); ++i) {
 399         QRectF glyphRect = d->rawFont.boundingRect(d->glyphIndexes.at(i));
 400         glyphRect.translate(d->glyphPositions.at(i));
 401
 402         if (i == 0) {
 403             minX = glyphRect.left();
 404             minY = glyphRect.top();
 405             maxX = glyphRect.right();
 406             maxY = glyphRect.bottom();
 407         } else {
 408             minX = qMin(glyphRect.left(), minX);
 409             minY = qMin(glyphRect.top(), minY);
 410             maxX = qMax(glyphRect.right(),maxX);
 411             maxY = qMax(glyphRect.bottom(), maxY);
 412         }
 413     }
 414
 415     return QRectF(QPointF(minX, minY), QPointF(maxX, maxY));
 416 }
 417
 418 /*!
 419   Returns true if the QGlyphRun does not contain any glyphs.
 420
 421   \since 5.0
 422 */
 423 bool QGlyphRun::isEmpty() const
 424 {
 425     return d->glyphIndexes.isEmpty();
 426 }
 427
 428 QT_END_NAMESPACE
 429
 430 #endif // QT_NO_RAWFONT