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 "qtextoption.h"
41#include "qguiapplication.h"
42#include "qlist.h"
43
44QT_BEGIN_NAMESPACE
45
46struct QTextOptionPrivate
47{
48 QList<QTextOption::Tab> tabStops;
49};
50
51/*!
52 Constructs a text option with default properties for text.
53 The text alignment property is set to Qt::AlignLeft. The
54 word wrap property is set to QTextOption::WordWrap. The
55 using of design metrics flag is set to false.
56*/
57QTextOption::QTextOption()
58 : QTextOption(Qt::AlignLeft)
59{
60 direction = Qt::LayoutDirectionAuto;
61}
62
63/*!
64 Constructs a text option with the given \a alignment for text.
65 The word wrap property is set to QTextOption::WordWrap. The using
66 of design metrics flag is set to false.
67*/
68QTextOption::QTextOption(Qt::Alignment alignment)
69 : align(alignment),
70 wordWrap(QTextOption::WordWrap),
71 design(false),
72 unused(0),
73 f(0),
74 tab(-1),
75 d(nullptr)
76{
77 direction = QGuiApplication::layoutDirection();
78}
79
80/*!
81 Destroys the text option.
82*/
83QTextOption::~QTextOption()
84{
85 delete d;
86}
87
88/*!
89 \fn QTextOption::QTextOption(const QTextOption &other)
90
91 Construct a copy of the \a other text option.
92*/
93QTextOption::QTextOption(const QTextOption &o)
94 : align(o.align),
95 wordWrap(o.wordWrap),
96 design(o.design),
97 direction(o.direction),
98 unused(o.unused),
99 f(o.f),
100 tab(o.tab),
101 d(nullptr)
102{
103 if (o.d)
104 d = new QTextOptionPrivate(*o.d);
105}
106
107/*!
108 \fn QTextOption &QTextOption::operator=(const QTextOption &other)
109
110 Returns \c true if the text option is the same as the \a other text option;
111 otherwise returns \c false.
112*/
113QTextOption &QTextOption::operator=(const QTextOption &o)
114{
115 if (this == &o)
116 return *this;
117
118 QTextOptionPrivate* dNew = nullptr;
119 if (o.d)
120 dNew = new QTextOptionPrivate(*o.d);
121 delete d;
122 d = dNew;
123
124 align = o.align;
125 wordWrap = o.wordWrap;
126 design = o.design;
127 direction = o.direction;
128 unused = o.unused;
129 f = o.f;
130 tab = o.tab;
131 return *this;
132}
133
134/*!
135 Sets the tab positions for the text layout to those specified by
136 \a tabStops.
137
138 \sa tabArray(), setTabStopDistance(), setTabs()
139*/
140void QTextOption::setTabArray(const QList<qreal> &tabStops)
141{
142 if (!d)
143 d = new QTextOptionPrivate;
144 QList<QTextOption::Tab> tabs;
145 QTextOption::Tab tab;
146 tabs.reserve(tabStops.count());
147 for (qreal pos : tabStops) {
148 tab.position = pos;
149 tabs.append(tab);
150 }
151 d->tabStops = tabs;
152}
153
154/*!
155 \since 4.4
156 Sets the tab positions for the text layout to those specified by
157 \a tabStops.
158
159 \sa tabStopDistance()
160*/
161void QTextOption::setTabs(const QList<QTextOption::Tab> &tabStops)
162{
163 if (!d)
164 d = new QTextOptionPrivate;
165 d->tabStops = tabStops;
166}
167
168/*!
169 Returns a list of tab positions defined for the text layout.
170
171 \sa setTabArray(), tabStopDistance()
172*/
173QList<qreal> QTextOption::tabArray() const
174{
175 QList<qreal> answer;
176 if (!d)
177 return answer;
178
179 answer.reserve(d->tabStops.count());
180 QList<QTextOption::Tab>::ConstIterator iter = d->tabStops.constBegin();
181 while(iter != d->tabStops.constEnd()) {
182 answer.append( (*iter).position);
183 ++iter;
184 }
185 return answer;
186}
187
188
189QList<QTextOption::Tab> QTextOption::tabs() const
190{
191 if (!d)
192 return QList<QTextOption::Tab>();
193 return d->tabStops;
194}
195
196/*!
197 \class QTextOption
198 \reentrant
199
200 \brief The QTextOption class provides a description of general rich text
201 properties.
202 \inmodule QtGui
203
204 \ingroup richtext-processing
205
206 QTextOption is used to encapsulate common rich text properties in a single
207 object. It contains information about text alignment, layout direction,
208 word wrapping, and other standard properties associated with text rendering
209 and layout.
210
211 \sa QTextEdit, QTextDocument, QTextCursor
212*/
213
214/*!
215 \enum QTextOption::WrapMode
216
217 This enum describes how text is wrapped in a document.
218
219 \value NoWrap Text is not wrapped at all.
220 \value WordWrap Text is wrapped at word boundaries.
221 \value ManualWrap Same as QTextOption::NoWrap
222 \value WrapAnywhere Text can be wrapped at any point on a line, even if
223 it occurs in the middle of a word.
224 \value WrapAtWordBoundaryOrAnywhere If possible, wrapping occurs at a word
225 boundary; otherwise it will occur at the appropriate
226 point on the line, even in the middle of a word.
227*/
228
229/*!
230 \fn void QTextOption::setUseDesignMetrics(bool enable)
231
232 If \a enable is true then the layout will use design metrics;
233 otherwise it will use the metrics of the paint device (which is
234 the default behavior).
235
236 \sa useDesignMetrics()
237*/
238
239/*!
240 \fn bool QTextOption::useDesignMetrics() const
241
242 Returns \c true if the layout uses design rather than device metrics;
243 otherwise returns \c false.
244
245 \sa setUseDesignMetrics()
246*/
247
248/*!
249 \fn Qt::Alignment QTextOption::alignment() const
250
251 Returns the text alignment defined by the option.
252
253 \sa setAlignment()
254*/
255
256/*!
257 \fn void QTextOption::setAlignment(Qt::Alignment alignment);
258
259 Sets the option's text alignment to the specified \a alignment.
260
261 \sa alignment()
262*/
263
264/*!
265 \fn Qt::LayoutDirection QTextOption::textDirection() const
266
267 Returns the direction of the text layout defined by the option.
268
269 \sa setTextDirection()
270*/
271
272/*!
273 \fn void QTextOption::setTextDirection(Qt::LayoutDirection direction)
274
275 Sets the direction of the text layout defined by the option to the
276 given \a direction.
277
278 \sa textDirection()
279*/
280
281/*!
282 \fn WrapMode QTextOption::wrapMode() const
283
284 Returns the text wrap mode defined by the option.
285
286 \sa setWrapMode()
287*/
288
289/*!
290 \fn void QTextOption::setWrapMode(WrapMode mode)
291
292 Sets the option's text wrap mode to the given \a mode.
293*/
294
295/*!
296 \enum QTextOption::Flag
297
298 \value IncludeTrailingSpaces When this option is set, QTextLine::naturalTextWidth() and naturalTextRect() will
299 return a value that includes the width of trailing spaces in the text; otherwise
300 this width is excluded.
301 \value ShowTabsAndSpaces Visualize spaces with little dots, and tabs with little arrows. Non-breaking spaces are
302 shown differently to breaking spaces.
303 \value ShowLineAndParagraphSeparators Visualize line and paragraph separators with appropriate symbol characters.
304 \value ShowDocumentTerminator Visualize the end of the document with a section sign. This enum value was added
305 in Qt 5.7.
306 \value AddSpaceForLineAndParagraphSeparators While determining the line-break positions take into account the
307 space added for drawing a separator character.
308 \value SuppressColors Suppress all color changes in the character formats (except the main selection).
309*/
310
311/*!
312 \fn Flags QTextOption::flags() const
313
314 Returns the flags associated with the option.
315
316 \sa setFlags()
317*/
318
319/*!
320 \fn void QTextOption::setFlags(Flags flags)
321
322 Sets the flags associated with the option to the given \a flags.
323
324 \sa flags()
325*/
326
327/*!
328 \fn qreal QTextOption::tabStopDistance() const
329 \since 5.10
330
331 Returns the distance in device units between tab stops.
332
333 \sa setTabStopDistance(), tabArray(), setTabs(), tabs()
334*/
335
336/*!
337 \fn void QTextOption::setTabStopDistance(qreal tabStopDistance)
338 \since 5.10
339
340 Sets the default distance in device units between tab stops to the value specified
341 by \a tabStopDistance.
342
343 \sa tabStopDistance(), setTabArray(), setTabs(), tabs()
344*/
345
346/*!
347 \enum QTextOption::TabType
348 \since 4.4
349
350 This enum holds the different types of tabulator
351
352 \value LeftTab A left-tab
353 \value RightTab A right-tab
354 \value CenterTab A centered-tab
355 \value DelimiterTab A tab stopping at a certain delimiter-character
356*/
357
358/*!
359 \class QTextOption::Tab
360 \since 4.4
361 \inmodule QtGui
362 Each tab definition is represented by this struct.
363*/
364
365/*!
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
373 the tab to the left.
374*/
375
376/*!
377 \variable QTextOption::Tab::type
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.
381*/
382
383/*!
384 \variable QTextOption::Tab::delimiter
385 If type is DelimitorTab; tab until this char is found in the text.
386*/
387
388/*!
389 \fn QTextOption::Tab::Tab()
390 Creates a default left tab with position 80.
391*/
392
393/*!
394 \fn QTextOption::Tab::Tab(qreal pos, TabType tabType, QChar delim = QChar())
395
396 Creates a tab with the given position, tab type, and delimiter
397 (\a pos, \a tabType, \a delim).
398
399 \note \a delim is only used when \a tabType is DelimiterTab.
400
401 \since 4.7
402*/
403
404/*!
405 \fn bool QTextOption::Tab::operator==(const QTextOption::Tab &other) const
406
407 Returns \c true if tab \a other is equal to this tab;
408 otherwise returns \c false.
409*/
410
411/*!
412 \fn bool QTextOption::Tab::operator!=(const QTextOption::Tab &other) const
413
414 Returns \c true if tab \a other is not equal to this tab;
415 otherwise returns \c false.
416*/
417
418/*!
419 \since 4.4
420 \fn QList<QTextOption::Tab> QTextOption::tabs() const
421 Returns a list of tab positions defined for the text layout.
422
423 \sa tabStopDistance(), setTabs(), setTabStopDistance()
424*/
425
426
427QT_END_NAMESPACE
428