src/gui/text/qtextoption.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtGui module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "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(const QList<qreal> &tabStops)
 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(const QList<QTextOption::Tab> &tabStops)
 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     \inmodule QtGui
 209
 210     \ingroup richtext-processing
 211
 212     QTextOption is used to encapsulate common rich text properties in a single
 213     object. It contains information about text alignment, layout direction,
 214     word wrapping, and other standard properties associated with text rendering
 215     and layout.
 216
 217     \sa QTextEdit, QTextDocument, QTextCursor
 218 */
 219
 220 /*!
 221     \enum QTextOption::WrapMode
 222
 223     This enum describes how text is wrapped in a document.
 224
 225     \value NoWrap       Text is not wrapped at all.
 226     \value WordWrap     Text is wrapped at word boundaries.
 227     \value ManualWrap   Same as QTextOption::NoWrap
 228     \value WrapAnywhere Text can be wrapped at any point on a line, even if
 229                         it occurs in the middle of a word.
 230     \value WrapAtWordBoundaryOrAnywhere If possible, wrapping occurs at a word
 231                         boundary; otherwise it will occur at the appropriate
 232                         point on the line, even in the middle of a word.
 233 */
 234
 235 /*!
 236   \fn void QTextOption::setUseDesignMetrics(bool enable)
 237
 238     If \a enable is true then the layout will use design metrics;
 239     otherwise it will use the metrics of the paint device (which is
 240     the default behavior).
 241
 242     \sa useDesignMetrics()
 243 */
 244
 245 /*!
 246   \fn bool QTextOption::useDesignMetrics() const
 247
 248     Returns true if the layout uses design rather than device metrics;
 249     otherwise returns false.
 250
 251     \sa setUseDesignMetrics()
 252 */
 253
 254 /*!
 255   \fn Qt::Alignment QTextOption::alignment() const
 256
 257   Returns the text alignment defined by the option.
 258
 259   \sa setAlignment()
 260 */
 261
 262 /*!
 263   \fn void QTextOption::setAlignment(Qt::Alignment alignment);
 264
 265   Sets the option's text alignment to the specified \a alignment.
 266
 267   \sa alignment()
 268 */
 269
 270 /*!
 271   \fn Qt::LayoutDirection QTextOption::textDirection() const
 272
 273   Returns the direction of the text layout defined by the option.
 274
 275   \sa setTextDirection()
 276 */
 277
 278 /*!
 279   \fn void QTextOption::setTextDirection(Qt::LayoutDirection direction)
 280
 281   Sets the direction of the text layout defined by the option to the
 282   given \a direction.
 283
 284   \sa textDirection()
 285 */
 286
 287 /*!
 288   \fn WrapMode QTextOption::wrapMode() const
 289
 290   Returns the text wrap mode defined by the option.
 291
 292   \sa setWrapMode()
 293 */
 294
 295 /*!
 296   \fn void QTextOption::setWrapMode(WrapMode mode)
 297
 298   Sets the option's text wrap mode to the given \a mode.
 299 */
 300
 301 /*!
 302   \enum QTextOption::Flag
 303
 304   \value IncludeTrailingSpaces When this option is set, QTextLine::naturalTextWidth() and naturalTextRect() will
 305                                return a value that includes the width of trailing spaces in the text; otherwise
 306                                this width is excluded.
 307   \value ShowTabsAndSpaces Visualize spaces with little dots, and tabs with little arrows.
 308   \value ShowLineAndParagraphSeparators Visualize line and paragraph separators with appropriate symbol characters.
 309   \value AddSpaceForLineAndParagraphSeparators While determining the line-break positions take into account the
 310             space added for drawing a separator character.
 311   \value SuppressColors Suppress all color changes in the character formats (except the main selection).
 312 */
 313
 314 /*!
 315   \fn Flags QTextOption::flags() const
 316
 317   Returns the flags associated with the option.
 318
 319   \sa setFlags()
 320 */
 321
 322 /*!
 323   \fn void QTextOption::setFlags(Flags flags)
 324
 325   Sets the flags associated with the option to the given \a flags.
 326
 327   \sa flags()
 328 */
 329
 330 /*!
 331   \fn qreal QTextOption::tabStop() const
 332
 333   Returns the distance in device units between tab stops.
 334   Convenient function for the above method
 335
 336   \sa setTabStop(), tabArray(), setTabs(), tabs()
 337 */
 338
 339 /*!
 340   \fn void QTextOption::setTabStop(qreal tabStop)
 341
 342   Sets the default distance in device units between tab stops to the value specified
 343   by \a tabStop.
 344
 345   \sa tabStop(), setTabArray(), setTabs(), tabs()
 346 */
 347
 348 /*!
 349     \enum QTextOption::TabType
 350     \since 4.4
 351
 352     This enum holds the different types of tabulator
 353
 354     \value LeftTab      A left-tab
 355     \value RightTab     A right-tab
 356     \value CenterTab    A centered-tab
 357     \value DelimiterTab A tab stopping at a certain delimiter-character
 358 */
 359
 360 /*!
 361     \class QTextOption::Tab
 362     \since 4.4
 363     \inmodule QtGui
 364     Each tab definition is represented by this struct.
 365 */
 366
 367 /*!
 368     \variable Tab::position
 369     Distance from the start of the paragraph.
 370     The position of a tab is from the start of the paragraph which implies that when
 371     the alignment of the paragraph is set to centered, the tab is interpreted to be
 372     moved the same distance as the left ege of the paragraph does.
 373     In case the paragraph is set to have a layoutDirection() RightToLeft the position
 374     is interpreted to be from the right side of the paragraph with higher numbers moving
 375     the tab to the left.
 376 */
 377
 378 /*!
 379     \variable Tab::type
 380     Determine which type is used.
 381     In a paragraph that has layoutDirection() RightToLeft the type LeftTab will
 382     be interpreted to be a RightTab and vice versa.
 383 */
 384
 385 /*!
 386     \variable Tab::delimiter
 387     If type is DelimitorTab; tab until this char is found in the text.
 388 */
 389
 390 /*!
 391     \fn Tab::Tab()
 392     Creates a default left tab with position 80.
 393 */
 394
 395 /*!
 396     \fn Tab::Tab(qreal pos, TabType tabType, QChar delim = QChar())
 397
 398     Creates a tab with the given position, tab type, and delimiter
 399     (\a pos, \a tabType, \a delim).
 400
 401     \note \a delim is only used when \a tabType is DelimiterTab.
 402
 403     \since 4.7
 404 */
 405
 406 /*!
 407     \fn bool Tab::operator==(const Tab &other) const
 408
 409     Returns true if tab \a other is equal to this tab;
 410     otherwise returns false.
 411 */
 412
 413 /*!
 414     \fn bool Tab::operator!=(const Tab &other) const
 415
 416     Returns true if tab \a other is not equal to this tab;
 417     otherwise returns false.
 418 */
 419
 420 /*!
 421   \fn void setTabs(QList<Tab> tabStops)
 422   Set the Tab properties to \a tabStops.
 423
 424   \sa tabStop(), tabs()
 425 */
 426
 427 /*!
 428   \since 4.4
 429   \fn QList<QTextOption::Tab> QTextOption::tabs() const
 430   Returns a list of tab positions defined for the text layout.
 431
 432   \sa tabStop(), setTabs(), setTabStop()
 433 */
 434
 435
 436 QT_END_NAMESPACE