src/gui/text/qglyphrun.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the QtGui module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Lesser General Public License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  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     \inmodule QtGui
  57
  58     \ingroup text
  59     \mainclass
  60
  61     When Qt displays a string of text encoded in Unicode, it will first convert the Unicode points
  62     into a list of glyph indexes and a list of positions based on one or more fonts. The Unicode
  63     representation of the text and the QFont object will in this case serve as a convenient
  64     abstraction that hides the details of what actually takes place when displaying the text
  65     on-screen. For instance, by the time the text actually reaches the screen, it may be represented
  66     by a set of fonts in addition to the one specified by the user, e.g. in case the originally
  67     selected font did not support all the writing systems contained in the text.
  68
  69     Under certain circumstances, it can be useful as an application developer to have more low-level
  70     control over which glyphs in a specific font are drawn to the screen. This could for instance
  71     be the case in applications that use an external font engine and text shaper together with Qt.
  72     QGlyphRun provides an interface to the raw data needed to get text on the screen. It
  73     contains a list of glyph indexes, a position for each glyph and a font.
  74
  75     It is the user's responsibility to ensure that the selected font actually contains the
  76     provided glyph indexes.
  77
  78     QTextLayout::glyphRuns() or QTextFragment::glyphRuns() can be used to convert unicode encoded
  79     text into a list of QGlyphRun objects, and QPainter::drawGlyphRun() can be used to draw the
  80     glyphs.
  81
  82     \note Please note that QRawFont is considered local to the thread in which it is constructed.
  83     This in turn means that a new QRawFont will have to be created and set on the QGlyphRun if it is
  84     moved to a different thread. If the QGlyphRun contains a reference to a QRawFont from a different
  85     thread than the current, it will not be possible to draw the glyphs using a QPainter, as the
  86     QRawFont is considered invalid and inaccessible in this case.
  87 */
  88
  89 /*!
  90   \enum QGlyphRun::GlyphRunFlag
  91   \since 5.0
  92
  93   This enum describes flags that alter the way the run of glyphs might be presented or behave in
  94   a visual layout. The layout which generates the glyph runs can set these flags based on relevant
  95   internal data, to retain information needed to present the text as intended by the user of the
  96   layout.
  97
  98   \value Overline Indicates that the glyphs should be visualized together with an overline.
  99   \value Underline Indicates that the glyphs should be visualized together with an underline.
 100   \value StrikeOut Indicates that the glyphs should be struck out visually.
 101   \value RightToLeft Indicates that the glyphs are ordered right to left. This can affect the
 102   positioning of other screen elements that are relative to the glyph run, such as an inline
 103   text object.
 104   \value SplitLigature Indicates that the glyph run splits a ligature glyph. This means
 105   that a ligature glyph is included in the run, but the characters represented by it corresponds
 106   only to part of that ligature. The glyph run's boundingRect() function can in this case be used
 107   to retrieve the area covered by glyphs that correspond to the characters represented by the
 108   glyph run. When visualizing the glyphs, care needs to be taken to clip to this bounding rect to
 109   ensure that only the corresponding part of the ligature is painted. In particular, this can be
 110   the case when retrieving a glyph run from a QTextLayout for a specific character range, e.g.
 111   when retrieving the selected area of a QTextLayout.
 112 */
 113
 114 /*!
 115     Constructs an empty QGlyphRun object.
 116 */
 117 QGlyphRun::QGlyphRun() : d(new QGlyphRunPrivate)
 118 {
 119 }
 120
 121 /*!
 122     Constructs a QGlyphRun object which is a copy of \a other.
 123 */
 124 QGlyphRun::QGlyphRun(const QGlyphRun &other)
 125 {
 126     d = other.d;
 127 }
 128
 129 /*!
 130     Destroys the QGlyphRun.
 131 */
 132 QGlyphRun::~QGlyphRun()
 133 {
 134     // Required for QExplicitlySharedDataPointer
 135 }
 136
 137 /*!
 138     \internal
 139 */
 140 void QGlyphRun::detach()
 141 {
 142     if (d->ref.load() != 1)
 143         d.detach();
 144 }
 145
 146 /*!
 147     Assigns \a other to this QGlyphRun object.
 148 */
 149 QGlyphRun &QGlyphRun::operator=(const QGlyphRun &other)
 150 {
 151     d = other.d;
 152     return *this;
 153 }
 154
 155 /*!
 156     \fn void QGlyphRun::swap(QGlyphRun &other)
 157     \since 5.0
 158
 159     Swaps this glyph run instance with \a other. This function is very
 160     fast and never fails.
 161 */
 162
 163 /*!
 164     Compares \a other to this QGlyphRun object. Returns true if the list of glyph indexes,
 165     the list of positions and the font are all equal, otherwise returns false.
 166 */
 167 bool QGlyphRun::operator==(const QGlyphRun &other) const
 168 {
 169     if (d == other.d)
 170         return true;
 171
 172     if ((d->glyphIndexDataSize != other.d->glyphIndexDataSize)
 173      || (d->glyphPositionDataSize != other.d->glyphPositionDataSize)) {
 174         return false;
 175     }
 176
 177     if (d->glyphIndexData != other.d->glyphIndexData) {
 178         for (int i = 0; i < d->glyphIndexDataSize; ++i) {
 179             if (d->glyphIndexData[i] != other.d->glyphIndexData[i])
 180                return false;
 181         }
 182     }
 183     if (d->glyphPositionData != other.d->glyphPositionData) {
 184         for (int i = 0; i < d->glyphPositionDataSize; ++i) {
 185             if (d->glyphPositionData[i] != other.d->glyphPositionData[i])
 186                return false;
 187         }
 188     }
 189
 190     return (d->flags == other.d->flags && d->rawFont == other.d->rawFont);
 191 }
 192
 193 /*!
 194     \fn bool QGlyphRun::operator!=(const QGlyphRun &other) const
 195
 196     Compares \a other to this QGlyphRun object. Returns true if any of the list of glyph
 197     indexes, the list of positions or the font are different, otherwise returns false.
 198 */
 199
 200 /*!
 201     Returns the font selected for this QGlyphRun object.
 202
 203     \sa setRawFont()
 204 */
 205 QRawFont QGlyphRun::rawFont() const
 206 {
 207     return d->rawFont;
 208 }
 209
 210 /*!
 211     Sets the font in which to look up the glyph indexes to the \a rawFont
 212     specified.
 213
 214     \sa rawFont(), setGlyphIndexes()
 215 */
 216 void QGlyphRun::setRawFont(const QRawFont &rawFont)
 217 {
 218     detach();
 219     d->rawFont = rawFont;
 220 }
 221
 222 /*!
 223     Returns the glyph indexes for this QGlyphRun object.
 224
 225     \sa setGlyphIndexes(), setPositions()
 226 */
 227 QVector<quint32> QGlyphRun::glyphIndexes() const
 228 {
 229     if (d->glyphIndexes.constData() == d->glyphIndexData) {
 230         return d->glyphIndexes;
 231     } else {
 232         QVector<quint32> indexes(d->glyphIndexDataSize);
 233         memcpy(indexes.data(), d->glyphIndexData, d->glyphIndexDataSize * sizeof(quint32));
 234         return indexes;
 235     }
 236 }
 237
 238 /*!
 239     Set the glyph indexes for this QGlyphRun object to \a glyphIndexes. The glyph indexes must
 240     be valid for the selected font.
 241 */
 242 void QGlyphRun::setGlyphIndexes(const QVector<quint32> &glyphIndexes)
 243 {
 244     detach();
 245     d->glyphIndexes = glyphIndexes; // Keep a reference to the QVector to avoid copying
 246     d->glyphIndexData = glyphIndexes.constData();
 247     d->glyphIndexDataSize = glyphIndexes.size();
 248 }
 249
 250 /*!
 251     Returns the position of the edge of the baseline for each glyph in this set of glyph indexes.
 252 */
 253 QVector<QPointF> QGlyphRun::positions() const
 254 {
 255     if (d->glyphPositions.constData() == d->glyphPositionData) {
 256         return d->glyphPositions;
 257     } else {
 258         QVector<QPointF> glyphPositions(d->glyphPositionDataSize);
 259         memcpy(glyphPositions.data(), d->glyphPositionData,
 260                  d->glyphPositionDataSize * sizeof(QPointF));
 261         return glyphPositions;
 262     }
 263 }
 264
 265 /*!
 266     Sets the positions of the edge of the baseline for each glyph in this set of glyph indexes to
 267     \a positions.
 268 */
 269 void QGlyphRun::setPositions(const QVector<QPointF> &positions)
 270 {
 271     detach();
 272     d->glyphPositions = positions; // Keep a reference to the vector to avoid copying
 273     d->glyphPositionData = positions.constData();
 274     d->glyphPositionDataSize = positions.size();
 275 }
 276
 277 /*!
 278     Clears all data in the QGlyphRun object.
 279 */
 280 void QGlyphRun::clear()
 281 {
 282     detach();
 283     d->rawFont = QRawFont();
 284     d->flags = 0;
 285
 286     setPositions(QVector<QPointF>());
 287     setGlyphIndexes(QVector<quint32>());
 288 }
 289
 290 /*!
 291     Sets the glyph indexes and positions of this QGlyphRun to use the first \a size
 292     elements in the arrays \a glyphIndexArray and \a glyphPositionArray. The data is
 293     \e not copied. The caller must guarantee that the arrays are not deleted as long
 294     as this QGlyphRun and any copies of it exists.
 295
 296     \sa setGlyphIndexes(), setPositions()
 297 */
 298 void QGlyphRun::setRawData(const quint32 *glyphIndexArray, const QPointF *glyphPositionArray,
 299                            int size)
 300 {
 301     detach();
 302     d->glyphIndexes.clear();
 303     d->glyphPositions.clear();
 304
 305     d->glyphIndexData = glyphIndexArray;
 306     d->glyphPositionData = glyphPositionArray;
 307     d->glyphIndexDataSize = d->glyphPositionDataSize = size;
 308 }
 309
 310 /*!
 311    Returns true if this QGlyphRun should be painted with an overline decoration.
 312
 313    \sa setOverline(), flags()
 314 */
 315 bool QGlyphRun::overline() const
 316 {
 317     return d->flags & Overline;
 318 }
 319
 320 /*!
 321   Indicates that this QGlyphRun should be painted with an overline decoration if \a overline is true.
 322   Otherwise the QGlyphRun should be painted with no overline decoration.
 323
 324   \sa overline(), setFlag(), setFlags()
 325 */
 326 void QGlyphRun::setOverline(bool overline)
 327 {
 328     setFlag(Overline, overline);
 329 }
 330
 331 /*!
 332    Returns true if this QGlyphRun should be painted with an underline decoration.
 333
 334    \sa setUnderline(), flags()
 335 */
 336 bool QGlyphRun::underline() const
 337 {
 338     return d->flags & Underline;
 339 }
 340
 341 /*!
 342   Indicates that this QGlyphRun should be painted with an underline decoration if \a underline is
 343   true. Otherwise the QGlyphRun should be painted with no underline decoration.
 344
 345   \sa underline(), setFlag(), setFlags()
 346 */
 347 void QGlyphRun::setUnderline(bool underline)
 348 {
 349     setFlag(Underline, underline);
 350 }
 351
 352 /*!
 353    Returns true if this QGlyphRun should be painted with a strike out decoration.
 354
 355    \sa setStrikeOut(), flags()
 356 */
 357 bool QGlyphRun::strikeOut() const
 358 {
 359     return d->flags & StrikeOut;
 360 }
 361
 362 /*!
 363   Indicates that this QGlyphRun should be painted with an strike out decoration if \a strikeOut is
 364   true. Otherwise the QGlyphRun should be painted with no strike out decoration.
 365
 366   \sa strikeOut(), setFlag(), setFlags()
 367 */
 368 void QGlyphRun::setStrikeOut(bool strikeOut)
 369 {
 370     setFlag(StrikeOut, strikeOut);
 371 }
 372
 373 /*!
 374   Returns true if this QGlyphRun contains glyphs that are painted from the right to the left.
 375
 376   \since 5.0
 377   \sa setRightToLeft(), flags()
 378 */
 379 bool QGlyphRun::isRightToLeft() const
 380 {
 381     return d->flags & RightToLeft;
 382 }
 383
 384 /*!
 385   Indicates that this QGlyphRun contains glyphs that should be ordered from the right to left
 386   if \a rightToLeft is true. Otherwise the order of the glyphs is assumed to be left to right.
 387
 388   \since 5.0
 389   \sa isRightToLeft(), setFlag(), setFlags()
 390 */
 391 void QGlyphRun::setRightToLeft(bool rightToLeft)
 392 {
 393     setFlag(RightToLeft, rightToLeft);
 394 }
 395
 396 /*!
 397   Returns the flags set for this QGlyphRun.
 398
 399   \since 5.0
 400   \sa setFlag(), setFlag()
 401 */
 402 QGlyphRun::GlyphRunFlags QGlyphRun::flags() const
 403 {
 404     return d->flags;
 405 }
 406
 407 /*!
 408   If \a enabled is true, then \a flag is enabled; otherwise, it is disabled.
 409
 410   \since 5.0
 411   \sa flags(), setFlags()
 412 */
 413 void QGlyphRun::setFlag(GlyphRunFlag flag, bool enabled)
 414 {
 415     if (d->flags.testFlag(flag) == enabled)
 416         return;
 417
 418     detach();
 419     if (enabled)
 420         d->flags |= flag;
 421     else
 422         d->flags &= ~flag;
 423 }
 424
 425 /*!
 426   Sets the flags of this QGlyphRun to \a flags.
 427
 428   \since 5.0
 429   \sa setFlag(), flags()
 430 */
 431 void QGlyphRun::setFlags(GlyphRunFlags flags)
 432 {
 433     if (d->flags == flags)
 434         return;
 435
 436     detach();
 437     d->flags = flags;
 438 }
 439
 440 /*!
 441   Sets the bounding rect of the glyphs in this QGlyphRun to be \a boundingRect. This rectangle
 442   will be returned by boundingRect() unless it is empty, in which case the bounding rectangle of the
 443   glyphs in the glyph run will be returned instead.
 444
 445   \note Unless you are implementing text shaping, you should not have to use this function.
 446   It is used specifically when the QGlyphRun should represent an area which is smaller than the
 447   area of the glyphs it contains. This could happen e.g. if the glyph run is retrieved by calling
 448   QTextLayout::glyphRuns() and the specified range only includes part of a ligature (where two or
 449   more characters are combined to a single glyph.) When this is the case, the bounding rect should
 450   only include the appropriate part of the ligature glyph, based on a calculation of the average
 451   width of the characters in the ligature.
 452
 453   In order to support such a case (an example is selections which should be drawn with a different
 454   color than the main text color), it is necessary to clip the painting mechanism to the rectangle
 455   returned from boundingRect() to avoid drawing the entire ligature glyph.
 456
 457   \sa boundingRect()
 458
 459   \since 5.0
 460 */
 461 void QGlyphRun::setBoundingRect(const QRectF &boundingRect)
 462 {
 463     detach();
 464     d->boundingRect = boundingRect;
 465 }
 466
 467 /*!
 468   Returns the smallest rectangle that contains all glyphs in this QGlyphRun. If a bounding rect
 469   has been set using setBoundingRect(), then this will be returned. Otherwise the bounding rect
 470   will be calculated based on the font metrics of the glyphs in the glyph run.
 471
 472   \since 5.0
 473 */
 474 QRectF QGlyphRun::boundingRect() const
 475 {
 476     if (!d->boundingRect.isEmpty())
 477         return d->boundingRect;
 478
 479     qreal minX, minY, maxX, maxY;
 480     minX = minY = maxX = maxY = 0;
 481
 482     for (int i=0; i<qMin(d->glyphPositions.size(), d->glyphIndexes.size()); ++i) {
 483         QRectF glyphRect = d->rawFont.boundingRect(d->glyphIndexes.at(i));
 484         glyphRect.translate(d->glyphPositions.at(i));
 485
 486         if (i == 0) {
 487             minX = glyphRect.left();
 488             minY = glyphRect.top();
 489             maxX = glyphRect.right();
 490             maxY = glyphRect.bottom();
 491         } else {
 492             minX = qMin(glyphRect.left(), minX);
 493             minY = qMin(glyphRect.top(), minY);
 494             maxX = qMax(glyphRect.right(),maxX);
 495             maxY = qMax(glyphRect.bottom(), maxY);
 496         }
 497     }
 498
 499     return QRectF(QPointF(minX, minY), QPointF(maxX, maxY));
 500 }
 501
 502 /*!
 503   Returns true if the QGlyphRun does not contain any glyphs.
 504
 505   \since 5.0
 506 */
 507 bool QGlyphRun::isEmpty() const
 508 {
 509     return d->glyphIndexes.isEmpty();
 510 }
 511
 512 QT_END_NAMESPACE
 513
 514 #endif // QT_NO_RAWFONT