src/gui/text/qtextformat.cpp

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