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     for (int i=0; i<qMax(d->glyphIndexDataSize, d->glyphPositionDataSize); ++i) {
 145         if (i < d->glyphIndexDataSize && d->glyphIndexData[i] != other.d->glyphIndexData[i])
 146            return false;
 147
 148         if (i < d->glyphPositionDataSize && d->glyphPositionData[i] != other.d->glyphPositionData[i])
 149            return false;
 150     }
 151
 152
 153     return (d->overline == other.d->overline
 154             && d->underline == other.d->underline
 155             && d->strikeOut == other.d->strikeOut
 156             && d->rawFont == other.d->rawFont);
 157 }
 158
 159 /*!
 160     Compares \a other to this QGlyphRun object. Returns true if any of the list of glyph
 161     indexes, the list of positions or the font are different, otherwise returns false.
 162 */
 163 bool QGlyphRun::operator!=(const QGlyphRun &other) const
 164 {
 165     return !(*this == other);
 166 }
 167
 168 /*!
 169     Returns the font selected for this QGlyphRun object.
 170
 171     \sa setRawFont()
 172 */
 173 QRawFont QGlyphRun::rawFont() const
 174 {
 175     return d->rawFont;
 176 }
 177
 178 /*!
 179     Sets the font in which to look up the glyph indexes to the \a rawFont
 180     specified.
 181
 182     \sa rawFont(), setGlyphIndexes()
 183 */
 184 void QGlyphRun::setRawFont(const QRawFont &rawFont)
 185 {
 186     detach();
 187     d->rawFont = rawFont;
 188 }
 189
 190 /*!
 191     Returns the glyph indexes for this QGlyphRun object.
 192
 193     \sa setGlyphIndexes(), setPositions()
 194 */
 195 QVector<quint32> QGlyphRun::glyphIndexes() const
 196 {
 197     if (d->glyphIndexes.constData() == d->glyphIndexData) {
 198         return d->glyphIndexes;
 199     } else {
 200         QVector<quint32> indexes(d->glyphIndexDataSize);
 201         qMemCopy(indexes.data(), d->glyphIndexData, d->glyphIndexDataSize * sizeof(quint32));
 202         return indexes;
 203     }
 204 }
 205
 206 /*!
 207     Set the glyph indexes for this QGlyphRun object to \a glyphIndexes. The glyph indexes must
 208     be valid for the selected font.
 209 */
 210 void QGlyphRun::setGlyphIndexes(const QVector<quint32> &glyphIndexes)
 211 {
 212     detach();
 213     d->glyphIndexes = glyphIndexes; // Keep a reference to the QVector to avoid copying
 214     d->glyphIndexData = glyphIndexes.constData();
 215     d->glyphIndexDataSize = glyphIndexes.size();
 216 }
 217
 218 /*!
 219     Returns the position of the edge of the baseline for each glyph in this set of glyph indexes.
 220 */
 221 QVector<QPointF> QGlyphRun::positions() const
 222 {
 223     if (d->glyphPositions.constData() == d->glyphPositionData) {
 224         return d->glyphPositions;
 225     } else {
 226         QVector<QPointF> glyphPositions(d->glyphPositionDataSize);
 227         qMemCopy(glyphPositions.data(), d->glyphPositionData,
 228                  d->glyphPositionDataSize * sizeof(QPointF));
 229         return glyphPositions;
 230     }
 231 }
 232
 233 /*!
 234     Sets the positions of the edge of the baseline for each glyph in this set of glyph indexes to
 235     \a positions.
 236 */
 237 void QGlyphRun::setPositions(const QVector<QPointF> &positions)
 238 {
 239     detach();
 240     d->glyphPositions = positions; // Keep a reference to the vector to avoid copying
 241     d->glyphPositionData = positions.constData();
 242     d->glyphPositionDataSize = positions.size();
 243 }
 244
 245 /*!
 246     Clears all data in the QGlyphRun object.
 247 */
 248 void QGlyphRun::clear()
 249 {
 250     detach();
 251     d->rawFont = QRawFont();
 252     d->strikeOut = false;
 253     d->overline = false;
 254     d->underline = false;
 255
 256     setPositions(QVector<QPointF>());
 257     setGlyphIndexes(QVector<quint32>());
 258 }
 259
 260 /*!
 261     Sets the glyph indexes and positions of this QGlyphRun to use the first \a size
 262     elements in the arrays \a glyphIndexArray and \a glyphPositionArray. The data is
 263     \e not copied. The caller must guarantee that the arrays are not deleted as long
 264     as this QGlyphRun and any copies of it exists.
 265
 266     \sa setGlyphIndexes(), setPositions()
 267 */
 268 void QGlyphRun::setRawData(const quint32 *glyphIndexArray, const QPointF *glyphPositionArray,
 269                            int size)
 270 {
 271     detach();
 272     d->glyphIndexes.clear();
 273     d->glyphPositions.clear();
 274
 275     d->glyphIndexData = glyphIndexArray;
 276     d->glyphPositionData = glyphPositionArray;
 277     d->glyphIndexDataSize = d->glyphPositionDataSize = size;
 278 }
 279
 280 /*!
 281    Returns true if this QGlyphRun should be painted with an overline decoration.
 282
 283    \sa setOverline()
 284 */
 285 bool QGlyphRun::overline() const
 286 {
 287     return d->overline;
 288 }
 289
 290 /*!
 291   Indicates that this QGlyphRun should be painted with an overline decoration if \a overline is true.
 292   Otherwise the QGlyphRun should be painted with no overline decoration.
 293
 294   \sa overline()
 295 */
 296 void QGlyphRun::setOverline(bool overline)
 297 {
 298     detach();
 299     d->overline = overline;
 300 }
 301
 302 /*!
 303    Returns true if this QGlyphRun should be painted with an underline decoration.
 304
 305    \sa setUnderline()
 306 */
 307 bool QGlyphRun::underline() const
 308 {
 309     return d->underline;
 310 }
 311
 312 /*!
 313   Indicates that this QGlyphRun should be painted with an underline decoration if \a underline is
 314   true. Otherwise the QGlyphRun should be painted with no underline decoration.
 315
 316   \sa underline()
 317 */
 318 void QGlyphRun::setUnderline(bool underline)
 319 {
 320     detach();
 321     d->underline = underline;
 322 }
 323
 324 /*!
 325    Returns true if this QGlyphRun should be painted with a strike out decoration.
 326
 327    \sa setStrikeOut()
 328 */
 329 bool QGlyphRun::strikeOut() const
 330 {
 331     return d->strikeOut;
 332 }
 333
 334 /*!
 335   Indicates that this QGlyphRun should be painted with an strike out decoration if \a strikeOut is
 336   true. Otherwise the QGlyphRun should be painted with no strike out decoration.
 337
 338   \sa strikeOut()
 339 */
 340 void QGlyphRun::setStrikeOut(bool strikeOut)
 341 {
 342     detach();
 343     d->strikeOut = strikeOut;
 344 }
 345
 346 /*!
 347   Sets the bounding rect of the glyphs in this QGlyphRun to be \a boundingRect. This rectangle
 348   will be returned by boundingRect() unless it is empty, in which case the bounding rectangle of the
 349   glyphs in the glyph run will be returned instead.
 350
 351   \note Unless you are implementing text shaping, you should not have to use this function.
 352   It is used specifically when the QGlyphRun should represent an area which is smaller than the
 353   area of the glyphs it contains. This could happen e.g. if the glyph run is retrieved by calling
 354   QTextLayout::glyphRuns() and the specified range only includes part of a ligature (where two or
 355   more characters are combined to a single glyph.) When this is the case, the bounding rect should
 356   only include the appropriate part of the ligature glyph, based on a calculation of the average
 357   width of the characters in the ligature.
 358
 359   In order to support such a case (an example is selections which should be drawn with a different
 360   color than the main text color), it is necessary to clip the painting mechanism to the rectangle
 361   returned from boundingRect() to avoid drawing the entire ligature glyph.
 362
 363   \sa boundingRect()
 364
 365   \since 5.0
 366 */
 367 void QGlyphRun::setBoundingRect(const QRectF &boundingRect)
 368 {
 369     detach();
 370     d->boundingRect = boundingRect;
 371 }
 372
 373 /*!
 374   Returns the smallest rectangle that contains all glyphs in this QGlyphRun. If a bounding rect
 375   has been set using setBoundingRect(), then this will be returned. Otherwise the bounding rect
 376   will be calculated based on the font metrics of the glyphs in the glyph run.
 377
 378   \since 5.0
 379 */
 380 QRectF QGlyphRun::boundingRect() const
 381 {
 382     if (!d->boundingRect.isEmpty())
 383         return d->boundingRect;
 384
 385     qreal minX, minY, maxX, maxY;
 386
 387     for (int i=0; i<qMin(d->glyphPositions.size(), d->glyphIndexes.size()); ++i) {
 388         QRectF glyphRect = d->rawFont.boundingRect(d->glyphIndexes.at(i));
 389         glyphRect.translate(d->glyphPositions.at(i));
 390
 391         if (i == 0) {
 392             minX = glyphRect.left();
 393             minY = glyphRect.top();
 394             maxX = glyphRect.right();
 395             maxY = glyphRect.bottom();
 396         } else {
 397             minX = qMin(glyphRect.left(), minX);
 398             minY = qMin(glyphRect.top(), minY);
 399             maxX = qMax(glyphRect.right(),maxX);
 400             maxY = qMax(glyphRect.bottom(), maxY);
 401         }
 402     }
 403
 404     return QRectF(QPointF(minX, minY), QPointF(maxX, maxY));
 405 }
 406
 407 /*!
 408   Returns true if the QGlyphRun does not contain any glyphs.
 409
 410   \since 5.0
 411 */
 412 bool QGlyphRun::isEmpty() const
 413 {
 414     return d->glyphIndexes.isEmpty();
 415 }
 416
 417 QT_END_NAMESPACE
 418
 419 #endif // QT_NO_RAWFONT