1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtGui module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qtextoption.h"
43 #include "qguiapplication.h"
48 struct QTextOptionPrivate
50 QList<QTextOption::Tab> tabStops;
54 Constructs a text option with default properties for text.
55 The text alignment property is set to Qt::AlignLeft. The
56 word wrap property is set to QTextOption::WordWrap. The
57 using of design metrics flag is set to false.
59 QTextOption::QTextOption()
60 : align(Qt::AlignLeft),
61 wordWrap(QTextOption::WordWrap),
68 direction = Qt::LayoutDirectionAuto;
72 Constructs a text option with the given \a alignment for text.
73 The word wrap property is set to QTextOption::WordWrap. The using
74 of design metrics flag is set to false.
76 QTextOption::QTextOption(Qt::Alignment alignment)
78 wordWrap(QTextOption::WordWrap),
85 direction = QGuiApplication::layoutDirection();
89 Destroys the text option.
91 QTextOption::~QTextOption()
97 \fn QTextOption::QTextOption(const QTextOption &other)
99 Construct a copy of the \a other text option.
101 QTextOption::QTextOption(const QTextOption &o)
103 wordWrap(o.wordWrap),
105 direction(o.direction),
112 d = new QTextOptionPrivate(*o.d);
116 \fn QTextOption &QTextOption::operator=(const QTextOption &other)
118 Returns true if the text option is the same as the \a other text option;
119 otherwise returns false.
121 QTextOption &QTextOption::operator=(const QTextOption &o)
126 QTextOptionPrivate* dNew = 0;
128 dNew = new QTextOptionPrivate(*o.d);
133 wordWrap = o.wordWrap;
135 direction = o.direction;
143 Sets the tab positions for the text layout to those specified by
146 \sa tabArray(), setTabStop(), setTabs()
148 void QTextOption::setTabArray(const QList<qreal> &tabStops)
151 d = new QTextOptionPrivate;
152 QList<QTextOption::Tab> tabs;
153 QTextOption::Tab tab;
154 foreach (qreal pos, tabStops) {
163 Sets the tab positions for the text layout to those specified by
168 void QTextOption::setTabs(const QList<QTextOption::Tab> &tabStops)
171 d = new QTextOptionPrivate;
172 d->tabStops = tabStops;
176 Returns a list of tab positions defined for the text layout.
178 \sa setTabArray(), tabStop()
180 QList<qreal> QTextOption::tabArray() const
183 return QList<qreal>();
186 QList<QTextOption::Tab>::ConstIterator iter = d->tabStops.constBegin();
187 while(iter != d->tabStops.constEnd()) {
188 answer.append( (*iter).position);
195 QList<QTextOption::Tab> QTextOption::tabs() const
198 return QList<QTextOption::Tab>();
206 \brief The QTextOption class provides a description of general rich text
209 \ingroup richtext-processing
211 QTextOption is used to encapsulate common rich text properties in a single
212 object. It contains information about text alignment, layout direction,
213 word wrapping, and other standard properties associated with text rendering
216 \sa QTextEdit, QTextDocument, QTextCursor
220 \enum QTextOption::WrapMode
222 This enum describes how text is wrapped in a document.
224 \value NoWrap Text is not wrapped at all.
225 \value WordWrap Text is wrapped at word boundaries.
226 \value ManualWrap Same as QTextOption::NoWrap
227 \value WrapAnywhere Text can be wrapped at any point on a line, even if
228 it occurs in the middle of a word.
229 \value WrapAtWordBoundaryOrAnywhere If possible, wrapping occurs at a word
230 boundary; otherwise it will occur at the appropriate
231 point on the line, even in the middle of a word.
235 \fn void QTextOption::setUseDesignMetrics(bool enable)
237 If \a enable is true then the layout will use design metrics;
238 otherwise it will use the metrics of the paint device (which is
239 the default behavior).
241 \sa useDesignMetrics()
245 \fn bool QTextOption::useDesignMetrics() const
247 Returns true if the layout uses design rather than device metrics;
248 otherwise returns false.
250 \sa setUseDesignMetrics()
254 \fn Qt::Alignment QTextOption::alignment() const
256 Returns the text alignment defined by the option.
262 \fn void QTextOption::setAlignment(Qt::Alignment alignment);
264 Sets the option's text alignment to the specified \a alignment.
270 \fn Qt::LayoutDirection QTextOption::textDirection() const
272 Returns the direction of the text layout defined by the option.
274 \sa setTextDirection()
278 \fn void QTextOption::setTextDirection(Qt::LayoutDirection direction)
280 Sets the direction of the text layout defined by the option to the
287 \fn WrapMode QTextOption::wrapMode() const
289 Returns the text wrap mode defined by the option.
295 \fn void QTextOption::setWrapMode(WrapMode mode)
297 Sets the option's text wrap mode to the given \a mode.
301 \enum QTextOption::Flag
303 \value IncludeTrailingSpaces When this option is set, QTextLine::naturalTextWidth() and naturalTextRect() will
304 return a value that includes the width of trailing spaces in the text; otherwise
305 this width is excluded.
306 \value ShowTabsAndSpaces Visualize spaces with little dots, and tabs with little arrows.
307 \value ShowLineAndParagraphSeparators Visualize line and paragraph separators with appropriate symbol characters.
308 \value AddSpaceForLineAndParagraphSeparators While determining the line-break positions take into account the
309 space added for drawing a separator character.
310 \value SuppressColors Suppress all color changes in the character formats (except the main selection).
314 \fn Flags QTextOption::flags() const
316 Returns the flags associated with the option.
322 \fn void QTextOption::setFlags(Flags flags)
324 Sets the flags associated with the option to the given \a flags.
330 \fn qreal QTextOption::tabStop() const
332 Returns the distance in device units between tab stops.
333 Convenient function for the above method
335 \sa setTabStop(), tabArray(), setTabs(), tabs()
339 \fn void QTextOption::setTabStop(qreal tabStop)
341 Sets the default distance in device units between tab stops to the value specified
344 \sa tabStop(), setTabArray(), setTabs(), tabs()
348 \enum QTextOption::TabType
351 This enum holds the different types of tabulator
353 \value LeftTab A left-tab
354 \value RightTab A right-tab
355 \value CenterTab A centered-tab
356 \value DelimiterTab A tab stopping at a certain delimiter-character
360 \class QTextOption::Tab
362 Each tab definition is represented by this struct.
366 \variable Tab::position
367 Distance from the start of the paragraph.
368 The position of a tab is from the start of the paragraph which implies that when
369 the alignment of the paragraph is set to centered, the tab is interpreted to be
370 moved the same distance as the left ege of the paragraph does.
371 In case the paragraph is set to have a layoutDirection() RightToLeft the position
372 is interpreted to be from the right side of the paragraph with higher numbers moving
378 Determine which type is used.
379 In a paragraph that has layoutDirection() RightToLeft the type LeftTab will
380 be interpreted to be a RightTab and vice versa.
384 \variable Tab::delimiter
385 If type is DelimitorTab; tab until this char is found in the text.
390 Creates a default left tab with position 80.
394 \fn Tab::Tab(qreal pos, TabType tabType, QChar delim = QChar())
396 Creates a tab with the given position, tab type, and delimiter
397 (\a pos, \a tabType, \a delim).
399 \note \a delim is only used when \a tabType is DelimiterTab.
405 \fn bool Tab::operator==(const Tab &other) const
407 Returns true if tab \a other is equal to this tab;
408 otherwise returns false.
412 \fn bool Tab::operator!=(const Tab &other) const
414 Returns true if tab \a other is not equal to this tab;
415 otherwise returns false.
419 \fn void setTabs(QList<Tab> tabStops)
420 Set the Tab properties to \a tabStops.
422 \sa tabStop(), tabs()
427 \fn QList<QTextOption::Tab> QTextOption::tabs() const
428 Returns a list of tab positions defined for the text layout.
430 \sa tabStop(), setTabs(), setTabStop()