1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 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 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include <qabstracttextdocumentlayout.h>

    43 #include <qtextformat.h>

    44 #include "qtextdocument_p.h"

    45 #include "qtextengine_p.h"

    46 

    47 #include "qabstracttextdocumentlayout_p.h"

    48 

    49 QT_BEGIN_NAMESPACE

    50 

    51 /*!

    52     \class QAbstractTextDocumentLayout

    53     \reentrant

    54 

    55     \brief The QAbstractTextDocumentLayout class is an abstract base

    56     class used to implement custom layouts for QTextDocuments.

    57 

    58     \ingroup richtext-processing

    59 

    60     The standard layout provided by Qt can handle simple word processing

    61     including inline images, lists and tables.

    62 

    63     Some applications, e.g., a word processor or a DTP application might need

    64     more features than the ones provided by Qt's layout engine, in which case

    65     you can subclass QAbstractTextDocumentLayout to provide custom layout

    66     behavior for your text documents.

    67 

    68     An instance of the QAbstractTextDocumentLayout subclass can be installed

    69     on a QTextDocument object with the

    70     \l{QTextDocument::}{setDocumentLayout()} function.

    71 

    72     You can insert custom objects into a QTextDocument; see the

    73     QTextObjectInterface class description for details.

    74 

    75     \sa QTextObjectInterface

    76 */

    77 

    78 /*!

    79     \class QTextObjectInterface

    80     \brief The QTextObjectInterface class allows drawing of

    81            custom text objects in \l{QTextDocument}s.

    82     \since 4.5

    83 

    84     A text object describes the structure of one or more elements in a

    85     text document; for instance, images imported from HTML are

    86     implemented using text objects. A text object knows how to lay out

    87     and draw its elements when a document is being rendered.

    88 

    89     Qt allows custom text objects to be inserted into a document by

    90     registering a custom \l{QTextCharFormat::objectType()}{object

    91     type} with QTextCharFormat. A QTextObjectInterface must also be

    92     implemented for this type and be

    93     \l{QAbstractTextDocumentLayout::registerHandler()}{registered}

    94     with the QAbstractTextDocumentLayout of the document. When the

    95     object type is encountered while rendering a QTextDocument, the

    96     intrinsicSize() and drawObject() functions of the interface are

    97     called.

    98 

    99     The following list explains the required steps of inserting a

   100     custom text object into a document:

   101 

   102     \list

   103         \o Choose an \a objectType. The \a objectType is an integer with a

   104             value greater or equal to QTextFormat::UserObject.

   105          \o Create a QTextCharFormat object and set the object type to the

   106             chosen type using the setObjectType() function.

   107          \o Implement the QTextObjectInterface class.

   108          \o Call QAbstractTextDocumentLayout::registerHandler() with an instance of your

   109             QTextObjectInterface subclass to register your object type.

   110          \o Insert QChar::ObjectReplacementCharacter with the aforementioned

   111             QTextCharFormat of the chosen object type into the document.

   112             As mentioned, the functions of QTextObjectInterface

   113             \l{QTextObjectInterface::}{intrinsicSize()} and

   114             \l{QTextObjectInterface::}{drawObject()} will then be called with the

   115             QTextFormat as parameter whenever the replacement character is

   116             encountered.

   117     \endlist

   118 

   119     A class implementing a text object needs to inherit both QObject

   120     and QTextObjectInterface. QObject must be the first class

   121     inherited. For instance:

   122 

   123     \snippet examples/richtext/textobject/svgtextobject.h 1

   124 

   125     The data of a text object is usually stored in the QTextCharFormat

   126     using QTextCharFormat::setProperty(), and then retrieved with

   127     QTextCharFormat::property().

   128 

   129     \warning Copy and Paste operations ignore custom text objects.

   130 

   131     \sa {Text Object Example}, QTextCharFormat, QTextLayout

   132 */

   133 

   134 /*!

   135     \fn QTextObjectInterface::~QTextObjectInterface()

   136 

   137     Destroys this QTextObjectInterface.

   138 */

   139 

   140 /*!

   141     \fn virtual QSizeF QTextObjectInterface::intrinsicSize(QTextDocument *doc, int posInDocument, const QTextFormat &format) = 0

   142 

   143     The intrinsicSize() function returns the size of the text object

   144     represented by \a format in the given document (\a doc) at the

   145     given position (\a posInDocument).

   146 

   147     The size calculated will be used for subsequent calls to

   148     drawObject() for this \a format.

   149 

   150     \sa drawObject()

   151 */

   152 

   153 /*!

   154     \fn virtual void QTextObjectInterface::drawObject(QPainter *painter, const QRectF &rect, QTextDocument *doc, int posInDocument, const QTextFormat &format) = 0

   155 

   156     Draws this text object using the specified \a painter.

   157 

   158     The size of the rectangle, \a rect, to draw in is the size

   159     previously calculated by intrinsicSize(). The rectangles position

   160     is relative to the \a painter.

   161 

   162     You also get the document (\a doc) and the position (\a

   163     posInDocument) of the \a format in that document.

   164 

   165     \sa intrinsicSize()

   166 */

   167 

   168 /*!

   169     \fn void QAbstractTextDocumentLayout::update(const QRectF &rect)

   170 

   171     This signal is emitted when the rectangle \a rect has been updated.

   172 

   173     Subclasses of QAbstractTextDocumentLayout should emit this signal when

   174     the layout of the contents change in order to repaint.

   175 */

   176 

   177 /*!

   178    \fn void QAbstractTextDocumentLayout::updateBlock(const QTextBlock &block)

   179    \since 4.4

   180 

   181    This signal is emitted when the specified \a block has been updated.

   182 

   183    Subclasses of QAbstractTextDocumentLayout should emit this signal when

   184    the layout of \a block has changed in order to repaint. 

   185 */

   186 

   187 /*!

   188     \fn void QAbstractTextDocumentLayout::documentSizeChanged(const QSizeF &newSize)

   189 

   190     This signal is emitted when the size of the document layout changes to

   191     \a newSize.

   192 

   193     Subclasses of QAbstractTextDocumentLayout should emit this signal when the

   194     document's entire layout size changes. This signal is useful for widgets

   195     that display text documents since it enables them to update their scroll

   196     bars correctly.

   197 

   198     \sa documentSize()

   199 */

   200 

   201 /*!

   202     \fn void QAbstractTextDocumentLayout::pageCountChanged(int newPages)

   203 

   204     This signal is emitted when the number of pages in the layout changes;

   205     \a newPages is the updated page count.

   206 

   207     Subclasses of QAbstractTextDocumentLayout should emit this signal when

   208     the number of pages in the layout has changed. Changes to the page count

   209     are caused by changes to the layout or the document content itself.

   210 

   211     \sa pageCount()

   212 */

   213 

   214 /*!

   215     \fn int QAbstractTextDocumentLayout::pageCount() const

   216 

   217     Returns the number of pages contained in the layout.

   218 

   219     \sa pageCountChanged()

   220 */

   221 

   222 /*!

   223     \fn QSizeF QAbstractTextDocumentLayout::documentSize() const

   224 

   225     Returns the total size of the document's layout.

   226 

   227     This information can be used by display widgets to update their scroll bars

   228     correctly.

   229 

   230     \sa documentSizeChanged(), QTextDocument::pageSize

   231 */

   232 

   233 /*!

   234     \fn void QAbstractTextDocumentLayout::draw(QPainter *painter, const PaintContext &context)

   235 

   236     Draws the layout with the given \a painter using the given \a context.

   237 */

   238 

   239 /*!

   240     \fn int QAbstractTextDocumentLayout::hitTest(const QPointF &point, Qt::HitTestAccuracy accuracy) const

   241 

   242     Returns the cursor postion for the given \a point with the specified

   243     \a accuracy. Returns -1 if no valid cursor position was found.

   244 */

   245 

   246 /*!

   247     \fn void QAbstractTextDocumentLayout::documentChanged(int position, int charsRemoved, int charsAdded)

   248 

   249     This function is called whenever the contents of the document change. A

   250     change occurs when text is inserted, removed, or a combination of these

   251     two. The change is specified by \a position, \a charsRemoved, and

   252     \a charsAdded corresponding to the starting character position of the

   253     change, the number of characters removed from the document, and the

   254     number of characters added.

   255 

   256     For example, when inserting the text "Hello" into an empty document,

   257     \a charsRemoved would be 0 and \a charsAdded would be 5 (the length of

   258     the string).

   259 

   260     Replacing text is a combination of removing and inserting. For example, if

   261     the text "Hello" gets replaced by "Hi", \a charsRemoved would be 5 and

   262     \a charsAdded would be 2.

   263 

   264     For subclasses of QAbstractTextDocumentLayout, this is the central function

   265     where a large portion of the work to lay out and position document contents

   266     is done.

   267 

   268     For example, in a subclass that only arranges blocks of text, an

   269     implementation of this function would have to do the following:

   270 

   271     \list

   272         \o Determine the list of changed \l{QTextBlock}(s) using the parameters

   273             provided.

   274         \o Each QTextBlock object's corresponding QTextLayout object needs to

   275             be processed. You can access the \l{QTextBlock}'s layout using the

   276             QTextBlock::layout() function. This processing should take the

   277             document's page size into consideration.

   278         \o If the total number of pages changed, the pageCountChanged() signal

   279             should be emitted.

   280         \o If the total size changed, the documentSizeChanged() signal should

   281             be emitted.

   282         \o The update() signal should be emitted to schedule a repaint of areas

   283             in the layout that require repainting.

   284     \endlist

   285 

   286     \sa QTextLayout

   287 */

   288 

   289 /*!

   290     \class QAbstractTextDocumentLayout::PaintContext

   291     \reentrant

   292 

   293     \brief The QAbstractTextDocumentLayout::PaintContext class is a convenience

   294     class defining the parameters used when painting a document's layout.

   295 

   296     A paint context is used when rendering custom layouts for QTextDocuments

   297     with the QAbstractTextDocumentLayout::draw() function. It is specified by

   298     a \l {cursorPosition}{cursor position}, \l {palette}{default text color},

   299     \l clip rectangle and a collection of \l selections.

   300 

   301     \sa QAbstractTextDocumentLayout

   302 */

   303 

   304 /*!

   305     \fn QAbstractTextDocumentLayout::PaintContext::PaintContext()

   306     \internal

   307 */

   308 

   309 /*!

   310     \variable QAbstractTextDocumentLayout::PaintContext::cursorPosition

   311 

   312     \brief the position within the document, where the cursor line should be

   313     drawn.

   314 

   315     The default value is -1.

   316 */

   317 

   318 /*!

   319     \variable QAbstractTextDocumentLayout::PaintContext::palette

   320 

   321     \brief the default color that is used for the text, when no color is

   322     specified.

   323 

   324     The default value is the application's default palette.

   325 */

   326 

   327 /*!

   328     \variable QAbstractTextDocumentLayout::PaintContext::clip

   329 

   330     \brief a hint to the layout specifying the area around paragraphs, frames

   331     or text require painting.

   332 

   333     Everything outside of this rectangle does not need to be painted.

   334 

   335     Specifying a clip rectangle can speed up drawing of large documents

   336     significantly. Note that the clip rectangle is in document coordinates (not

   337     in viewport coordinates). It is not a substitute for a clip region set on

   338     the painter but merely a hint.

   339 

   340     The default value is a null rectangle indicating everything needs to be

   341     painted.

   342 */

   343 

   344 /*!

   345     \variable QAbstractTextDocumentLayout::PaintContext::selections

   346 

   347     \brief the collection of selections that will be rendered when passing this

   348     paint context to QAbstractTextDocumentLayout's draw() function.

   349 

   350     The default value is an empty vector indicating no selection.

   351 */

   352 

   353 /*!

   354     \class QAbstractTextDocumentLayout::Selection

   355     \reentrant

   356 

   357     \brief The QAbstractTextDocumentLayout::Selection class is a convenience

   358     class defining the parameters of a selection.

   359 

   360     A selection can be used to specify a part of a document that should be

   361     highlighted when drawing custom layouts for QTextDocuments with the

   362     QAbstractTextDocumentLayout::draw() function. It is specified using

   363     \l cursor and a \l format.

   364 

   365     \sa QAbstractTextDocumentLayout, PaintContext

   366 */

   367 

   368 /*!

   369     \variable QAbstractTextDocumentLayout::Selection::format

   370 

   371     \brief the format of the selection

   372 

   373     The default value is QTextFormat::InvalidFormat.

   374 */

   375 

   376 /*!

   377     \variable QAbstractTextDocumentLayout::Selection::cursor

   378     \brief the selection's cursor

   379 

   380     The default value is a null cursor.

   381 */

   382 

   383 /*!

   384     Creates a new text document layout for the given \a document.

   385 */

   386 QAbstractTextDocumentLayout::QAbstractTextDocumentLayout(QTextDocument *document)

   387     : QObject(*new QAbstractTextDocumentLayoutPrivate, document)

   388 {

   389     Q_D(QAbstractTextDocumentLayout);

   390     d->setDocument(document);

   391 }

   392 

   393 /*!

   394     \internal

   395 */

   396 QAbstractTextDocumentLayout::QAbstractTextDocumentLayout(QAbstractTextDocumentLayoutPrivate &p, QTextDocument *document)

   397     :QObject(p, document)

   398 {

   399     Q_D(QAbstractTextDocumentLayout);

   400     d->setDocument(document);

   401 }

   402 

   403 /*!

   404     \internal

   405 */

   406 QAbstractTextDocumentLayout::~QAbstractTextDocumentLayout()

   407 {

   408 }

   409 

   410 /*!

   411     \fn void QAbstractTextDocumentLayout::registerHandler(int objectType, QObject *component)

   412 

   413     Registers the given \a component as a handler for items of the given \a objectType.

   414 

   415     \note registerHandler() has to be called once for each object type. This

   416     means that there is only one handler for multiple replacement characters

   417     of the same object type.

   418 */

   419 void QAbstractTextDocumentLayout::registerHandler(int formatType, QObject *component)

   420 {

   421     Q_D(QAbstractTextDocumentLayout);

   422 

   423     QTextObjectInterface *iface = qobject_cast<QTextObjectInterface *>(component);

   424     if (!iface)

   425         return; // ### print error message on terminal?

   426 

   427     connect(component, SIGNAL(destroyed(QObject*)), this, SLOT(_q_handlerDestroyed(QObject*)));

   428 

   429     QTextObjectHandler h;

   430     h.iface = iface;

   431     h.component = component;

   432     d->handlers.insert(formatType, h);

   433 }

   434 

   435 /*!

   436     Returns a handler for objects of the given \a objectType.

   437 */

   438 QTextObjectInterface *QAbstractTextDocumentLayout::handlerForObject(int objectType) const

   439 {

   440     Q_D(const QAbstractTextDocumentLayout);

   441 

   442     QTextObjectHandler handler = d->handlers.value(objectType);

   443     if (!handler.component)

   444         return 0;

   445 

   446     return handler.iface;

   447 }

   448 

   449 /*!

   450     Sets the size of the inline object \a item corresponding to the text

   451     \a format.

   452 

   453     \a posInDocument specifies the position of the object within the document.

   454 

   455     The default implementation resizes the \a item to the size returned by

   456     the object handler's intrinsicSize() function. This function is called only

   457     within Qt. Subclasses can reimplement this function to customize the

   458     resizing of inline objects.

   459 */

   460 void QAbstractTextDocumentLayout::resizeInlineObject(QTextInlineObject item, int posInDocument, const QTextFormat &format)

   461 {

   462     Q_D(QAbstractTextDocumentLayout);

   463 

   464     QTextCharFormat f = format.toCharFormat();

   465     Q_ASSERT(f.isValid());

   466     QTextObjectHandler handler = d->handlers.value(f.objectType());

   467     if (!handler.component)

   468         return;

   469 

   470     QSizeF s = handler.iface->intrinsicSize(document(), posInDocument, format);

   471     item.setWidth(s.width());

   472     item.setAscent(s.height() - 1);

   473     item.setDescent(0);

   474 }

   475 

   476 /*!

   477     Lays out the inline object \a item using the given text \a format.

   478 

   479     \a posInDocument specifies the position of the object within the document.

   480 

   481     The default implementation does nothing. This function is called only

   482     within Qt. Subclasses can reimplement this function to customize the

   483     position of inline objects.

   484 

   485     \sa drawInlineObject()

   486 */

   487 void QAbstractTextDocumentLayout::positionInlineObject(QTextInlineObject item, int posInDocument, const QTextFormat &format)

   488 {

   489     Q_UNUSED(item);

   490     Q_UNUSED(posInDocument);

   491     Q_UNUSED(format);

   492 }

   493 

   494 /*!

   495     \fn void QAbstractTextDocumentLayout::drawInlineObject(QPainter *painter, const QRectF &rect, QTextInlineObject object, int posInDocument, const QTextFormat &format)

   496 

   497     This function is called to draw the inline object, \a object, with the

   498     given \a painter within the rectangle specified by \a rect using the

   499     specified text \a format.

   500 

   501     \a posInDocument specifies the position of the object within the document.

   502 

   503     The default implementation calls drawObject() on the object handlers. This

   504     function is called only within Qt. Subclasses can reimplement this function

   505     to customize the drawing of inline objects.

   506 

   507     \sa draw()

   508 */

   509 void QAbstractTextDocumentLayout::drawInlineObject(QPainter *p, const QRectF &rect, QTextInlineObject item,

   510                                                    int posInDocument, const QTextFormat &format)

   511 {

   512     Q_UNUSED(item);

   513     Q_D(QAbstractTextDocumentLayout);

   514 

   515     QTextCharFormat f = format.toCharFormat();

   516     Q_ASSERT(f.isValid());

   517     QTextObjectHandler handler = d->handlers.value(f.objectType());

   518     if (!handler.component)

   519         return;

   520 

   521     handler.iface->drawObject(p, rect, document(), posInDocument, format);

   522 }

   523 

   524 void QAbstractTextDocumentLayoutPrivate::_q_handlerDestroyed(QObject *obj)

   525 {

   526     HandlerHash::Iterator it = handlers.begin();

   527     while (it != handlers.end())

   528         if ((*it).component == obj)

   529             it = handlers.erase(it);

   530         else

   531             ++it;

   532 }

   533 

   534 /*!

   535     \internal

   536 

   537     Returns the index of the format at position \a pos.

   538 */

   539 int QAbstractTextDocumentLayout::formatIndex(int pos)

   540 {

   541     QTextDocumentPrivate *pieceTable = qobject_cast<QTextDocument *>(parent())->docHandle();

   542     return pieceTable->find(pos).value()->format;

   543 }

   544 

   545 /*!

   546     \fn QTextCharFormat QAbstractTextDocumentLayout::format(int position)

   547 

   548     Returns the character format that is applicable at the given \a position.

   549 */

   550 QTextCharFormat QAbstractTextDocumentLayout::format(int pos)

   551 {

   552     QTextDocumentPrivate *pieceTable = qobject_cast<QTextDocument *>(parent())->docHandle();

   553     int idx = pieceTable->find(pos).value()->format;

   554     return pieceTable->formatCollection()->charFormat(idx);

   555 }

   556 

   557 

   558 

   559 /*!

   560     Returns the text document that this layout is operating on.

   561 */

   562 QTextDocument *QAbstractTextDocumentLayout::document() const

   563 {

   564     Q_D(const QAbstractTextDocumentLayout);

   565     return d->document;

   566 }

   567 

   568 /*!

   569     \fn QString QAbstractTextDocumentLayout::anchorAt(const QPointF &position) const

   570 

   571     Returns the reference of the anchor the given \a position, or an empty

   572     string if no anchor exists at that point.

   573 */

   574 QString QAbstractTextDocumentLayout::anchorAt(const QPointF& pos) const

   575 {

   576     int cursorPos = hitTest(pos, Qt::ExactHit);

   577     if (cursorPos == -1)

   578         return QString();

   579 

   580     QTextDocumentPrivate *pieceTable = qobject_cast<const QTextDocument *>(parent())->docHandle();

   581     QTextDocumentPrivate::FragmentIterator it = pieceTable->find(cursorPos);

   582     QTextCharFormat fmt = pieceTable->formatCollection()->charFormat(it->format);

   583     return fmt.anchorHref();

   584 }

   585 

   586 /*!

   587     \fn QRectF QAbstractTextDocumentLayout::frameBoundingRect(QTextFrame *frame) const

   588 

   589     Returns the bounding rectangle of \a frame.

   590 */

   591 

   592 /*!

   593     \fn QRectF QAbstractTextDocumentLayout::blockBoundingRect(const QTextBlock &block) const

   594 

   595     Returns the bounding rectangle of \a block.

   596 */

   597 

   598 /*!

   599     Sets the paint device used for rendering the document's layout to the given

   600     \a device.

   601 

   602     \sa paintDevice()

   603 */

   604 void QAbstractTextDocumentLayout::setPaintDevice(QPaintDevice *device)

   605 {

   606     Q_D(QAbstractTextDocumentLayout);

   607     d->paintDevice = device;

   608 }

   609 

   610 /*!

   611     Returns the paint device used to render the document's layout.

   612 

   613     \sa setPaintDevice()

   614 */

   615 QPaintDevice *QAbstractTextDocumentLayout::paintDevice() const

   616 {

   617     Q_D(const QAbstractTextDocumentLayout);

   618     return d->paintDevice;

   619 }

   620 

   621 QT_END_NAMESPACE

   622 

   623 #include "moc_qabstracttextdocumentlayout.cpp"