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