src/gui/text/qtextoption.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the QtGui module of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** GNU Lesser General Public License Usage
  11 ** This file may be used under the terms of the GNU Lesser General Public
  12 ** License version 2.1 as published by the Free Software Foundation and
  13 ** appearing in the file LICENSE.LGPL included in the packaging of this
  14 ** file. Please review the following information to ensure the GNU Lesser
  15 ** General Public License version 2.1 requirements will be met:
  16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  17 **
  18 ** In addition, as a special exception, Nokia gives you certain additional
  19 ** rights. These rights are described in the Nokia Qt LGPL Exception
  20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  21 **
  22 ** GNU General Public License Usage
  23 ** Alternatively, this file may be used under the terms of the GNU General
  24 ** Public License version 3.0 as published by the Free Software Foundation
  25 ** and appearing in the file LICENSE.GPL included in the packaging of this
  26 ** file. Please review the following information to ensure the GNU General
  27 ** Public License version 3.0 requirements will be met:
  28 ** http://www.gnu.org/copyleft/gpl.html.
  29 **
  30 ** Other Usage
  31 ** Alternatively, this file may be used in accordance with the terms and
  32 ** conditions contained in a signed written agreement between you and Nokia.
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qtextoption.h"
  43 #include "qguiapplication.h"
  44 #include "qlist.h"
  45
  46 QT_BEGIN_NAMESPACE
  47
  48 struct QTextOptionPrivate
  49 {
  50     QList<QTextOption::Tab> tabStops;
  51 };
  52
  53 /*!
  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.
  58 */
  59 QTextOption::QTextOption()
  60     : align(Qt::AlignLeft),
  61       wordWrap(QTextOption::WordWrap),
  62       design(false),
  63       unused(0),
  64       f(0),
  65       tab(-1),
  66       d(0)
  67 {
  68     direction = Qt::LayoutDirectionAuto;
  69 }
  70
  71 /*!
  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.
  75 */
  76 QTextOption::QTextOption(Qt::Alignment alignment)
  77     : align(alignment),
  78       wordWrap(QTextOption::WordWrap),
  79       design(false),
  80       unused(0),
  81       f(0),
  82       tab(-1),
  83       d(0)
  84 {
  85     direction = QGuiApplication::layoutDirection();
  86 }
  87
  88 /*!
  89     Destroys the text option.
  90 */
  91 QTextOption::~QTextOption()
  92 {
  93     delete d;
  94 }
  95
  96 /*!
  97     \fn QTextOption::QTextOption(const QTextOption &other)
  98
  99     Construct a copy of the \a other text option.
 100 */
 101 QTextOption::QTextOption(const QTextOption &o)
 102     : align(o.align),
 103       wordWrap(o.wordWrap),
 104       design(o.design),
 105       direction(o.direction),
 106       unused(o.unused),
 107       f(o.f),
 108       tab(o.tab),
 109       d(0)
 110 {
 111     if (o.d)
 112         d = new QTextOptionPrivate(*o.d);
 113 }
 114
 115 /*!
 116     \fn QTextOption &QTextOption::operator=(const QTextOption &other)
 117
 118     Returns true if the text option is the same as the \a other text option;
 119     otherwise returns false.
 120 */
 121 QTextOption &QTextOption::operator=(const QTextOption &o)
 122 {
 123     if (this == &o)
 124         return *this;
 125
 126     QTextOptionPrivate* dNew = 0;
 127     if (o.d)
 128         dNew = new QTextOptionPrivate(*o.d);
 129     delete d;
 130     d = dNew;
 131
 132     align = o.align;
 133     wordWrap = o.wordWrap;
 134     design = o.design;
 135     direction = o.direction;
 136     unused = o.unused;
 137     f = o.f;
 138     tab = o.tab;
 139     return *this;
 140 }
 141
 142 /*!
 143     Sets the tab positions for the text layout to those specified by
 144     \a tabStops.
 145
 146     \sa tabArray(), setTabStop(), setTabs()
 147 */
 148 void QTextOption::setTabArray(QList<qreal> tabStops) // Qt5: const ref
 149 {
 150     if (!d)
 151         d = new QTextOptionPrivate;
 152     QList<QTextOption::Tab> tabs;
 153     QTextOption::Tab tab;
 154     foreach (qreal pos, tabStops) {
 155         tab.position = pos;
 156         tabs.append(tab);
 157     }
 158     d->tabStops = tabs;
 159 }
 160
 161 /*!
 162     \since 4.4
 163     Sets the tab positions for the text layout to those specified by
 164     \a tabStops.
 165
 166     \sa tabStops()
 167 */
 168 void QTextOption::setTabs(QList<QTextOption::Tab> tabStops) // Qt5: const ref
 169 {
 170     if (!d)
 171         d = new QTextOptionPrivate;
 172     d->tabStops = tabStops;
 173 }
 174
 175 /*!
 176     Returns a list of tab positions defined for the text layout.
 177
 178     \sa setTabArray(), tabStop()
 179 */
 180 QList<qreal> QTextOption::tabArray() const
 181 {
 182     if (!d)
 183         return QList<qreal>();
 184
 185     QList<qreal> answer;
 186     QList<QTextOption::Tab>::ConstIterator iter = d->tabStops.constBegin();
 187     while(iter != d->tabStops.constEnd()) {
 188         answer.append( (*iter).position);
 189         ++iter;
 190     }
 191     return answer;
 192 }
 193
 194
 195 QList<QTextOption::Tab> QTextOption::tabs() const
 196 {
 197     if (!d)
 198         return QList<QTextOption::Tab>();
 199     return d->tabStops;
 200 }
 201
 202 /*!
 203     \class QTextOption
 204     \reentrant
 205
 206     \brief The QTextOption class provides a description of general rich text
 207     properties.
 208
 209     \ingroup richtext-processing
 210
 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
 214     and layout.
 215
 216     \sa QTextEdit, QTextDocument, QTextCursor
 217 */
 218
 219 /*!
 220     \enum QTextOption::WrapMode
 221
 222     This enum describes how text is wrapped in a document.
 223
 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.
 232 */
 233
 234 /*!
 235   \fn void QTextOption::setUseDesignMetrics(bool enable)
 236
 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).
 240
 241     \sa useDesignMetrics()
 242 */
 243
 244 /*!
 245   \fn bool QTextOption::useDesignMetrics() const
 246
 247     Returns true if the layout uses design rather than device metrics;
 248     otherwise returns false.
 249
 250     \sa setUseDesignMetrics()
 251 */
 252
 253 /*!
 254   \fn Qt::Alignment QTextOption::alignment() const
 255
 256   Returns the text alignment defined by the option.
 257
 258   \sa setAlignment()
 259 */
 260
 261 /*!
 262   \fn void QTextOption::setAlignment(Qt::Alignment alignment);
 263
 264   Sets the option's text alignment to the specified \a alignment.
 265
 266   \sa alignment()
 267 */
 268
 269 /*!
 270   \fn Qt::LayoutDirection QTextOption::textDirection() const
 271
 272   Returns the direction of the text layout defined by the option.
 273
 274   \sa setTextDirection()
 275 */
 276
 277 /*!
 278   \fn void QTextOption::setTextDirection(Qt::LayoutDirection direction)
 279
 280   Sets the direction of the text layout defined by the option to the
 281   given \a direction.
 282
 283   \sa textDirection()
 284 */
 285
 286 /*!
 287   \fn WrapMode QTextOption::wrapMode() const
 288
 289   Returns the text wrap mode defined by the option.
 290
 291   \sa setWrapMode()
 292 */
 293
 294 /*!
 295   \fn void QTextOption::setWrapMode(WrapMode mode)
 296
 297   Sets the option's text wrap mode to the given \a mode.
 298 */
 299
 300 /*!
 301   \enum QTextOption::Flag
 302
 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).
 311 */
 312
 313 /*!
 314   \fn Flags QTextOption::flags() const
 315
 316   Returns the flags associated with the option.
 317
 318   \sa setFlags()
 319 */
 320
 321 /*!
 322   \fn void QTextOption::setFlags(Flags flags)
 323
 324   Sets the flags associated with the option to the given \a flags.
 325
 326   \sa flags()
 327 */
 328
 329 /*!
 330   \fn qreal QTextOption::tabStop() const
 331
 332   Returns the distance in device units between tab stops.
 333   Convenient function for the above method
 334
 335   \sa setTabStop(), tabArray(), setTabs(), tabs()
 336 */
 337
 338 /*!
 339   \fn void QTextOption::setTabStop(qreal tabStop)
 340
 341   Sets the default distance in device units between tab stops to the value specified
 342   by \a tabStop.
 343
 344   \sa tabStop(), setTabArray(), setTabs(), tabs()
 345 */
 346
 347 /*!
 348     \enum QTextOption::TabType
 349     \since 4.4
 350
 351     This enum holds the different types of tabulator
 352
 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
 357 */
 358
 359 /*!
 360     \class QTextOption::Tab
 361     \since 4.4
 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 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 Tab::delimiter
 385     If type is DelimitorTab; tab until this char is found in the text.
 386 */
 387
 388 /*!
 389     \fn Tab::Tab()
 390     Creates a default left tab with position 80.
 391 */
 392
 393 /*!
 394     \fn 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 Tab::operator==(const Tab &other) const
 406
 407     Returns true if tab \a other is equal to this tab;
 408     otherwise returns false.
 409 */
 410
 411 /*!
 412     \fn bool Tab::operator!=(const Tab &other) const
 413
 414     Returns true if tab \a other is not equal to this tab;
 415     otherwise returns false.
 416 */
 417
 418 /*!
 419   \fn void setTabs(QList<Tab> tabStops)
 420   Set the Tab properties to \a tabStops.
 421
 422   \sa tabStop(), tabs()
 423 */
 424
 425 /*!
 426   \since 4.4
 427   \fn QList<QTextOption::Tab> QTextOption::tabs() const
 428   Returns a list of tab positions defined for the text layout.
 429
 430   \sa tabStop(), setTabs(), setTabStop()
 431 */
 432
 433
 434 QT_END_NAMESPACE