src/gui/text/qtextformat.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 "qtextformat.h"
  43 #include "qtextformat_p.h"
  44
  45 #include <qvariant.h>
  46 #include <qdatastream.h>
  47 #include <qdebug.h>
  48 #include <qmap.h>
  49 #include <qhash.h>
  50
  51 QT_BEGIN_NAMESPACE
  52
  53 /*!
  54     \class QTextLength
  55     \reentrant
  56
  57     \brief The QTextLength class encapsulates the different types of length
  58     used in a QTextDocument.
  59
  60     \ingroup richtext-processing
  61
  62     When we specify a value for the length of an element in a text document,
  63     we often need to provide some other information so that the length is
  64     used in the way we expect. For example, when we specify a table width,
  65     the value can represent a fixed number of pixels, or it can be a percentage
  66     value. This information changes both the meaning of the value and the way
  67     it is used.
  68
  69     Generally, this class is used to specify table widths. These can be
  70     specified either as a fixed amount of pixels, as a percentage of the
  71     containing frame's width, or by a variable width that allows it to take
  72     up just the space it requires.
  73
  74     \sa QTextTable
  75 */
  76
  77 /*!
  78     \fn explicit QTextLength::QTextLength()
  79
  80     Constructs a new length object which represents a variable size.
  81 */
  82
  83 /*!
  84     \fn QTextLength::QTextLength(Type type, qreal value)
  85
  86     Constructs a new length object of the given \a type and \a value.
  87 */
  88
  89 /*!
  90     \fn Type QTextLength::type() const
  91
  92     Returns the type of this length object.
  93
  94     \sa QTextLength::Type
  95 */
  96
  97 /*!
  98     \fn qreal QTextLength::value(qreal maximumLength) const
  99
 100     Returns the effective length, constrained by the type of the length object
 101     and the specified \a maximumLength.
 102
 103     \sa type()
 104 */
 105
 106 /*!
 107     \fn qreal QTextLength::rawValue() const
 108
 109     Returns the constraint value that is specific for the type of the length.
 110     If the length is QTextLength::PercentageLength then the raw value is in
 111     percent, in the range of 0 to 100. If the length is QTextLength::FixedLength
 112     then that fixed amount is returned. For variable lengths, zero is returned.
 113 */
 114
 115 /*!
 116     \fn bool QTextLength::operator==(const QTextLength &other) const
 117
 118     Returns true if this text length is the same as the \a other text
 119     length.
 120 */
 121
 122 /*!
 123     \fn bool QTextLength::operator!=(const QTextLength &other) const
 124
 125     Returns true if this text length is different from the \a other text
 126     length.
 127 */
 128
 129 /*!
 130     \enum QTextLength::Type
 131
 132     This enum describes the different types a length object can
 133     have.
 134
 135     \value VariableLength The width of the object is variable
 136     \value FixedLength The width of the object is fixed
 137     \value PercentageLength The width of the object is in
 138                             percentage of the maximum width
 139
 140     \sa type()
 141 */
 142
 143 /*!
 144    Returns the text length as a QVariant
 145 */
 146 QTextLength::operator QVariant() const
 147 {
 148     return QVariant(QVariant::TextLength, this);
 149 }
 150
 151 #ifndef QT_NO_DATASTREAM
 152 QDataStream &operator<<(QDataStream &stream, const QTextLength &length)
 153 {
 154     return stream << qint32(length.lengthType) << double(length.fixedValueOrPercentage);
 155 }
 156
 157 QDataStream &operator>>(QDataStream &stream, QTextLength &length)
 158 {
 159     qint32 type;
 160     double fixedValueOrPercentage;
 161     stream >> type >> fixedValueOrPercentage;
 162     length.fixedValueOrPercentage = fixedValueOrPercentage;
 163     length.lengthType = QTextLength::Type(type);
 164     return stream;
 165 }
 166 #endif // QT_NO_DATASTREAM
 167
 168 class QTextFormatPrivate : public QSharedData
 169 {
 170 public:
 171     QTextFormatPrivate() : hashDirty(true), fontDirty(true), hashValue(0) {}
 172
 173     struct Property
 174     {
 175         inline Property(qint32 k, const QVariant &v) : key(k), value(v) {}
 176         inline Property() {}
 177
 178         qint32 key;
 179         QVariant value;
 180
 181         inline bool operator==(const Property &other) const
 182         { return key == other.key && value == other.value; }
 183         inline bool operator!=(const Property &other) const
 184         { return key != other.key || value != other.value; }
 185     };
 186
 187     inline uint hash() const
 188     {
 189         if (!hashDirty)
 190             return hashValue;
 191         return recalcHash();
 192     }
 193
 194     inline bool operator==(const QTextFormatPrivate &rhs) const {
 195         if (hash() != rhs.hash())
 196             return false;
 197
 198         return props == rhs.props;
 199     }
 200
 201     inline void insertProperty(qint32 key, const QVariant &value)
 202     {
 203         hashDirty = true;
 204         if (key >= QTextFormat::FirstFontProperty && key <= QTextFormat::LastFontProperty)
 205             fontDirty = true;
 206         for (int i = 0; i < props.count(); ++i)
 207             if (props.at(i).key == key) {
 208                 props[i].value = value;
 209                 return;
 210             }
 211         props.append(Property(key, value));
 212     }
 213
 214     inline void clearProperty(qint32 key)
 215     {
 216         for (int i = 0; i < props.count(); ++i)
 217             if (props.at(i).key == key) {
 218                 hashDirty = true;
 219                 if (key >= QTextFormat::FirstFontProperty && key <= QTextFormat::LastFontProperty)
 220                     fontDirty = true;
 221                 props.remove(i);
 222                 return;
 223             }
 224     }
 225
 226     inline int propertyIndex(qint32 key) const
 227     {
 228         for (int i = 0; i < props.count(); ++i)
 229             if (props.at(i).key == key)
 230                 return i;
 231         return -1;
 232     }
 233
 234     inline QVariant property(qint32 key) const
 235     {
 236         const int idx = propertyIndex(key);
 237         if (idx < 0)
 238             return QVariant();
 239         return props.at(idx).value;
 240     }
 241
 242     inline bool hasProperty(qint32 key) const
 243     { return propertyIndex(key) != -1; }
 244
 245     void resolveFont(const QFont &defaultFont);
 246
 247     inline const QFont &font() const {
 248         if (fontDirty)
 249             recalcFont();
 250         return fnt;
 251     }
 252
 253     QVector<Property> props;
 254 private:
 255
 256     uint recalcHash() const;
 257     void recalcFont() const;
 258
 259     mutable bool hashDirty;
 260     mutable bool fontDirty;
 261     mutable uint hashValue;
 262     mutable QFont fnt;
 263
 264     friend QDataStream &operator<<(QDataStream &, const QTextFormat &);
 265     friend QDataStream &operator>>(QDataStream &, QTextFormat &);
 266 };
 267
 268 // this is only safe because sizeof(int) == sizeof(float)
 269 static inline uint hash(float d)
 270 {
 271 #ifdef Q_CC_GNU
 272     // this is a GCC extension and isn't guaranteed to work in other compilers
 273     // the reinterpret_cast below generates a strict-aliasing warning with GCC
 274     union { float f; uint u; } cvt;
 275     cvt.f = d;
 276     return cvt.u;
 277 #else
 278     return reinterpret_cast<uint&>(d);
 279 #endif
 280 }
 281
 282 static inline uint hash(const QColor &color)
 283 {
 284     return (color.isValid()) ? color.rgba() : 0x234109;
 285 }
 286
 287 static inline uint hash(const QPen &pen)
 288 {
 289     return hash(pen.color()) + hash(pen.widthF());
 290 }
 291
 292 static inline uint hash(const QBrush &brush)
 293 {
 294     return hash(brush.color()) + (brush.style() << 3);
 295 }
 296
 297 static inline uint variantHash(const QVariant &variant)
 298 {
 299     // simple and fast hash functions to differentiate between type and value
 300     switch (variant.userType()) { // sorted by occurrence frequency
 301     case QVariant::String: return qHash(variant.toString());
 302     case QVariant::Double: return hash(variant.toDouble());
 303     case QVariant::Int: return 0x811890 + variant.toInt();
 304     case QVariant::Brush:
 305         return 0x01010101 + hash(qvariant_cast<QBrush>(variant));
 306     case QVariant::Bool: return 0x371818 + variant.toBool();
 307     case QVariant::Pen: return 0x02020202 + hash(qvariant_cast<QPen>(variant));
 308     case QVariant::List:
 309         return 0x8377 + qvariant_cast<QVariantList>(variant).count();
 310     case QVariant::Color: return hash(qvariant_cast<QColor>(variant));
 311       case QVariant::TextLength:
 312         return 0x377 + hash(qvariant_cast<QTextLength>(variant).rawValue());
 313     case QMetaType::Float: return hash(variant.toFloat());
 314     case QVariant::Invalid: return 0;
 315     default: break;
 316     }
 317     return qHash(variant.typeName());
 318 }
 319
 320 static inline int getHash(const QTextFormatPrivate *d, int format)
 321 {
 322     return (d ? d->hash() : 0) + format;
 323 }
 324
 325 uint QTextFormatPrivate::recalcHash() const
 326 {
 327     hashValue = 0;
 328     for (QVector<Property>::ConstIterator it = props.constBegin(); it != props.constEnd(); ++it)
 329         hashValue += (it->key << 16) + variantHash(it->value);
 330
 331     hashDirty = false;
 332
 333     return hashValue;
 334 }
 335
 336 void QTextFormatPrivate::resolveFont(const QFont &defaultFont)
 337 {
 338     recalcFont();
 339     const uint oldMask = fnt.resolve();
 340     fnt = fnt.resolve(defaultFont);
 341
 342     if (hasProperty(QTextFormat::FontSizeAdjustment)) {
 343         const qreal scaleFactors[7] = {qreal(0.7), qreal(0.8), qreal(1.0), qreal(1.2), qreal(1.5), qreal(2), qreal(2.4)};
 344
 345         const int htmlFontSize = qBound(0, property(QTextFormat::FontSizeAdjustment).toInt() + 3 - 1, 6);
 346
 347
 348         if (defaultFont.pointSize() <= 0) {
 349             qreal pixelSize = scaleFactors[htmlFontSize] * defaultFont.pixelSize();
 350             fnt.setPixelSize(qRound(pixelSize));
 351         } else {
 352             qreal pointSize = scaleFactors[htmlFontSize] * defaultFont.pointSizeF();
 353             fnt.setPointSizeF(pointSize);
 354         }
 355     }
 356
 357     fnt.resolve(oldMask);
 358 }
 359
 360 void QTextFormatPrivate::recalcFont() const
 361 {
 362     // update cached font as well
 363     QFont f;
 364
 365     for (int i = 0; i < props.count(); ++i) {
 366         switch (props.at(i).key) {
 367             case QTextFormat::FontFamily:
 368                 f.setFamily(props.at(i).value.toString());
 369                 break;
 370             case QTextFormat::FontPointSize:
 371                 f.setPointSizeF(props.at(i).value.toReal());
 372                 break;
 373             case  QTextFormat::FontPixelSize:
 374                 f.setPixelSize(props.at(i).value.toInt());
 375                 break;
 376             case QTextFormat::FontWeight: {
 377                 int weight = props.at(i).value.toInt();
 378                 if (weight == 0) weight = QFont::Normal;
 379                 f.setWeight(weight);
 380                 break; }
 381             case QTextFormat::FontItalic:
 382                 f.setItalic(props.at(i).value.toBool());
 383                 break;
 384             case QTextFormat::FontUnderline:
 385                 if (! hasProperty(QTextFormat::TextUnderlineStyle)) // don't use the old one if the new one is there.
 386                     f.setUnderline(props.at(i).value.toBool());
 387                 break;
 388             case QTextFormat::TextUnderlineStyle:
 389                 f.setUnderline(static_cast<QTextCharFormat::UnderlineStyle>(props.at(i).value.toInt()) == QTextCharFormat::SingleUnderline);
 390                 break;
 391             case QTextFormat::FontOverline:
 392                 f.setOverline(props.at(i).value.toBool());
 393                 break;
 394             case QTextFormat::FontStrikeOut:
 395                 f.setStrikeOut(props.at(i).value.toBool());
 396                 break;
 397             case QTextFormat::FontLetterSpacing:
 398                 f.setLetterSpacing(QFont::PercentageSpacing, props.at(i).value.toReal());
 399                 break;
 400             case QTextFormat::FontWordSpacing:
 401                 f.setWordSpacing(props.at(i).value.toReal());
 402                 break;
 403             case QTextFormat::FontCapitalization:
 404                 f.setCapitalization(static_cast<QFont::Capitalization> (props.at(i).value.toInt()));
 405                 break;
 406             case QTextFormat::FontFixedPitch: {
 407                 const bool value = props.at(i).value.toBool();
 408                 if (f.fixedPitch() != value)
 409                     f.setFixedPitch(value);
 410                 break; }
 411             case QTextFormat::FontStyleHint:
 412                 f.setStyleHint(static_cast<QFont::StyleHint>(props.at(i).value.toInt()), f.styleStrategy());
 413                 break;
 414             case QTextFormat::FontHintingPreference:
 415                 f.setHintingPreference(static_cast<QFont::HintingPreference>(props.at(i).value.toInt()));
 416                 break;
 417             case QTextFormat::FontStyleStrategy:
 418                 f.setStyleStrategy(static_cast<QFont::StyleStrategy>(props.at(i).value.toInt()));
 419                 break;
 420             case QTextFormat::FontKerning:
 421                 f.setKerning(props.at(i).value.toBool());
 422                 break;
 423             default:
 424                 break;
 425             }
 426     }
 427     fnt = f;
 428     fontDirty = false;
 429 }
 430
 431 #ifndef QT_NO_DATASTREAM
 432 Q_GUI_EXPORT QDataStream &operator<<(QDataStream &stream, const QTextFormat &fmt)
 433 {
 434     stream << fmt.format_type << fmt.properties();
 435     return stream;
 436 }
 437
 438 Q_GUI_EXPORT QDataStream &operator>>(QDataStream &stream, QTextFormat &fmt)
 439 {
 440     QMap<qint32, QVariant> properties;
 441     stream >> fmt.format_type >> properties;
 442
 443     // QTextFormat's default constructor doesn't allocate the private structure, so
 444     // we have to do this, in case fmt is a default constructed value.
 445     if(!fmt.d)
 446         fmt.d = new QTextFormatPrivate();
 447
 448     for (QMap<qint32, QVariant>::ConstIterator it = properties.constBegin();
 449          it != properties.constEnd(); ++it)
 450         fmt.d->insertProperty(it.key(), it.value());
 451
 452     return stream;
 453 }
 454 #endif // QT_NO_DATASTREAM
 455
 456 /*!
 457     \class QTextFormat
 458     \reentrant
 459
 460     \brief The QTextFormat class provides formatting information for a
 461     QTextDocument.
 462
 463     \ingroup richtext-processing
 464     \ingroup shared
 465
 466     A QTextFormat is a generic class used for describing the format of
 467     parts of a QTextDocument. The derived classes QTextCharFormat,
 468     QTextBlockFormat, QTextListFormat, and QTextTableFormat are usually
 469     more useful, and describe the formatting that is applied to
 470     specific parts of the document.
 471
 472     A format has a \c FormatType which specifies the kinds of text item it
 473     can format; e.g. a block of text, a list, a table, etc. A format
 474     also has various properties (some specific to particular format
 475     types), as described by the Property enum. Every property has a
 476     corresponding Property.
 477
 478     The format type is given by type(), and the format can be tested
 479     with isCharFormat(), isBlockFormat(), isListFormat(),
 480     isTableFormat(), isFrameFormat(), and isImageFormat(). If the
 481     type is determined, it can be retrieved with toCharFormat(),
 482     toBlockFormat(), toListFormat(), toTableFormat(), toFrameFormat(),
 483     and toImageFormat().
 484
 485     A format's properties can be set with the setProperty() functions,
 486     and retrieved with boolProperty(), intProperty(), doubleProperty(),
 487     and stringProperty() as appropriate. All the property IDs used in
 488     the format can be retrieved with allPropertyIds(). One format can
 489     be merged into another using merge().
 490
 491     A format's object index can be set with setObjectIndex(), and
 492     retrieved with objectIndex(). These methods can be used to
 493     associate the format with a QTextObject. It is used to represent
 494     lists, frames, and tables inside the document.
 495
 496     \sa {Rich Text Processing}
 497 */
 498
 499 /*!
 500     \enum QTextFormat::FormatType
 501
 502     This enum describes the text item a QTextFormat object is formatting.
 503
 504     \value InvalidFormat An invalid format as created by the default
 505                          constructor
 506     \value BlockFormat The object formats a text block
 507     \value CharFormat The object formats a single character
 508     \value ListFormat The object formats a list
 509     \value TableFormat The object formats a table
 510     \value FrameFormat The object formats a frame
 511
 512     \value UserFormat
 513
 514     \sa QTextCharFormat, QTextBlockFormat, QTextListFormat,
 515     QTextTableFormat, type()
 516 */
 517
 518 /*!
 519     \enum QTextFormat::Property
 520
 521     This enum describes the different properties a format can have.
 522
 523     \value ObjectIndex The index of the formatted object. See objectIndex().
 524
 525     Paragraph and character properties
 526
 527     \value CssFloat How a frame is located relative to the surrounding text
 528     \value LayoutDirection  The layout direction of the text in the document
 529                             (Qt::LayoutDirection).
 530
 531     \value OutlinePen
 532     \value ForegroundBrush
 533     \value BackgroundBrush
 534     \value BackgroundImageUrl
 535
 536     Paragraph properties
 537
 538     \value BlockAlignment
 539     \value BlockTopMargin
 540     \value BlockBottomMargin
 541     \value BlockLeftMargin
 542     \value BlockRightMargin
 543     \value TextIndent
 544     \value TabPositions     Specifies the tab positions.  The tab positions are structs of QTextOption::Tab which are stored in
 545                             a QList (internally, in a QList<QVariant>).
 546     \value BlockIndent
 547     \value LineHeight
 548     \value LineHeightType
 549     \value BlockNonBreakableLines
 550     \value BlockTrailingHorizontalRulerWidth The width of a horizontal ruler element.
 551
 552     Character properties
 553
 554     \value FontFamily
 555     \value FontPointSize
 556     \value FontPixelSize
 557     \value FontSizeAdjustment       Specifies the change in size given to the fontsize already set using
 558                                     FontPointSize or FontPixelSize.
 559     \value FontFixedPitch
 560     \omitvalue FontSizeIncrement
 561     \value FontWeight
 562     \value FontItalic
 563     \value FontUnderline \e{This property has been deprecated.} Use QTextFormat::TextUnderlineStyle instead.
 564     \value FontOverline
 565     \value FontStrikeOut
 566     \value FontCapitalization Specifies the capitalization type that is to be applied to the text.
 567     \value FontLetterSpacing Changes the default spacing between individual letters in the font. The value is
 568                                                 specified in percentage, with 100 as the default value.
 569     \value FontWordSpacing  Changes the default spacing between individual words. A positive value increases the word spacing
 570                                                  by the corresponding pixels; a negative value decreases the spacing.
 571     \value FontStyleHint        Corresponds to the QFont::StyleHint property
 572     \value FontStyleStrategy    Corresponds to the QFont::StyleStrategy property
 573     \value FontKerning          Specifies whether the font has kerning turned on.
 574     \value FontHintingPreference Controls the use of hinting according to values
 575                                  of the QFont::HintingPreference enum.
 576
 577     \omitvalue FirstFontProperty
 578     \omitvalue LastFontProperty
 579
 580     \value TextUnderlineColor
 581     \value TextVerticalAlignment
 582     \value TextOutline
 583     \value TextUnderlineStyle
 584     \value TextToolTip Specifies the (optional) tool tip to be displayed for a fragment of text.
 585
 586     \value IsAnchor
 587     \value AnchorHref
 588     \value AnchorName
 589     \value ObjectType
 590
 591     List properties
 592
 593     \value ListStyle        Specifies the style used for the items in a list,
 594                             described by values of the QTextListFormat::Style enum.
 595     \value ListIndent       Specifies the amount of indentation used for a list.
 596     \value ListNumberPrefix Defines the text which is prepended to item numbers in
 597                             numeric lists.
 598     \value ListNumberSuffix Defines the text which is appended to item numbers in
 599                             numeric lists.
 600
 601     Table and frame properties
 602
 603     \value FrameBorder
 604     \value FrameBorderBrush
 605     \value FrameBorderStyle See the \l{QTextFrameFormat::BorderStyle}{BorderStyle} enum.
 606     \value FrameBottomMargin
 607     \value FrameHeight
 608     \value FrameLeftMargin
 609     \value FrameMargin
 610     \value FramePadding
 611     \value FrameRightMargin
 612     \value FrameTopMargin
 613     \value FrameWidth
 614     \value TableCellSpacing
 615     \value TableCellPadding
 616     \value TableColumns
 617     \value TableColumnWidthConstraints
 618     \value TableHeaderRowCount
 619
 620     Table cell properties
 621
 622     \value TableCellRowSpan
 623     \value TableCellColumnSpan
 624     \value TableCellLeftPadding
 625     \value TableCellRightPadding
 626     \value TableCellTopPadding
 627     \value TableCellBottomPadding
 628
 629     Image properties
 630
 631     \value ImageName
 632     \value ImageWidth
 633     \value ImageHeight
 634
 635     Selection properties
 636
 637     \value FullWidthSelection When set on the characterFormat of a selection,
 638                               the whole width of the text will be shown selected.
 639
 640     Page break properties
 641
 642     \value PageBreakPolicy Specifies how pages are broken. See the PageBreakFlag enum.
 643
 644     \value UserProperty
 645
 646     \sa property(), setProperty()
 647 */
 648
 649 /*!
 650     \enum QTextFormat::ObjectTypes
 651
 652     This enum describes what kind of QTextObject this format is associated with.
 653
 654     \value NoObject
 655     \value ImageObject
 656     \value TableObject
 657     \value TableCellObject
 658     \value UserObject The first object that can be used for application-specific purposes.
 659
 660     \sa QTextObject, QTextTable, QTextObject::format()
 661 */
 662
 663 /*!
 664     \enum QTextFormat::PageBreakFlag
 665     \since 4.2
 666
 667     This enum describes how page breaking is performed when printing. It maps to the
 668     corresponding css properties.
 669
 670     \value PageBreak_Auto The page break is determined automatically depending on the
 671                           available space on the current page
 672     \value PageBreak_AlwaysBefore The page is always broken before the paragraph/table
 673     \value PageBreak_AlwaysAfter  A new page is always started after the paragraph/table
 674
 675     \sa QTextBlockFormat::pageBreakPolicy(), QTextFrameFormat::pageBreakPolicy(),
 676     PageBreakPolicy
 677 */
 678
 679 /*!
 680     \fn bool QTextFormat::isValid() const
 681
 682     Returns true if the format is valid (i.e. is not
 683     InvalidFormat); otherwise returns false.
 684 */
 685
 686 /*!
 687     \fn bool QTextFormat::isCharFormat() const
 688
 689     Returns true if this text format is a \c CharFormat; otherwise
 690     returns false.
 691 */
 692
 693
 694 /*!
 695     \fn bool QTextFormat::isBlockFormat() const
 696
 697     Returns true if this text format is a \c BlockFormat; otherwise
 698     returns false.
 699 */
 700
 701
 702 /*!
 703     \fn bool QTextFormat::isListFormat() const
 704
 705     Returns true if this text format is a \c ListFormat; otherwise
 706     returns false.
 707 */
 708
 709
 710 /*!
 711     \fn bool QTextFormat::isTableFormat() const
 712
 713     Returns true if this text format is a \c TableFormat; otherwise
 714     returns false.
 715 */
 716
 717
 718 /*!
 719     \fn bool QTextFormat::isFrameFormat() const
 720
 721     Returns true if this text format is a \c FrameFormat; otherwise
 722     returns false.
 723 */
 724
 725
 726 /*!
 727     \fn bool QTextFormat::isImageFormat() const
 728
 729     Returns true if this text format is an image format; otherwise
 730     returns false.
 731 */
 732
 733
 734 /*!
 735     \fn bool QTextFormat::isTableCellFormat() const
 736     \since 4.4
 737
 738     Returns true if this text format is a \c TableCellFormat; otherwise
 739     returns false.
 740 */
 741
 742
 743 /*!
 744     Creates a new text format with an \c InvalidFormat.
 745
 746     \sa FormatType
 747 */
 748 QTextFormat::QTextFormat()
 749     : format_type(InvalidFormat)
 750 {
 751 }
 752
 753 /*!
 754     Creates a new text format of the given \a type.
 755
 756     \sa FormatType
 757 */
 758 QTextFormat::QTextFormat(int type)
 759     : format_type(type)
 760 {
 761 }
 762
 763
 764 /*!
 765     \fn QTextFormat::QTextFormat(const QTextFormat &other)
 766
 767     Creates a new text format with the same attributes as the \a other
 768     text format.
 769 */
 770 QTextFormat::QTextFormat(const QTextFormat &rhs)
 771     : d(rhs.d), format_type(rhs.format_type)
 772 {
 773 }
 774
 775 /*!
 776     \fn QTextFormat &QTextFormat::operator=(const QTextFormat &other)
 777
 778     Assigns the \a other text format to this text format, and returns a
 779     reference to this text format.
 780 */
 781 QTextFormat &QTextFormat::operator=(const QTextFormat &rhs)
 782 {
 783     d = rhs.d;
 784     format_type = rhs.format_type;
 785     return *this;
 786 }
 787
 788 /*!
 789     Destroys this text format.
 790 */
 791 QTextFormat::~QTextFormat()
 792 {
 793 }
 794
 795
 796 /*!
 797    Returns the text format as a QVariant
 798 */
 799 QTextFormat::operator QVariant() const
 800 {
 801     return QVariant(QVariant::TextFormat, this);
 802 }
 803
 804 /*!
 805     Merges the \a other format with this format; where there are
 806     conflicts the \a other format takes precedence.
 807 */
 808 void QTextFormat::merge(const QTextFormat &other)
 809 {
 810     if (format_type != other.format_type)
 811         return;
 812
 813     if (!d) {
 814         d = other.d;
 815         return;
 816     }
 817
 818     if (!other.d)
 819         return;
 820
 821     QTextFormatPrivate *d = this->d;
 822
 823     const QVector<QTextFormatPrivate::Property> &otherProps = other.d->props;
 824     d->props.reserve(d->props.size() + otherProps.size());
 825     for (int i = 0; i < otherProps.count(); ++i) {
 826         const QTextFormatPrivate::Property &p = otherProps.at(i);
 827         d->insertProperty(p.key, p.value);
 828     }
 829 }
 830
 831 /*!
 832     Returns the type of this format.
 833
 834     \sa FormatType
 835 */
 836 int QTextFormat::type() const
 837 {
 838     return format_type;
 839 }
 840
 841 /*!
 842     Returns this format as a block format.
 843 */
 844 QTextBlockFormat QTextFormat::toBlockFormat() const
 845 {
 846     return QTextBlockFormat(*this);
 847 }
 848
 849 /*!
 850     Returns this format as a character format.
 851 */
 852 QTextCharFormat QTextFormat::toCharFormat() const
 853 {
 854     return QTextCharFormat(*this);
 855 }
 856
 857 /*!
 858     Returns this format as a list format.
 859 */
 860 QTextListFormat QTextFormat::toListFormat() const
 861 {
 862     return QTextListFormat(*this);
 863 }
 864
 865 /*!
 866     Returns this format as a table format.
 867 */
 868 QTextTableFormat QTextFormat::toTableFormat() const
 869 {
 870     return QTextTableFormat(*this);
 871 }
 872
 873 /*!
 874     Returns this format as a frame format.
 875 */
 876 QTextFrameFormat QTextFormat::toFrameFormat() const
 877 {
 878     return QTextFrameFormat(*this);
 879 }
 880
 881 /*!
 882     Returns this format as an image format.
 883 */
 884 QTextImageFormat QTextFormat::toImageFormat() const
 885 {
 886     return QTextImageFormat(*this);
 887 }
 888
 889 /*!
 890     \since 4.4
 891
 892     Returns this format as a table cell format.
 893 */
 894 QTextTableCellFormat QTextFormat::toTableCellFormat() const
 895 {
 896     return QTextTableCellFormat(*this);
 897 }
 898
 899 /*!
 900     Returns the value of the property specified by \a propertyId. If the
 901     property isn't of QTextFormat::Bool type, false is returned instead.
 902
 903     \sa setProperty() intProperty() doubleProperty() stringProperty() colorProperty() lengthProperty() lengthVectorProperty() Property
 904 */
 905 bool QTextFormat::boolProperty(int propertyId) const
 906 {
 907     if (!d)
 908         return false;
 909     const QVariant prop = d->property(propertyId);
 910     if (prop.userType() != QVariant::Bool)
 911         return false;
 912     return prop.toBool();
 913 }
 914
 915 /*!
 916     Returns the value of the property specified by \a propertyId. If the
 917     property is not of QTextFormat::Integer type, 0 is returned instead.
 918
 919     \sa setProperty() boolProperty() doubleProperty() stringProperty() colorProperty() lengthProperty() lengthVectorProperty() Property
 920 */
 921 int QTextFormat::intProperty(int propertyId) const
 922 {
 923     // required, since the default layout direction has to be LayoutDirectionAuto, which is not integer 0
 924     int def = (propertyId == QTextFormat::LayoutDirection) ? int(Qt::LayoutDirectionAuto) : 0;
 925
 926     if (!d)
 927         return def;
 928     const QVariant prop = d->property(propertyId);
 929     if (prop.userType() != QVariant::Int)
 930         return def;
 931     return prop.toInt();
 932 }
 933
 934 /*!
 935     Returns the value of the property specified by \a propertyId. If the
 936     property isn't of QVariant::Double or QMetaType::Float type, 0 is
 937     returned instead.
 938
 939     \sa setProperty() boolProperty() intProperty() stringProperty() colorProperty() lengthProperty() lengthVectorProperty() Property
 940 */
 941 qreal QTextFormat::doubleProperty(int propertyId) const
 942 {
 943     if (!d)
 944         return 0.;
 945     const QVariant prop = d->property(propertyId);
 946     if (prop.userType() != QVariant::Double && prop.userType() != QMetaType::Float)
 947         return 0.;
 948     return qvariant_cast<qreal>(prop);
 949 }
 950
 951 /*!
 952     Returns the value of the property given by \a propertyId; if the
 953     property isn't of QVariant::String type, an empty string is
 954     returned instead.
 955
 956     \sa setProperty() boolProperty() intProperty() doubleProperty() colorProperty() lengthProperty() lengthVectorProperty() Property
 957 */
 958 QString QTextFormat::stringProperty(int propertyId) const
 959 {
 960     if (!d)
 961         return QString();
 962     const QVariant prop = d->property(propertyId);
 963     if (prop.userType() != QVariant::String)
 964         return QString();
 965     return prop.toString();
 966 }
 967
 968 /*!
 969     Returns the value of the property given by \a propertyId; if the
 970     property isn't of QVariant::Color type, an invalid color is
 971     returned instead.
 972
 973     \sa setProperty(), boolProperty(), intProperty(), doubleProperty(),
 974         stringProperty(), lengthProperty(), lengthVectorProperty(), Property
 975 */
 976 QColor QTextFormat::colorProperty(int propertyId) const
 977 {
 978     if (!d)
 979         return QColor();
 980     const QVariant prop = d->property(propertyId);
 981     if (prop.userType() != QVariant::Color)
 982         return QColor();
 983     return qvariant_cast<QColor>(prop);
 984 }
 985
 986 /*!
 987     Returns the value of the property given by \a propertyId; if the
 988     property isn't of QVariant::Pen type, Qt::NoPen is
 989     returned instead.
 990
 991     \sa setProperty() boolProperty() intProperty() doubleProperty() stringProperty() lengthProperty() lengthVectorProperty() Property
 992 */
 993 QPen QTextFormat::penProperty(int propertyId) const
 994 {
 995     if (!d)
 996         return QPen(Qt::NoPen);
 997     const QVariant prop = d->property(propertyId);
 998     if (prop.userType() != QVariant::Pen)
 999         return QPen(Qt::NoPen);
1000     return qvariant_cast<QPen>(prop);
1001 }
1002
1003 /*!
1004     Returns the value of the property given by \a propertyId; if the
1005     property isn't of QVariant::Brush type, Qt::NoBrush is
1006     returned instead.
1007
1008     \sa setProperty() boolProperty() intProperty() doubleProperty() stringProperty() lengthProperty() lengthVectorProperty() Property
1009 */
1010 QBrush QTextFormat::brushProperty(int propertyId) const
1011 {
1012     if (!d)
1013         return QBrush(Qt::NoBrush);
1014     const QVariant prop = d->property(propertyId);
1015     if (prop.userType() != QVariant::Brush)
1016         return QBrush(Qt::NoBrush);
1017     return qvariant_cast<QBrush>(prop);
1018 }
1019
1020 /*!
1021     Returns the value of the property given by \a propertyId.
1022
1023     \sa setProperty() boolProperty() intProperty() doubleProperty() stringProperty() colorProperty() lengthVectorProperty() Property
1024 */
1025 QTextLength QTextFormat::lengthProperty(int propertyId) const
1026 {
1027     if (!d)
1028         return QTextLength();
1029     return qvariant_cast<QTextLength>(d->property(propertyId));
1030 }
1031
1032 /*!
1033     Returns the value of the property given by \a propertyId. If the
1034     property isn't of QTextFormat::LengthVector type, an empty length
1035     vector is returned instead.
1036
1037     \sa setProperty() boolProperty() intProperty() doubleProperty() stringProperty() colorProperty() lengthProperty() Property
1038 */
1039 QVector<QTextLength> QTextFormat::lengthVectorProperty(int propertyId) const
1040 {
1041     QVector<QTextLength> vector;
1042     if (!d)
1043         return vector;
1044     const QVariant prop = d->property(propertyId);
1045     if (prop.userType() != QVariant::List)
1046         return vector;
1047
1048     QList<QVariant> propertyList = prop.toList();
1049     for (int i=0; i<propertyList.size(); ++i) {
1050         QVariant var = propertyList.at(i);
1051         if (var.userType() == QVariant::TextLength)
1052             vector.append(qvariant_cast<QTextLength>(var));
1053     }
1054
1055     return vector;
1056 }
1057
1058 /*!
1059     Returns the property specified by the given \a propertyId.
1060
1061     \sa Property
1062 */
1063 QVariant QTextFormat::property(int propertyId) const
1064 {
1065     return d ? d->property(propertyId) : QVariant();
1066 }
1067
1068 /*!
1069     Sets the property specified by the \a propertyId to the given \a value.
1070
1071     \sa Property
1072 */
1073 void QTextFormat::setProperty(int propertyId, const QVariant &value)
1074 {
1075     if (!d)
1076         d = new QTextFormatPrivate;
1077     if (!value.isValid())
1078         clearProperty(propertyId);
1079     else
1080         d->insertProperty(propertyId, value);
1081 }
1082
1083 /*!
1084     Sets the value of the property given by \a propertyId to \a value.
1085
1086     \sa lengthVectorProperty() Property
1087 */
1088 void QTextFormat::setProperty(int propertyId, const QVector<QTextLength> &value)
1089 {
1090     if (!d)
1091         d = new QTextFormatPrivate;
1092     QVariantList list;
1093     for (int i=0; i<value.size(); ++i)
1094         list << value.at(i);
1095     d->insertProperty(propertyId, list);
1096 }
1097
1098 /*!
1099     Clears the value of the property given by \a propertyId
1100
1101     \sa Property
1102 */
1103 void QTextFormat::clearProperty(int propertyId)
1104 {
1105     if (!d)
1106         return;
1107     d->clearProperty(propertyId);
1108 }
1109
1110
1111 /*!
1112     \fn void QTextFormat::setObjectType(int type)
1113
1114     Sets the text format's object type to \a type.
1115
1116     \sa ObjectTypes, objectType()
1117 */
1118
1119
1120 /*!
1121     \fn int QTextFormat::objectType() const
1122
1123     Returns the text format's object type.
1124
1125     \sa ObjectTypes, setObjectType()
1126 */
1127
1128
1129 /*!
1130     Returns the index of the format object, or -1 if the format object is invalid.
1131
1132     \sa setObjectIndex()
1133 */
1134 int QTextFormat::objectIndex() const
1135 {
1136     if (!d)
1137         return -1;
1138     const QVariant prop = d->property(ObjectIndex);
1139     if (prop.userType() != QVariant::Int) // ####
1140         return -1;
1141     return prop.toInt();
1142 }
1143
1144 /*!
1145     \fn void QTextFormat::setObjectIndex(int index)
1146
1147     Sets the format object's object \a index.
1148
1149     \sa objectIndex()
1150 */
1151 void QTextFormat::setObjectIndex(int o)
1152 {
1153     if (o == -1) {
1154         if (d)
1155             d->clearProperty(ObjectIndex);
1156     } else {
1157         if (!d)
1158             d = new QTextFormatPrivate;
1159         // ### type
1160         d->insertProperty(ObjectIndex, o);
1161     }
1162 }
1163
1164 /*!
1165     Returns true if the text format has a property with the given \a
1166     propertyId; otherwise returns false.
1167
1168     \sa properties() Property
1169 */
1170 bool QTextFormat::hasProperty(int propertyId) const
1171 {
1172     return d ? d->hasProperty(propertyId) : false;
1173 }
1174
1175 /*
1176     Returns the property type for the given \a propertyId.
1177
1178     \sa hasProperty() allPropertyIds() Property
1179 */
1180
1181 /*!
1182     Returns a map with all properties of this text format.
1183 */
1184 QMap<int, QVariant> QTextFormat::properties() const
1185 {
1186     QMap<int, QVariant> map;
1187     if (d) {
1188         for (int i = 0; i < d->props.count(); ++i)
1189             map.insert(d->props.at(i).key, d->props.at(i).value);
1190     }
1191     return map;
1192 }
1193
1194 /*!
1195     \since 4.3
1196     Returns the number of properties stored in the format.
1197 */
1198 int QTextFormat::propertyCount() const
1199 {
1200     return d ? d->props.count() : 0;
1201 }
1202
1203 /*!
1204     \fn bool QTextFormat::operator!=(const QTextFormat &other) const
1205
1206     Returns true if this text format is different from the \a other text
1207     format.
1208 */
1209
1210
1211 /*!
1212     \fn bool QTextFormat::operator==(const QTextFormat &other) const
1213
1214     Returns true if this text format is the same as the \a other text
1215     format.
1216 */
1217 bool QTextFormat::operator==(const QTextFormat &rhs) const
1218 {
1219     if (format_type != rhs.format_type)
1220         return false;
1221
1222     if (d == rhs.d)
1223         return true;
1224
1225     if (d && d->props.isEmpty() && !rhs.d)
1226         return true;
1227
1228     if (!d && rhs.d && rhs.d->props.isEmpty())
1229         return true;
1230
1231     if (!d || !rhs.d)
1232         return false;
1233
1234     return *d == *rhs.d;
1235 }
1236
1237 /*!
1238     \class QTextCharFormat
1239     \reentrant
1240
1241     \brief The QTextCharFormat class provides formatting information for
1242     characters in a QTextDocument.
1243
1244     \ingroup richtext-processing
1245
1246     The character format of text in a document specifies the visual properties
1247     of the text, as well as information about its role in a hypertext document.
1248
1249     The font used can be set by supplying a font to the setFont() function, and
1250     each aspect of its appearance can be adjusted to give the desired effect.
1251     setFontFamily() and setFontPointSize() define the font's family (e.g. Times)
1252     and printed size; setFontWeight() and setFontItalic() provide control over
1253     the style of the font. setFontUnderline(), setFontOverline(),
1254     setFontStrikeOut(), and setFontFixedPitch() provide additional effects for
1255     text.
1256
1257     The color is set with setForeground(). If the text is intended to be used
1258     as an anchor (for hyperlinks), this can be enabled with setAnchor(). The
1259     setAnchorHref() and setAnchorNames() functions are used to specify the
1260     information about the hyperlink's destination and the anchor's name.
1261
1262     \sa QTextFormat QTextBlockFormat QTextTableFormat QTextListFormat
1263 */
1264
1265 /*!
1266     \enum QTextCharFormat::VerticalAlignment
1267
1268     This enum describes the ways that adjacent characters can be vertically
1269     aligned.
1270
1271     \value AlignNormal  Adjacent characters are positioned in the standard
1272                         way for text in the writing system in use.
1273     \value AlignSuperScript Characters are placed above the base line for
1274                             normal text.
1275     \value AlignSubScript   Characters are placed below the base line for
1276                             normal text.
1277     \value AlignMiddle The center of the object is vertically aligned with the
1278                        base line. Currently, this is only implemented for
1279                        inline objects.
1280     \value AlignBottom The bottom edge of the object is vertically aligned with
1281                        the base line.
1282     \value AlignTop    The top edge of the object is vertically aligned with
1283                        the base line.
1284     \value AlignBaseline The base lines of the characters are aligned.
1285 */
1286
1287 /*!
1288     \enum QTextCharFormat::UnderlineStyle
1289
1290     This enum describes the different ways drawing underlined text.
1291
1292     \value NoUnderline          Text is draw without any underlining decoration.
1293     \value SingleUnderline      A line is drawn using Qt::SolidLine.
1294     \value DashUnderline        Dashes are drawn using Qt::DashLine.
1295     \value DotLine              Dots are drawn using Qt::DotLine;
1296     \value DashDotLine          Dashs and dots are drawn using Qt::DashDotLine.
1297     \value DashDotDotLine       Underlines draw drawn using Qt::DashDotDotLine.
1298     \value WaveUnderline        The text is underlined using a wave shaped line.
1299     \value SpellCheckUnderline  The underline is drawn depending on the QStyle::SH_SpellCeckUnderlineStyle
1300                                 style hint of the QApplication style. By default this is mapped to
1301                                 WaveUnderline, on Mac OS X it is mapped to DashDotLine.
1302
1303     \sa Qt::PenStyle
1304 */
1305
1306 /*!
1307     \fn QTextCharFormat::QTextCharFormat()
1308
1309     Constructs a new character format object.
1310 */
1311 QTextCharFormat::QTextCharFormat() : QTextFormat(CharFormat) {}
1312
1313 /*!
1314     \internal
1315     \fn QTextCharFormat::QTextCharFormat(const QTextFormat &other)
1316
1317     Creates a new character format with the same attributes as the \a given
1318     text format.
1319 */
1320 QTextCharFormat::QTextCharFormat(const QTextFormat &fmt)
1321  : QTextFormat(fmt)
1322 {
1323 }
1324
1325 /*!
1326     \fn bool QTextCharFormat::isValid() const
1327
1328     Returns true if this character format is valid; otherwise returns
1329     false.
1330 */
1331
1332
1333 /*!
1334     \fn void QTextCharFormat::setFontFamily(const QString &family)
1335
1336     Sets the text format's font \a family.
1337
1338     \sa setFont()
1339 */
1340
1341
1342 /*!
1343     \fn QString QTextCharFormat::fontFamily() const
1344
1345     Returns the text format's font family.
1346
1347     \sa font()
1348 */
1349
1350
1351 /*!
1352     \fn void QTextCharFormat::setFontPointSize(qreal size)
1353
1354     Sets the text format's font \a size.
1355
1356     \sa setFont()
1357 */
1358
1359
1360 /*!
1361     \fn qreal QTextCharFormat::fontPointSize() const
1362
1363     Returns the font size used to display text in this format.
1364
1365     \sa font()
1366 */
1367
1368
1369 /*!
1370     \fn void QTextCharFormat::setFontWeight(int weight)
1371
1372     Sets the text format's font weight to \a weight.
1373
1374     \sa setFont(), QFont::Weight
1375 */
1376
1377
1378 /*!
1379     \fn int QTextCharFormat::fontWeight() const
1380
1381     Returns the text format's font weight.
1382
1383     \sa font(), QFont::Weight
1384 */
1385
1386
1387 /*!
1388     \fn void QTextCharFormat::setFontItalic(bool italic)
1389
1390     If \a italic is true, sets the text format's font to be italic; otherwise
1391     the font will be non-italic.
1392
1393     \sa setFont()
1394 */
1395
1396
1397 /*!
1398     \fn bool QTextCharFormat::fontItalic() const
1399
1400     Returns true if the text format's font is italic; otherwise
1401     returns false.
1402
1403     \sa font()
1404 */
1405
1406
1407 /*!
1408     \fn void QTextCharFormat::setFontUnderline(bool underline)
1409
1410     If \a underline is true, sets the text format's font to be underlined;
1411     otherwise it is displayed non-underlined.
1412
1413     \sa setFont()
1414 */
1415
1416
1417 /*!
1418     \fn bool QTextCharFormat::fontUnderline() const
1419
1420     Returns true if the text format's font is underlined; otherwise
1421     returns false.
1422
1423     \sa font()
1424 */
1425 bool QTextCharFormat::fontUnderline() const
1426 {
1427     if (hasProperty(TextUnderlineStyle))
1428         return underlineStyle() == SingleUnderline;
1429     return boolProperty(FontUnderline);
1430 }
1431
1432 /*!
1433     \fn UnderlineStyle QTextCharFormat::underlineStyle() const
1434     \since 4.2
1435
1436     Returns the style of underlining the text.
1437 */
1438
1439 /*!
1440     \fn void QTextCharFormat::setUnderlineStyle(UnderlineStyle style)
1441     \since 4.2
1442
1443     Sets the style of underlining the text to \a style.
1444 */
1445 void QTextCharFormat::setUnderlineStyle(UnderlineStyle style)
1446 {
1447     setProperty(TextUnderlineStyle, style);
1448     // for compatibility
1449     setProperty(FontUnderline, style == SingleUnderline);
1450 }
1451
1452 /*!
1453     \fn void QTextCharFormat::setFontOverline(bool overline)
1454
1455     If \a overline is true, sets the text format's font to be overlined;
1456     otherwise the font is displayed non-overlined.
1457
1458     \sa setFont()
1459 */
1460
1461
1462 /*!
1463     \fn bool QTextCharFormat::fontOverline() const
1464
1465     Returns true if the text format's font is overlined; otherwise
1466     returns false.
1467
1468     \sa font()
1469 */
1470
1471
1472 /*!
1473     \fn void QTextCharFormat::setFontStrikeOut(bool strikeOut)
1474
1475     If \a strikeOut is true, sets the text format's font with strike-out
1476     enabled (with a horizontal line through it); otherwise it is displayed
1477     without strikeout.
1478
1479     \sa setFont()
1480 */
1481
1482
1483 /*!
1484     \fn bool QTextCharFormat::fontStrikeOut() const
1485
1486     Returns true if the text format's font is struck out (has a horizontal line
1487     drawn through it); otherwise returns false.
1488
1489     \sa font()
1490 */
1491
1492
1493 /*!
1494     \since 4.5
1495     \fn void QTextCharFormat::setFontStyleHint(QFont::StyleHint hint, QFont::StyleStrategy strategy)
1496
1497     Sets the font style \a hint and \a strategy.
1498
1499     Qt does not support style hints on X11 since this information is not provided by the window system.
1500
1501     \sa setFont()
1502     \sa QFont::setStyleHint()
1503 */
1504
1505
1506 /*!
1507     \since 4.5
1508     \fn void QTextCharFormat::setFontStyleStrategy(QFont::StyleStrategy strategy)
1509
1510     Sets the font style \a strategy.
1511
1512     \sa setFont()
1513     \sa QFont::setStyleStrategy()
1514 */
1515
1516
1517 /*!
1518     \since 4.5
1519     \fn void QTextCharFormat::setFontKerning(bool enable)
1520     Enables kerning for this font if \a enable is true; otherwise disables it.
1521
1522     When kerning is enabled, glyph metrics do not add up anymore, even for
1523     Latin text. In other words, the assumption that width('a') + width('b')
1524     is equal to width("ab") is not neccesairly true.
1525
1526     \sa setFont()
1527 */
1528
1529
1530 /*!
1531     \fn QTextCharFormat::StyleHint QTextCharFormat::fontStyleHint() const
1532     \since 4.5
1533
1534     Returns the font style hint.
1535
1536     \sa setFontStyleHint(), font()
1537 */
1538
1539
1540 /*!
1541     \since 4.5
1542     \fn QTextCharFormat::StyleStrategy QTextCharFormat::fontStyleStrategy() const
1543
1544     Returns the current font style strategy.
1545
1546     \sa setFontStyleStrategy()
1547     \sa font()
1548 */
1549
1550
1551 /*!
1552     \since 4.5
1553     \fn  bool QTextCharFormat::fontKerning() const
1554     Returns true if the font kerning is enabled.
1555
1556     \sa setFontKerning()
1557     \sa font()
1558 */
1559
1560
1561 /*!
1562     \fn void QTextCharFormat::setFontFixedPitch(bool fixedPitch)
1563
1564     If \a fixedPitch is true, sets the text format's font to be fixed pitch;
1565     otherwise a non-fixed pitch font is used.
1566
1567     \sa setFont()
1568 */
1569
1570
1571 /*!
1572     \fn bool QTextCharFormat::fontFixedPitch() const
1573
1574     Returns true if the text format's font is fixed pitch; otherwise
1575     returns false.
1576
1577     \sa font()
1578 */
1579
1580 /*!
1581     \since 4.8
1582
1583     \fn void QTextCharFormat::setFontHintingPreference(QFont::HintingPreference hintingPreference)
1584
1585     Sets the hinting preference of the text format's font to be \a hintingPreference.
1586
1587     \sa setFont(), QFont::setHintingPreference()
1588 */
1589
1590 /*!
1591     \since 4.8
1592
1593     \fn QFont::HintingPreference QTextCharFormat::fontHintingPreference() const
1594
1595     Returns the hinting preference set for this text format.
1596
1597     \sa font(), QFont::hintingPreference()
1598 */
1599
1600 /*!
1601     \fn QPen QTextCharFormat::textOutline() const
1602
1603     Returns the pen used to draw the outlines of characters in this format.
1604 */
1605
1606
1607 /*!
1608     \fn void QTextCharFormat::setTextOutline(const QPen &pen)
1609
1610     Sets the pen used to draw the outlines of characters to the given \a pen.
1611 */
1612
1613 /*!
1614     \fn void QTextCharFormat::setToolTip(const QString &text)
1615     \since 4.3
1616
1617     Sets the tool tip for a fragment of text to the given \a text.
1618 */
1619
1620 /*!
1621     \fn QString QTextCharFormat::toolTip() const
1622     \since 4.3
1623
1624     Returns the tool tip that is displayed for a fragment of text.
1625 */
1626
1627 /*!
1628     \fn void QTextFormat::setForeground(const QBrush &brush)
1629
1630     Sets the foreground brush to the specified \a brush. The foreground
1631     brush is mostly used to render text.
1632
1633     \sa foreground() clearForeground() setBackground()
1634 */
1635
1636
1637 /*!
1638     \fn QBrush QTextFormat::foreground() const
1639
1640     Returns the brush used to render foreground details, such as text,
1641     frame outlines, and table borders.
1642
1643     \sa setForeground() clearForeground() background()
1644 */
1645
1646 /*!
1647     \fn void QTextFormat::clearForeground()
1648
1649     Clears the brush used to paint the document's foreground. The default
1650     brush will be used.
1651
1652     \sa foreground() setForeground() clearBackground()
1653 */
1654
1655
1656 /*!
1657     \fn void QTextCharFormat::setAnchor(bool anchor)
1658
1659     If \a anchor is true, text with this format represents an anchor, and is
1660     formatted in the appropriate way; otherwise the text is formatted normally.
1661     (Anchors are hyperlinks which are often shown underlined and in a different
1662     color from plain text.)
1663
1664     The way the text is rendered is independent of whether or not the format
1665     has a valid anchor defined. Use setAnchorHref(), and optionally
1666     setAnchorNames() to create a hypertext link.
1667
1668     \sa isAnchor()
1669 */
1670
1671
1672 /*!
1673     \fn bool QTextCharFormat::isAnchor() const
1674
1675     Returns true if the text is formatted as an anchor; otherwise
1676     returns false.
1677
1678     \sa setAnchor() setAnchorHref() setAnchorNames()
1679 */
1680
1681
1682 /*!
1683     \fn void QTextCharFormat::setAnchorHref(const QString &value)
1684
1685     Sets the hypertext link for the text format to the given \a value.
1686     This is typically a URL like "http://example.com/index.html".
1687
1688     The anchor will be displayed with the \a value as its display text;
1689     if you want to display different text call setAnchorNames().
1690
1691     To format the text as a hypertext link use setAnchor().
1692 */
1693
1694
1695 /*!
1696     \fn QString QTextCharFormat::anchorHref() const
1697
1698     Returns the text format's hypertext link, or an empty string if
1699     none has been set.
1700 */
1701
1702
1703 /*!
1704     \fn void QTextCharFormat::setAnchorName(const QString &name)
1705     \obsolete
1706
1707     This function is deprecated. Use setAnchorNames() instead.
1708
1709     Sets the text format's anchor \a name. For the anchor to work as a
1710     hyperlink, the destination must be set with setAnchorHref() and
1711     the anchor must be enabled with setAnchor().
1712 */
1713
1714 /*!
1715     \fn void QTextCharFormat::setAnchorNames(const QStringList &names)
1716     \since 4.3
1717
1718     Sets the text format's anchor \a names. For the anchor to work as a
1719     hyperlink, the destination must be set with setAnchorHref() and
1720     the anchor must be enabled with setAnchor().
1721 */
1722
1723 /*!
1724     \fn QString QTextCharFormat::anchorName() const
1725     \obsolete
1726
1727     This function is deprecated. Use anchorNames() instead.
1728
1729     Returns the anchor name associated with this text format, or an empty
1730     string if none has been set. If the anchor name is set, text with this
1731     format can be the destination of a hypertext link.
1732 */
1733 QString QTextCharFormat::anchorName() const
1734 {
1735     QVariant prop = property(AnchorName);
1736     if (prop.userType() == QVariant::StringList)
1737         return prop.toStringList().value(0);
1738     else if (prop.userType() != QVariant::String)
1739         return QString();
1740     return prop.toString();
1741 }
1742
1743 /*!
1744     \fn QStringList QTextCharFormat::anchorNames() const
1745     \since 4.3
1746
1747     Returns the anchor names associated with this text format, or an empty
1748     string list if none has been set. If the anchor names are set, text with this
1749     format can be the destination of a hypertext link.
1750 */
1751 QStringList QTextCharFormat::anchorNames() const
1752 {
1753     QVariant prop = property(AnchorName);
1754     if (prop.userType() == QVariant::StringList)
1755         return prop.toStringList();
1756     else if (prop.userType() != QVariant::String)
1757         return QStringList();
1758     return QStringList(prop.toString());
1759 }
1760
1761
1762 /*!
1763     \fn void QTextCharFormat::setTableCellRowSpan(int tableCellRowSpan)
1764     \internal
1765
1766     If this character format is applied to characters in a table cell,
1767     the cell will span \a tableCellRowSpan rows.
1768 */
1769
1770
1771 /*!
1772     \fn int QTextCharFormat::tableCellRowSpan() const
1773     \internal
1774
1775     If this character format is applied to characters in a table cell,
1776     this function returns the number of rows spanned by the text (this may
1777     be 1); otherwise it returns 1.
1778 */
1779
1780 /*!
1781     \fn void QTextCharFormat::setTableCellColumnSpan(int tableCellColumnSpan)
1782     \internal
1783
1784     If this character format is applied to characters in a table cell,
1785     the cell will span \a tableCellColumnSpan columns.
1786 */
1787
1788
1789 /*!
1790     \fn int QTextCharFormat::tableCellColumnSpan() const
1791     \internal
1792
1793     If this character format is applied to characters in a table cell,
1794     this function returns the number of columns spanned by the text (this
1795     may be 1); otherwise it returns 1.
1796 */
1797
1798 /*!
1799     \fn void QTextCharFormat::setUnderlineColor(const QColor &color)
1800
1801     Sets the underline color used for the characters with this format to
1802     the \a color specified.
1803
1804     \sa underlineColor()
1805 */
1806
1807 /*!
1808     \fn QColor QTextCharFormat::underlineColor() const
1809
1810     Returns the color used to underline the characters with this format.
1811
1812     \sa setUnderlineColor()
1813 */
1814
1815 /*!
1816     \fn void QTextCharFormat::setVerticalAlignment(VerticalAlignment alignment)
1817
1818     Sets the vertical alignment used for the characters with this format to
1819     the \a alignment specified.
1820
1821     \sa verticalAlignment()
1822 */
1823
1824 /*!
1825     \fn VerticalAlignment QTextCharFormat::verticalAlignment() const
1826
1827     Returns the vertical alignment used for characters with this format.
1828
1829     \sa setVerticalAlignment()
1830 */
1831
1832 /*!
1833     Sets the text format's \a font.
1834 */
1835 void QTextCharFormat::setFont(const QFont &font)
1836 {
1837     setFontFamily(font.family());
1838
1839     const qreal pointSize = font.pointSizeF();
1840     if (pointSize > 0) {
1841         setFontPointSize(pointSize);
1842     } else {
1843         const int pixelSize = font.pixelSize();
1844         if (pixelSize > 0)
1845             setProperty(QTextFormat::FontPixelSize, pixelSize);
1846     }
1847
1848     setFontWeight(font.weight());
1849     setFontItalic(font.italic());
1850     setUnderlineStyle(font.underline() ? SingleUnderline : NoUnderline);
1851     setFontOverline(font.overline());
1852     setFontStrikeOut(font.strikeOut());
1853     setFontFixedPitch(font.fixedPitch());
1854     setFontCapitalization(font.capitalization());
1855     setFontWordSpacing(font.wordSpacing());
1856     if (font.letterSpacingType() == QFont::PercentageSpacing)
1857         setFontLetterSpacing(font.letterSpacing());
1858     setFontStyleHint(font.styleHint());
1859     setFontStyleStrategy(font.styleStrategy());
1860     setFontKerning(font.kerning());
1861 }
1862
1863 /*!
1864     Returns the font for this character format.
1865 */
1866 QFont QTextCharFormat::font() const
1867 {
1868     return d ? d->font() : QFont();
1869 }
1870
1871 /*!
1872     \class QTextBlockFormat
1873     \reentrant
1874
1875     \brief The QTextBlockFormat class provides formatting information for
1876     blocks of text in a QTextDocument.
1877
1878     \ingroup richtext-processing
1879
1880     A document is composed of a list of blocks, represented by QTextBlock
1881     objects. Each block can contain an item of some kind, such as a
1882     paragraph of text, a table, a list, or an image. Every block has an
1883     associated QTextBlockFormat that specifies its characteristics.
1884
1885     To cater for left-to-right and right-to-left languages you can set
1886     a block's direction with setDirection(). Paragraph alignment is
1887     set with setAlignment(). Margins are controlled by setTopMargin(),
1888     setBottomMargin(), setLeftMargin(), setRightMargin(). Overall
1889     indentation is set with setIndent(), the indentation of the first
1890     line with setTextIndent().
1891
1892     Line spacing is set with setLineHeight() and retrieved via lineHeight()
1893     and lineHeightType(). The types of line spacing available are in the
1894     LineHeightTypes enum.
1895
1896     Line breaking can be enabled and disabled with setNonBreakableLines().
1897
1898     The brush used to paint the paragraph's background
1899     is set with \l{QTextFormat::setBackground()}{setBackground()}, and other
1900     aspects of the text's appearance can be customized by using the
1901     \l{QTextFormat::setProperty()}{setProperty()} function with the
1902     \c OutlinePen, \c ForegroundBrush, and \c BackgroundBrush
1903     \l{QTextFormat::Property} values.
1904
1905     If a text block is part of a list, it can also have a list format that
1906     is accessible with the listFormat() function.
1907
1908     \sa QTextBlock, QTextCharFormat
1909 */
1910
1911 /*!
1912     \since 4.8
1913     \enum QTextBlockFormat::LineHeightTypes
1914
1915     This enum describes the various types of line spacing support paragraphs can have.
1916
1917     \value SingleHeight This is the default line height: single spacing.
1918     \value ProportionalHeight This sets the spacing proportional to the line (in percentage).
1919                               For example, set to 200 for double spacing.
1920     \value FixedHeight This sets the line height to a fixed line height (in pixels).
1921     \value MinimumHeight This sets the minimum line height (in pixels).
1922     \value LineDistanceHeight This adds the specified height between lines (in pixels).
1923
1924     \sa lineHeight(), lineHeightType(), setLineHeight()
1925 */
1926
1927 /*!
1928     \fn QTextBlockFormat::QTextBlockFormat()
1929
1930     Constructs a new QTextBlockFormat.
1931 */
1932 QTextBlockFormat::QTextBlockFormat() : QTextFormat(BlockFormat) {}
1933
1934 /*!
1935     \internal
1936     \fn QTextBlockFormat::QTextBlockFormat(const QTextFormat &other)
1937
1938     Creates a new block format with the same attributes as the \a given
1939     text format.
1940 */
1941 QTextBlockFormat::QTextBlockFormat(const QTextFormat &fmt)
1942  : QTextFormat(fmt)
1943 {
1944 }
1945
1946 /*!
1947     \since 4.4
1948     Sets the tab positions for the text block to those specified by
1949     \a tabs.
1950
1951     \sa tabPositions()
1952 */
1953 void QTextBlockFormat::setTabPositions(const QList<QTextOption::Tab> &tabs)
1954 {
1955     QList<QVariant> list;
1956     QList<QTextOption::Tab>::ConstIterator iter = tabs.constBegin();
1957     while (iter != tabs.constEnd()) {
1958         QVariant v;
1959         v.setValue<QTextOption::Tab>(*iter);
1960         list.append(v);
1961         ++iter;
1962     }
1963     setProperty(TabPositions, list);
1964 }
1965
1966 /*!
1967     \since 4.4
1968     Returns a list of tab positions defined for the text block.
1969
1970     \sa setTabPositions()
1971 */
1972 QList<QTextOption::Tab> QTextBlockFormat::tabPositions() const
1973 {
1974     QVariant variant = property(TabPositions);
1975     if(variant.isNull())
1976         return QList<QTextOption::Tab>();
1977     QList<QTextOption::Tab> answer;
1978     QList<QVariant> variantsList = qvariant_cast<QList<QVariant> >(variant);
1979     QList<QVariant>::Iterator iter = variantsList.begin();
1980     while(iter != variantsList.end()) {
1981         answer.append( qvariant_cast<QTextOption::Tab>(*iter));
1982         ++iter;
1983     }
1984     return answer;
1985 }
1986
1987 /*!
1988     \fn QTextBlockFormat::isValid() const
1989
1990     Returns true if this block format is valid; otherwise returns
1991     false.
1992 */
1993
1994 /*!
1995     \fn void QTextFormat::setLayoutDirection(Qt::LayoutDirection direction)
1996
1997     Sets the document's layout direction to the specified \a direction.
1998
1999     \sa layoutDirection()
2000 */
2001
2002
2003 /*!
2004     \fn Qt::LayoutDirection QTextFormat::layoutDirection() const
2005
2006     Returns the document's layout direction.
2007
2008     \sa setLayoutDirection()
2009 */
2010
2011
2012 /*!
2013     \fn void QTextBlockFormat::setAlignment(Qt::Alignment alignment)
2014
2015     Sets the paragraph's \a alignment.
2016
2017     \sa alignment()
2018 */
2019
2020
2021 /*!
2022     \fn Qt::Alignment QTextBlockFormat::alignment() const
2023
2024     Returns the paragraph's alignment.
2025
2026     \sa setAlignment()
2027 */
2028
2029
2030 /*!
2031     \fn void QTextBlockFormat::setTopMargin(qreal margin)
2032
2033     Sets the paragraph's top \a margin.
2034
2035     \sa topMargin() setBottomMargin() setLeftMargin() setRightMargin()
2036 */
2037
2038
2039 /*!
2040     \fn qreal QTextBlockFormat::topMargin() const
2041
2042     Returns the paragraph's top margin.
2043
2044     \sa setTopMargin() bottomMargin()
2045 */
2046
2047
2048 /*!
2049     \fn void QTextBlockFormat::setBottomMargin(qreal margin)
2050
2051     Sets the paragraph's bottom \a margin.
2052
2053     \sa bottomMargin() setTopMargin() setLeftMargin() setRightMargin()
2054 */
2055
2056
2057 /*!
2058     \fn qreal QTextBlockFormat::bottomMargin() const
2059
2060     Returns the paragraph's bottom margin.
2061
2062     \sa setBottomMargin() topMargin()
2063 */
2064
2065
2066 /*!
2067     \fn void QTextBlockFormat::setLeftMargin(qreal margin)
2068
2069     Sets the paragraph's left \a margin. Indentation can be applied separately
2070     with setIndent().
2071
2072     \sa leftMargin() setRightMargin() setTopMargin() setBottomMargin()
2073 */
2074
2075
2076 /*!
2077     \fn qreal QTextBlockFormat::leftMargin() const
2078
2079     Returns the paragraph's left margin.
2080
2081     \sa setLeftMargin() rightMargin() indent()
2082 */
2083
2084
2085 /*!
2086     \fn void QTextBlockFormat::setRightMargin(qreal margin)
2087
2088     Sets the paragraph's right \a margin.
2089
2090     \sa rightMargin() setLeftMargin() setTopMargin() setBottomMargin()
2091 */
2092
2093
2094 /*!
2095     \fn qreal QTextBlockFormat::rightMargin() const
2096
2097     Returns the paragraph's right margin.
2098
2099     \sa setRightMargin() leftMargin()
2100 */
2101
2102
2103 /*!
2104     \fn void QTextBlockFormat::setTextIndent(qreal indent)
2105
2106     Sets the \a indent for the first line in the block. This allows the first
2107     line of a paragraph to be indented differently to the other lines,
2108     enhancing the readability of the text.
2109
2110     \sa textIndent() setLeftMargin() setRightMargin() setTopMargin() setBottomMargin()
2111 */
2112
2113
2114 /*!
2115     \fn qreal QTextBlockFormat::textIndent() const
2116
2117     Returns the paragraph's text indent.
2118
2119     \sa setTextIndent()
2120 */
2121
2122
2123 /*!
2124     \fn void QTextBlockFormat::setIndent(int indentation)
2125
2126     Sets the paragraph's \a indentation. Margins are set independently of
2127     indentation with setLeftMargin() and setTextIndent().
2128     The \a indentation is an integer that is multiplied with the document-wide
2129     standard indent, resulting in the actual indent of the paragraph.
2130
2131     \sa indent() QTextDocument::indentWidth()
2132 */
2133
2134
2135 /*!
2136     \fn int QTextBlockFormat::indent() const
2137
2138     Returns the paragraph's indent.
2139
2140     \sa setIndent()
2141 */
2142
2143
2144 /*!
2145     \fn void QTextBlockFormat::setLineHeight(qreal height, int heightType)
2146     \since 4.8
2147
2148     Sets the line height for the paragraph to the value given by \a height
2149     which is dependent on \a heightType in the way described by the
2150     LineHeightTypes enum.
2151
2152     \sa LineHeightTypes, lineHeight(), lineHeightType()
2153 */
2154
2155
2156 /*!
2157     \fn qreal QTextBlockFormat::lineHeight(qreal scriptLineHeight, qreal scaling) const
2158     \since 4.8
2159
2160     Returns the height of the lines in the paragraph based on the height of the
2161     script line given by \a scriptLineHeight and the specified \a scaling
2162     factor.
2163
2164     The value that is returned is also dependent on the given LineHeightType of
2165     the paragraph as well as the LineHeight setting that has been set for the
2166     paragraph.
2167
2168     The scaling is needed for heights that include a fixed number of pixels, to
2169     scale them appropriately for printing.
2170
2171     \sa LineHeightTypes, setLineHeight(), lineHeightType()
2172 */
2173
2174
2175 /*!
2176     \fn qreal QTextBlockFormat::lineHeight() const
2177     \since 4.8
2178
2179     This returns the LineHeight property for the paragraph.
2180
2181     \sa LineHeightTypes, setLineHeight(), lineHeightType()
2182 */
2183
2184
2185 /*!
2186     \fn qreal QTextBlockFormat::lineHeightType() const
2187     \since 4.8
2188
2189     This returns the LineHeightType property of the paragraph.
2190
2191     \sa LineHeightTypes, setLineHeight(), lineHeight()
2192 */
2193
2194
2195 /*!
2196     \fn void QTextBlockFormat::setNonBreakableLines(bool b)
2197
2198     If \a b is true, the lines in the paragraph are treated as
2199     non-breakable; otherwise they are breakable.
2200
2201     \sa nonBreakableLines()
2202 */
2203
2204
2205 /*!
2206     \fn bool QTextBlockFormat::nonBreakableLines() const
2207
2208     Returns true if the lines in the paragraph are non-breakable;
2209     otherwise returns false.
2210
2211     \sa setNonBreakableLines()
2212 */
2213
2214 /*!
2215     \fn QTextFormat::PageBreakFlags QTextBlockFormat::pageBreakPolicy() const
2216     \since 4.2
2217
2218     Returns the currently set page break policy for the paragraph. The default is
2219     QTextFormat::PageBreak_Auto.
2220
2221     \sa setPageBreakPolicy()
2222 */
2223
2224 /*!
2225     \fn void QTextBlockFormat::setPageBreakPolicy(PageBreakFlags policy)
2226     \since 4.2
2227
2228     Sets the page break policy for the paragraph to \a policy.
2229
2230     \sa pageBreakPolicy()
2231 */
2232
2233 /*!
2234     \class QTextListFormat
2235     \reentrant
2236
2237     \brief The QTextListFormat class provides formatting information for
2238     lists in a QTextDocument.
2239
2240     \ingroup richtext-processing
2241
2242     A list is composed of one or more items, represented as text blocks.
2243     The list's format specifies the appearance of items in the list.
2244     In particular, it determines the indentation and the style of each item.
2245
2246     The indentation of the items is an integer value that causes each item to
2247     be offset from the left margin by a certain amount. This value is read with
2248     indent() and set with setIndent().
2249
2250     The style used to decorate each item is set with setStyle() and can be read
2251     with the style() function. The style controls the type of bullet points and
2252     numbering scheme used for items in the list. Note that lists that use the
2253     decimal numbering scheme begin counting at 1 rather than 0.
2254
2255     Style properties can be set to further configure the appearance of list
2256     items; for example, the ListNumberPrefix and ListNumberSuffix properties
2257     can be used to customize the numbers used in an ordered list so that they
2258     appear as (1), (2), (3), etc.:
2259
2260     \snippet doc/src/snippets/textdocument-listitemstyles/mainwindow.cpp add a styled, ordered list
2261
2262     \sa QTextList
2263 */
2264
2265 /*!
2266     \enum QTextListFormat::Style
2267
2268     This enum describes the symbols used to decorate list items:
2269
2270     \value ListDisc        a filled circle
2271     \value ListCircle      an empty circle
2272     \value ListSquare      a filled square
2273     \value ListDecimal     decimal values in ascending order
2274     \value ListLowerAlpha  lower case Latin characters in alphabetical order
2275     \value ListUpperAlpha  upper case Latin characters in alphabetical order
2276     \value ListLowerRoman  lower case roman numerals (supports up to 4999 items only)
2277     \value ListUpperRoman  upper case roman numerals (supports up to 4999 items only)
2278     \omitvalue ListStyleUndefined
2279 */
2280
2281 /*!
2282     \fn QTextListFormat::QTextListFormat()
2283
2284     Constructs a new list format object.
2285 */
2286 QTextListFormat::QTextListFormat()
2287     : QTextFormat(ListFormat)
2288 {
2289     setIndent(1);
2290 }
2291
2292 /*!
2293     \internal
2294     \fn QTextListFormat::QTextListFormat(const QTextFormat &other)
2295
2296     Creates a new list format with the same attributes as the \a given
2297     text format.
2298 */
2299 QTextListFormat::QTextListFormat(const QTextFormat &fmt)
2300  : QTextFormat(fmt)
2301 {
2302 }
2303
2304 /*!
2305     \fn bool QTextListFormat::isValid() const
2306
2307     Returns true if this list format is valid; otherwise
2308     returns false.
2309 */
2310
2311 /*!
2312     \fn void QTextListFormat::setStyle(Style style)
2313
2314     Sets the list format's \a style.
2315
2316     \sa style() Style
2317 */
2318
2319 /*!
2320     \fn Style QTextListFormat::style() const
2321
2322     Returns the list format's style.
2323
2324     \sa setStyle() Style
2325 */
2326
2327
2328 /*!
2329     \fn void QTextListFormat::setIndent(int indentation)
2330
2331     Sets the list format's \a indentation.
2332     The indentation is multiplied by the QTextDocument::indentWidth
2333     property to get the effective indent in pixels.
2334
2335     \sa indent()
2336 */
2337
2338
2339 /*!
2340     \fn int QTextListFormat::indent() const
2341
2342     Returns the list format's indentation.
2343     The indentation is multiplied by the QTextDocument::indentWidth
2344     property to get the effective indent in pixels.
2345
2346     \sa setIndent()
2347 */
2348
2349 /*!
2350     \fn void QTextListFormat::setNumberPrefix(const QString &numberPrefix)
2351     \since 4.8
2352
2353     Sets the list format's number prefix to the string specified by
2354     \a numberPrefix. This can be used with all sorted list types. It does not
2355     have any effect on unsorted list types.
2356
2357     The default prefix is an empty string.
2358
2359     \sa numberPrefix()
2360 */
2361
2362 /*!
2363     \fn int QTextListFormat::numberPrefix() const
2364     \since 4.8
2365
2366     Returns the list format's number prefix.
2367
2368     \sa setNumberPrefix()
2369 */
2370
2371 /*!
2372     \fn void QTextListFormat::setNumberSuffix(const QString &numberSuffix)
2373     \since 4.8
2374
2375     Sets the list format's number suffix to the string specified by
2376     \a numberSuffix. This can be used with all sorted list types. It does not
2377     have any effect on unsorted list types.
2378
2379     The default suffix is ".".
2380
2381     \sa numberSuffix()
2382 */
2383
2384 /*!
2385     \fn int QTextListFormat::numberSuffix() const
2386     \since 4.8
2387
2388     Returns the list format's number suffix.
2389
2390     \sa setNumberSuffix()
2391 */
2392
2393 /*!
2394     \class QTextFrameFormat
2395     \reentrant
2396
2397     \brief The QTextFrameFormat class provides formatting information for
2398     frames in a QTextDocument.
2399
2400     \ingroup richtext-processing
2401
2402     A text frame groups together one or more blocks of text, providing a layer
2403     of structure larger than the paragraph. The format of a frame specifies
2404     how it is rendered and positioned on the screen. It does not directly
2405     specify the behavior of the text formatting within, but provides
2406     constraints on the layout of its children.
2407
2408     The frame format defines the width() and height() of the frame on the
2409     screen. Each frame can have a border() that surrounds its contents with
2410     a rectangular box. The border is surrounded by a margin() around the frame,
2411     and the contents of the frame are kept separate from the border by the
2412     frame's padding(). This scheme is similar to the box model used by Cascading
2413     Style Sheets for HTML pages.
2414
2415     \img qtextframe-style.png
2416
2417     The position() of a frame is set using setPosition() and determines how it
2418     is located relative to the surrounding text.
2419
2420     The validity of a QTextFrameFormat object can be determined with the
2421     isValid() function.
2422
2423     \sa QTextFrame QTextBlockFormat
2424 */
2425
2426 /*!
2427     \enum QTextFrameFormat::Position
2428
2429     This enum describes how a frame is located relative to the surrounding text.
2430
2431     \value InFlow
2432     \value FloatLeft
2433     \value FloatRight
2434
2435     \sa position() CssFloat
2436 */
2437
2438 /*!
2439     \enum QTextFrameFormat::BorderStyle
2440     \since 4.3
2441
2442     This enum describes different border styles for the text frame.
2443
2444     \value BorderStyle_None
2445     \value BorderStyle_Dotted
2446     \value BorderStyle_Dashed
2447     \value BorderStyle_Solid
2448     \value BorderStyle_Double
2449     \value BorderStyle_DotDash
2450     \value BorderStyle_DotDotDash
2451     \value BorderStyle_Groove
2452     \value BorderStyle_Ridge
2453     \value BorderStyle_Inset
2454     \value BorderStyle_Outset
2455
2456     \sa borderStyle() FrameBorderStyle
2457 */
2458
2459 /*!
2460     \fn QTextFrameFormat::QTextFrameFormat()
2461
2462     Constructs a text frame format object with the default properties.
2463 */
2464 QTextFrameFormat::QTextFrameFormat() : QTextFormat(FrameFormat)
2465 {
2466     setBorderStyle(BorderStyle_Outset);
2467     setBorderBrush(Qt::darkGray);
2468 }
2469
2470 /*!
2471     \internal
2472     \fn QTextFrameFormat::QTextFrameFormat(const QTextFormat &other)
2473
2474     Creates a new frame format with the same attributes as the \a given
2475     text format.
2476 */
2477 QTextFrameFormat::QTextFrameFormat(const QTextFormat &fmt)
2478  : QTextFormat(fmt)
2479 {
2480 }
2481
2482 /*!
2483     \fn QTextFrameFormat::isValid() const
2484
2485     Returns true if the format description is valid; otherwise returns false.
2486 */
2487
2488 /*!
2489     \fn QTextFrameFormat::setPosition(Position policy)
2490
2491     Sets the \a policy for positioning frames with this frame format.
2492
2493 */
2494
2495 /*!
2496     \fn Position QTextFrameFormat::position() const
2497
2498     Returns the positioning policy for frames with this frame format.
2499 */
2500
2501 /*!
2502     \fn QTextFrameFormat::setBorder(qreal width)
2503
2504     Sets the \a width (in pixels) of the frame's border.
2505 */
2506
2507 /*!
2508     \fn qreal QTextFrameFormat::border() const
2509
2510     Returns the width of the border in pixels.
2511 */
2512
2513 /*!
2514     \fn QTextFrameFormat::setBorderBrush(const QBrush &brush)
2515     \since 4.3
2516
2517     Sets the \a brush used for the frame's border.
2518 */
2519
2520 /*!
2521     \fn QBrush QTextFrameFormat::borderBrush() const
2522     \since 4.3
2523
2524     Returns the brush used for the frame's border.
2525 */
2526
2527 /*!
2528     \fn QTextFrameFormat::setBorderStyle(BorderStyle style)
2529     \since 4.3
2530
2531     Sets the \a style of the frame's border.
2532 */
2533
2534 /*!
2535     \fn BorderStyle QTextFrameFormat::borderStyle() const
2536     \since 4.3
2537
2538     Returns the style of the frame's border.
2539 */
2540
2541 /*!
2542     \fn QTextFrameFormat::setMargin(qreal margin)
2543
2544     Sets the frame's \a margin in pixels.
2545     This method also sets the left, right, top and bottom margins
2546     of the frame to the same value. The individual margins override
2547     the general margin.
2548 */
2549 void QTextFrameFormat::setMargin(qreal amargin)
2550 {
2551     setProperty(FrameMargin, amargin);
2552     setProperty(FrameTopMargin, amargin);
2553     setProperty(FrameBottomMargin, amargin);
2554     setProperty(FrameLeftMargin, amargin);
2555     setProperty(FrameRightMargin, amargin);
2556 }
2557
2558
2559 /*!
2560     \fn qreal QTextFrameFormat::margin() const
2561
2562     Returns the width of the frame's external margin in pixels.
2563 */
2564
2565 /*!
2566     \fn QTextFrameFormat::setTopMargin(qreal margin)
2567     \since 4.3
2568
2569     Sets the frame's top \a margin in pixels.
2570 */
2571
2572 /*!
2573     \fn qreal QTextFrameFormat::topMargin() const
2574     \since 4.3
2575
2576     Returns the width of the frame's top margin in pixels.
2577 */
2578 qreal QTextFrameFormat::topMargin() const
2579 {
2580     if (!hasProperty(FrameTopMargin))
2581         return margin();
2582     return doubleProperty(FrameTopMargin);
2583 }
2584
2585 /*!
2586     \fn QTextFrameFormat::setBottomMargin(qreal margin)
2587     \since 4.3
2588
2589     Sets the frame's bottom \a margin in pixels.
2590 */
2591
2592 /*!
2593     \fn qreal QTextFrameFormat::bottomMargin() const
2594     \since 4.3
2595
2596     Returns the width of the frame's bottom margin in pixels.
2597 */
2598 qreal QTextFrameFormat::bottomMargin() const
2599 {
2600     if (!hasProperty(FrameBottomMargin))
2601         return margin();
2602     return doubleProperty(FrameBottomMargin);
2603 }
2604
2605 /*!
2606     \fn QTextFrameFormat::setLeftMargin(qreal margin)
2607     \since 4.3
2608
2609     Sets the frame's left \a margin in pixels.
2610 */
2611
2612 /*!
2613     \fn qreal QTextFrameFormat::leftMargin() const
2614     \since 4.3
2615
2616     Returns the width of the frame's left margin in pixels.
2617 */
2618 qreal QTextFrameFormat::leftMargin() const
2619 {
2620     if (!hasProperty(FrameLeftMargin))
2621         return margin();
2622     return doubleProperty(FrameLeftMargin);
2623 }
2624
2625 /*!
2626     \fn QTextFrameFormat::setRightMargin(qreal margin)
2627     \since 4.3
2628
2629     Sets the frame's right \a margin in pixels.
2630 */
2631
2632 /*!
2633     \fn qreal QTextFrameFormat::rightMargin() const
2634     \since 4.3
2635
2636     Returns the width of the frame's right margin in pixels.
2637 */
2638 qreal QTextFrameFormat::rightMargin() const
2639 {
2640     if (!hasProperty(FrameRightMargin))
2641         return margin();
2642     return doubleProperty(FrameRightMargin);
2643 }
2644
2645 /*!
2646     \fn QTextFrameFormat::setPadding(qreal width)
2647
2648     Sets the \a width of the frame's internal padding in pixels.
2649 */
2650
2651 /*!
2652     \fn qreal QTextFrameFormat::padding() const
2653
2654     Returns the width of the frame's internal padding in pixels.
2655 */
2656
2657 /*!
2658     \fn QTextFrameFormat::setWidth(const QTextLength &width)
2659
2660     Sets the frame's border rectangle's \a width.
2661
2662     \sa QTextLength
2663 */
2664
2665 /*!
2666     \fn QTextFrameFormat::setWidth(qreal width)
2667     \overload
2668
2669     Convenience method that sets the width of the frame's border
2670     rectangle's width to the specified fixed \a width.
2671 */
2672
2673 /*!
2674     \fn QTextFormat::PageBreakFlags QTextFrameFormat::pageBreakPolicy() const
2675     \since 4.2
2676
2677     Returns the currently set page break policy for the frame/table. The default is
2678     QTextFormat::PageBreak_Auto.
2679
2680     \sa setPageBreakPolicy()
2681 */
2682
2683 /*!
2684     \fn void QTextFrameFormat::setPageBreakPolicy(PageBreakFlags policy)
2685     \since 4.2
2686
2687     Sets the page break policy for the frame/table to \a policy.
2688
2689     \sa pageBreakPolicy()
2690 */
2691
2692 /*!
2693     \fn QTextLength QTextFrameFormat::width() const
2694
2695     Returns the width of the frame's border rectangle.
2696
2697     \sa QTextLength
2698 */
2699
2700 /*!
2701     \fn void QTextFrameFormat::setHeight(const QTextLength &height)
2702
2703     Sets the frame's \a height.
2704 */
2705
2706 /*!
2707     \fn void QTextFrameFormat::setHeight(qreal height)
2708     \overload
2709
2710     Sets the frame's \a height.
2711 */
2712
2713 /*!
2714     \fn qreal QTextFrameFormat::height() const
2715
2716     Returns the height of the frame's border rectangle.
2717 */
2718
2719 /*!
2720     \class QTextTableFormat
2721     \reentrant
2722
2723     \brief The QTextTableFormat class provides formatting information for
2724     tables in a QTextDocument.
2725
2726     \ingroup richtext-processing
2727
2728     A table is a group of cells ordered into rows and columns. Each table
2729     contains at least one row and one column. Each cell contains a block.
2730     Tables in rich text documents are formatted using the properties
2731     defined in this class.
2732
2733     Tables are horizontally justified within their parent frame according to the
2734     table's alignment. This can be read with the alignment() function and set
2735     with setAlignment().
2736
2737     Cells within the table are separated by cell spacing. The number of pixels
2738     between cells is set with setCellSpacing() and read with cellSpacing().
2739     The contents of each cell is surrounded by cell padding. The number of pixels
2740     between each cell edge and its contents is set with setCellPadding() and read
2741     with cellPadding().
2742
2743     \image qtexttableformat-cell.png
2744
2745     The table's background color can be read with the background() function,
2746     and can be specified with setBackground(). The background color of each
2747     cell can be set independently, and will control the color of the cell within
2748     the padded area.
2749
2750     The table format also provides a way to constrain the widths of the columns
2751     in the table. Columns can be assigned a fixed width, a variable width, or
2752     a percentage of the available width (see QTextLength). The columns() function
2753     returns the number of columns with constraints, and the
2754     columnWidthConstraints() function returns the constraints defined for the
2755     table. These quantities can also be set by calling setColumnWidthConstraints()
2756     with a vector containing new constraints. If no constraints are
2757     required, clearColumnWidthConstraints() can be used to remove them.
2758
2759     \sa QTextTable QTextTableCell QTextLength
2760 */
2761
2762 /*!
2763     \fn QTextTableFormat::QTextTableFormat()
2764
2765     Constructs a new table format object.
2766 */
2767 QTextTableFormat::QTextTableFormat()
2768  : QTextFrameFormat()
2769 {
2770     setObjectType(TableObject);
2771     setCellSpacing(2);
2772     setBorder(1);
2773 }
2774
2775 /*!
2776     \internal
2777     \fn QTextTableFormat::QTextTableFormat(const QTextFormat &other)
2778
2779     Creates a new table format with the same attributes as the \a given
2780     text format.
2781 */
2782 QTextTableFormat::QTextTableFormat(const QTextFormat &fmt)
2783  : QTextFrameFormat(fmt)
2784 {
2785 }
2786
2787 /*!
2788     \fn bool QTextTableFormat::isValid() const
2789
2790     Returns true if this table format is valid; otherwise
2791     returns false.
2792 */
2793
2794
2795 /*!
2796     \fn int QTextTableFormat::columns() const
2797
2798     Returns the number of columns specified by the table format.
2799 */
2800
2801
2802 /*!
2803     \internal
2804     \fn void QTextTableFormat::setColumns(int columns)
2805
2806     Sets the number of \a columns required by the table format.
2807
2808     \sa columns()
2809 */
2810
2811 /*!
2812     \fn void QTextTableFormat::clearColumnWidthConstraints()
2813
2814     Clears the column width constraints for the table.
2815
2816     \sa columnWidthConstraints() setColumnWidthConstraints()
2817 */
2818
2819 /*!
2820     \fn void QTextTableFormat::setColumnWidthConstraints(const QVector<QTextLength> &constraints)
2821
2822     Sets the column width \a constraints for the table.
2823
2824     \sa columnWidthConstraints() clearColumnWidthConstraints()
2825 */
2826
2827 /*!
2828     \fn QVector<QTextLength> QTextTableFormat::columnWidthConstraints() const
2829
2830     Returns a list of constraints used by this table format to control the
2831     appearance of columns in a table.
2832
2833     \sa setColumnWidthConstraints()
2834 */
2835
2836 /*!
2837     \fn qreal QTextTableFormat::cellSpacing() const
2838
2839     Returns the table's cell spacing. This describes the distance between
2840     adjacent cells.
2841 */
2842
2843 /*!
2844     \fn void QTextTableFormat::setCellSpacing(qreal spacing)
2845
2846     Sets the cell \a spacing for the table. This determines the distance
2847     between adjacent cells.
2848 */
2849
2850 /*!
2851     \fn qreal QTextTableFormat::cellPadding() const
2852
2853     Returns the table's cell padding. This describes the distance between
2854     the border of a cell and its contents.
2855 */
2856
2857 /*!
2858     \fn void QTextTableFormat::setCellPadding(qreal padding)
2859
2860     Sets the cell \a padding for the table. This determines the distance
2861     between the border of a cell and its contents.
2862 */
2863
2864 /*!
2865     \fn void QTextTableFormat::setAlignment(Qt::Alignment alignment)
2866
2867     Sets the table's \a alignment.
2868
2869     \sa alignment()
2870 */
2871
2872 /*!
2873     \fn Qt::Alignment QTextTableFormat::alignment() const
2874
2875     Returns the table's alignment.
2876
2877     \sa setAlignment()
2878 */
2879
2880 /*!
2881     \fn void QTextTableFormat::setHeaderRowCount(int count)
2882     \since 4.2
2883
2884     Declares the first \a count rows of the table as table header.
2885     The table header rows get repeated when a table is broken
2886     across a page boundary.
2887 */
2888
2889 /*!
2890     \fn int QTextTableFormat::headerRowCount() const
2891     \since 4.2
2892
2893     Returns the number of rows in the table that define the header.
2894
2895     \sa setHeaderRowCount()
2896 */
2897
2898 /*!
2899     \fn void QTextFormat::setBackground(const QBrush &brush)
2900
2901     Sets the brush use to paint the document's background to the
2902     \a brush specified.
2903
2904     \sa background() clearBackground() setForeground()
2905 */
2906
2907 /*!
2908     \fn QColor QTextFormat::background() const
2909
2910     Returns the brush used to paint the document's background.
2911
2912     \sa setBackground() clearBackground() foreground()
2913 */
2914
2915 /*!
2916     \fn void QTextFormat::clearBackground()
2917
2918     Clears the brush used to paint the document's background. The default
2919     brush will be used.
2920
2921     \sa background() setBackground() clearForeground()
2922 */
2923
2924
2925 /*!
2926     \class QTextImageFormat
2927     \reentrant
2928
2929     \brief The QTextImageFormat class provides formatting information for
2930     images in a QTextDocument.
2931
2932     \ingroup richtext-processing
2933
2934     Inline images are represented by an object replacement character
2935     (0xFFFC in Unicode) which has an associated QTextImageFormat. The
2936     image format specifies a name with setName() that is used to
2937     locate the image. The size of the rectangle that the image will
2938     occupy is specified using setWidth() and setHeight().
2939
2940     Images can be supplied in any format for which Qt has an image
2941     reader, so SVG drawings can be included alongside PNG, TIFF and
2942     other bitmap formats.
2943
2944     \sa QImage, QImageReader
2945 */
2946
2947 /*!
2948     \fn QTextImageFormat::QTextImageFormat()
2949
2950     Creates a new image format object.
2951 */
2952 QTextImageFormat::QTextImageFormat() : QTextCharFormat() { setObjectType(ImageObject); }
2953
2954 /*!
2955     \internal
2956     \fn QTextImageFormat::QTextImageFormat(const QTextFormat &other)
2957
2958     Creates a new image format with the same attributes as the \a given
2959     text format.
2960 */
2961 QTextImageFormat::QTextImageFormat(const QTextFormat &fmt)
2962  : QTextCharFormat(fmt)
2963 {
2964 }
2965
2966 /*!
2967     \fn bool QTextImageFormat::isValid() const
2968
2969     Returns true if this image format is valid; otherwise returns false.
2970 */
2971
2972
2973 /*!
2974     \fn void QTextImageFormat::setName(const QString &name)
2975
2976     Sets the \a name of the image. The \a name is used to locate the image
2977     in the application's resources.
2978
2979     \sa name()
2980 */
2981
2982
2983 /*!
2984     \fn QString QTextImageFormat::name() const
2985
2986     Returns the name of the image. The name refers to an entry in the
2987     application's resources file.
2988
2989     \sa setName()
2990 */
2991
2992 /*!
2993     \fn void QTextImageFormat::setWidth(qreal width)
2994
2995     Sets the \a width of the rectangle occupied by the image.
2996
2997     \sa width() setHeight()
2998 */
2999
3000
3001 // ### Qt5 qreal replace with a QTextLength
3002 /*!
3003     \fn qreal QTextImageFormat::width() const
3004
3005     Returns the width of the rectangle occupied by the image.
3006
3007     \sa height() setWidth()
3008 */
3009
3010
3011 /*!
3012     \fn void QTextImageFormat::setHeight(qreal height)
3013
3014     Sets the \a height of the rectangle occupied by the image.
3015
3016     \sa height() setWidth()
3017 */
3018
3019
3020 // ### Qt5 qreal replace with a QTextLength
3021 /*!
3022     \fn qreal QTextImageFormat::height() const
3023
3024     Returns the height of the rectangle occupied by the image.
3025
3026     \sa width() setHeight()
3027 */
3028
3029 /*!
3030     \fn void QTextCharFormat::setFontCapitalization(QFont::Capitalization capitalization)
3031     \since 4.4
3032
3033     Sets the capitalization of the text that apppears in this font to \a capitalization.
3034
3035     A font's capitalization makes the text appear in the selected capitalization mode.
3036
3037     \sa fontCapitalization()
3038 */
3039
3040 /*!
3041     \fn Capitalization QTextCharFormat::fontCapitalization() const
3042     \since 4.4
3043
3044     Returns the current capitalization type of the font.
3045 */
3046
3047 /*!
3048     \fn void QTextCharFormat::setFontLetterSpacing(qreal spacing)
3049     \since 4.4
3050
3051     Sets the letter spacing of this format to the given \a spacing, in percent.
3052     A value of 100 indicates default spacing; a value of 200 doubles the amount
3053     of space a letter takes.
3054
3055     \sa fontLetterSpacing()
3056 */
3057
3058 /*!
3059     \fn qreal QTextCharFormat::fontLetterSpacing() const
3060     \since 4.4
3061
3062     Returns the current letter spacing percentage.
3063 */
3064
3065 /*!
3066     \fn void QTextCharFormat::setFontWordSpacing(qreal spacing)
3067     \since 4.4
3068
3069     Sets the word spacing of this format to the given \a spacing, in pixels.
3070
3071     \sa fontWordSpacing()
3072 */
3073
3074 /*!
3075     \fn qreal QTextCharFormat::fontWordSpacing() const
3076     \since 4.4
3077
3078     Returns the current word spacing value.
3079 */
3080
3081 /*!
3082    \fn qreal QTextTableCellFormat::topPadding() const
3083     \since 4.4
3084
3085    Gets the top padding of the table cell.
3086
3087    \sa setTopPadding(), leftPadding(), rightPadding(), bottomPadding()
3088 */
3089
3090 /*!
3091    \fn qreal QTextTableCellFormat::bottomPadding() const
3092     \since 4.4
3093
3094    Gets the bottom padding of the table cell.
3095
3096    \sa setBottomPadding(), leftPadding(), rightPadding(), topPadding()
3097 */
3098
3099 /*!
3100    \fn qreal QTextTableCellFormat::leftPadding() const
3101     \since 4.4
3102
3103    Gets the left padding of the table cell.
3104
3105    \sa setLeftPadding(), rightPadding(), topPadding(), bottomPadding()
3106 */
3107
3108 /*!
3109    \fn qreal QTextTableCellFormat::rightPadding() const
3110     \since 4.4
3111
3112    Gets the right padding of the table cell.
3113
3114    \sa setRightPadding(), leftPadding(), topPadding(), bottomPadding()
3115 */
3116
3117 /*!
3118    \fn void QTextTableCellFormat::setTopPadding(qreal padding)
3119     \since 4.4
3120
3121    Sets the top \a padding of the table cell.
3122
3123    \sa topPadding(), setLeftPadding(), setRightPadding(), setBottomPadding()
3124 */
3125
3126 /*!
3127    \fn void QTextTableCellFormat::setBottomPadding(qreal padding)
3128     \since 4.4
3129
3130    Sets the bottom \a padding of the table cell.
3131
3132    \sa bottomPadding(), setLeftPadding(), setRightPadding(), setTopPadding()
3133 */
3134
3135 /*!
3136    \fn void QTextTableCellFormat::setLeftPadding(qreal padding)
3137     \since 4.4
3138
3139    Sets the left \a padding of the table cell.
3140
3141    \sa leftPadding(), setRightPadding(), setTopPadding(), setBottomPadding()
3142 */
3143
3144 /*!
3145    \fn void QTextTableCellFormat::setRightPadding(qreal padding)
3146     \since 4.4
3147
3148    Sets the right \a padding of the table cell.
3149
3150    \sa rightPadding(), setLeftPadding(), setTopPadding(), setBottomPadding()
3151 */
3152
3153 /*!
3154    \fn void QTextTableCellFormat::setPadding(qreal padding)
3155     \since 4.4
3156
3157    Sets the left, right, top, and bottom \a padding of the table cell.
3158
3159    \sa setLeftPadding(), setRightPadding(), setTopPadding(), setBottomPadding()
3160 */
3161
3162 /*!
3163     \fn bool QTextTableCellFormat::isValid() const
3164     \since 4.4
3165
3166     Returns true if this table cell format is valid; otherwise returns false.
3167 */
3168
3169 /*!
3170     \fn QTextTableCellFormat::QTextTableCellFormat()
3171     \since 4.4
3172
3173     Constructs a new table cell format object.
3174 */
3175 QTextTableCellFormat::QTextTableCellFormat()
3176     : QTextCharFormat()
3177 {
3178     setObjectType(TableCellObject);
3179 }
3180
3181 /*!
3182     \internal
3183     \fn QTextTableCellFormat::QTextTableCellFormat(const QTextFormat &other)
3184
3185     Creates a new table cell format with the same attributes as the \a given
3186     text format.
3187 */
3188 QTextTableCellFormat::QTextTableCellFormat(const QTextFormat &fmt)
3189     : QTextCharFormat(fmt)
3190 {
3191 }
3192
3193 /*!
3194     \class QTextTableCellFormat
3195     \reentrant
3196     \since 4.4
3197
3198     \brief The QTextTableCellFormat class provides formatting information for
3199     table cells in a QTextDocument.
3200
3201     \ingroup richtext-processing
3202
3203     The table cell format of a table cell in a document specifies the visual
3204     properties of the table cell.
3205
3206     The padding properties of a table cell are controlled by setLeftPadding(),
3207     setRightPadding(), setTopPadding(), and setBottomPadding(). All the paddings
3208     can be set at once using setPadding().
3209
3210     \sa QTextFormat QTextBlockFormat QTextTableFormat QTextCharFormat
3211 */
3212
3213 // ------------------------------------------------------
3214
3215
3216 QTextFormatCollection::QTextFormatCollection(const QTextFormatCollection &rhs)
3217 {
3218     formats = rhs.formats;
3219     objFormats = rhs.objFormats;
3220 }
3221
3222 QTextFormatCollection &QTextFormatCollection::operator=(const QTextFormatCollection &rhs)
3223 {
3224     formats = rhs.formats;
3225     objFormats = rhs.objFormats;
3226     return *this;
3227 }
3228
3229 QTextFormatCollection::~QTextFormatCollection()
3230 {
3231 }
3232
3233 int QTextFormatCollection::indexForFormat(const QTextFormat &format)
3234 {
3235     uint hash = getHash(format.d, format.format_type);
3236     QMultiHash<uint, int>::const_iterator i = hashes.find(hash);
3237     while (i != hashes.end() && i.key() == hash) {
3238         if (formats.value(i.value()) == format) {
3239             return i.value();
3240         }
3241         ++i;
3242     }
3243
3244     int idx = formats.size();
3245     formats.append(format);
3246
3247     QT_TRY{
3248         QTextFormat &f = formats.last();
3249         if (!f.d)
3250             f.d = new QTextFormatPrivate;
3251         f.d->resolveFont(defaultFnt);
3252
3253         if (!hashes.contains(hash, idx))
3254             hashes.insert(hash, idx);
3255
3256     } QT_CATCH(...) {
3257         formats.pop_back();
3258         QT_RETHROW;
3259     }
3260     return idx;
3261 }
3262
3263 bool QTextFormatCollection::hasFormatCached(const QTextFormat &format) const
3264 {
3265     uint hash = getHash(format.d, format.format_type);
3266     QMultiHash<uint, int>::const_iterator i = hashes.find(hash);
3267     while (i != hashes.end() && i.key() == hash) {
3268         if (formats.value(i.value()) == format) {
3269             return true;
3270         }
3271         ++i;
3272     }
3273     return false;
3274 }
3275
3276 QTextFormat QTextFormatCollection::objectFormat(int objectIndex) const
3277 {
3278     if (objectIndex == -1)
3279         return QTextFormat();
3280     return format(objFormats.at(objectIndex));
3281 }
3282
3283 void QTextFormatCollection::setObjectFormat(int objectIndex, const QTextFormat &f)
3284 {
3285     const int formatIndex = indexForFormat(f);
3286     objFormats[objectIndex] = formatIndex;
3287 }
3288
3289 int QTextFormatCollection::objectFormatIndex(int objectIndex) const
3290 {
3291     if (objectIndex == -1)
3292         return -1;
3293     return objFormats.at(objectIndex);
3294 }
3295
3296 void QTextFormatCollection::setObjectFormatIndex(int objectIndex, int formatIndex)
3297 {
3298     objFormats[objectIndex] = formatIndex;
3299 }
3300
3301 int QTextFormatCollection::createObjectIndex(const QTextFormat &f)
3302 {
3303     const int objectIndex = objFormats.size();
3304     objFormats.append(indexForFormat(f));
3305     return objectIndex;
3306 }
3307
3308 QTextFormat QTextFormatCollection::format(int idx) const
3309 {
3310     if (idx < 0 || idx >= formats.count())
3311         return QTextFormat();
3312
3313     return formats.at(idx);
3314 }
3315
3316 void QTextFormatCollection::setDefaultFont(const QFont &f)
3317 {
3318     defaultFnt = f;
3319     for (int i = 0; i < formats.count(); ++i)
3320         if (formats[i].d)
3321             formats[i].d->resolveFont(defaultFnt);
3322 }
3323
3324 QT_END_NAMESPACE