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