/**************************************************************************** | |
** | |
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). | |
** All rights reserved. | |
** Contact: Nokia Corporation (qt-info@nokia.com) | |
** | |
** This file is part of the QtGui module of the Qt Toolkit. | |
** | |
** $QT_BEGIN_LICENSE:LGPL$ | |
** GNU Lesser General Public License Usage | |
** This file may be used under the terms of the GNU Lesser General Public | |
** License version 2.1 as published by the Free Software Foundation and | |
** appearing in the file LICENSE.LGPL included in the packaging of this | |
** file. Please review the following information to ensure the GNU Lesser | |
** General Public License version 2.1 requirements will be met: | |
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. | |
** | |
** In addition, as a special exception, Nokia gives you certain additional | |
** rights. These rights are described in the Nokia Qt LGPL Exception | |
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. | |
** | |
** GNU General Public License Usage | |
** Alternatively, this file may be used under the terms of the GNU General | |
** Public License version 3.0 as published by the Free Software Foundation | |
** and appearing in the file LICENSE.GPL included in the packaging of this | |
** file. Please review the following information to ensure the GNU General | |
** Public License version 3.0 requirements will be met: | |
** http://www.gnu.org/copyleft/gpl.html. | |
** | |
** Other Usage | |
** Alternatively, this file may be used in accordance with the terms and | |
** conditions contained in a signed written agreement between you and Nokia. | |
** | |
** | |
** | |
** | |
** | |
** $QT_END_LICENSE$ | |
** | |
****************************************************************************/ | |
#include <qabstracttextdocumentlayout.h> | |
#include <qtextformat.h> | |
#include "qtextdocument_p.h" | |
#include "qtextengine_p.h" | |
#include "qabstracttextdocumentlayout_p.h" | |
QT_BEGIN_NAMESPACE | |
/*! | |
\class QAbstractTextDocumentLayout | |
\reentrant | |
\brief The QAbstractTextDocumentLayout class is an abstract base | |
class used to implement custom layouts for QTextDocuments. | |
\ingroup richtext-processing | |
The standard layout provided by Qt can handle simple word processing | |
including inline images, lists and tables. | |
Some applications, e.g., a word processor or a DTP application might need | |
more features than the ones provided by Qt's layout engine, in which case | |
you can subclass QAbstractTextDocumentLayout to provide custom layout | |
behavior for your text documents. | |
An instance of the QAbstractTextDocumentLayout subclass can be installed | |
on a QTextDocument object with the | |
\l{QTextDocument::}{setDocumentLayout()} function. | |
You can insert custom objects into a QTextDocument; see the | |
QTextObjectInterface class description for details. | |
\sa QTextObjectInterface | |
*/ | |
/*! | |
\class QTextObjectInterface | |
\brief The QTextObjectInterface class allows drawing of | |
custom text objects in \l{QTextDocument}s. | |
\since 4.5 | |
A text object describes the structure of one or more elements in a | |
text document; for instance, images imported from HTML are | |
implemented using text objects. A text object knows how to lay out | |
and draw its elements when a document is being rendered. | |
Qt allows custom text objects to be inserted into a document by | |
registering a custom \l{QTextCharFormat::objectType()}{object | |
type} with QTextCharFormat. A QTextObjectInterface must also be | |
implemented for this type and be | |
\l{QAbstractTextDocumentLayout::registerHandler()}{registered} | |
with the QAbstractTextDocumentLayout of the document. When the | |
object type is encountered while rendering a QTextDocument, the | |
intrinsicSize() and drawObject() functions of the interface are | |
called. | |
The following list explains the required steps of inserting a | |
custom text object into a document: | |
\list | |
\o Choose an \a objectType. The \a objectType is an integer with a | |
value greater or equal to QTextFormat::UserObject. | |
\o Create a QTextCharFormat object and set the object type to the | |
chosen type using the setObjectType() function. | |
\o Implement the QTextObjectInterface class. | |
\o Call QAbstractTextDocumentLayout::registerHandler() with an instance of your | |
QTextObjectInterface subclass to register your object type. | |
\o Insert QChar::ObjectReplacementCharacter with the aforementioned | |
QTextCharFormat of the chosen object type into the document. | |
As mentioned, the functions of QTextObjectInterface | |
\l{QTextObjectInterface::}{intrinsicSize()} and | |
\l{QTextObjectInterface::}{drawObject()} will then be called with the | |
QTextFormat as parameter whenever the replacement character is | |
encountered. | |
\endlist | |
A class implementing a text object needs to inherit both QObject | |
and QTextObjectInterface. QObject must be the first class | |
inherited. For instance: | |
\snippet examples/richtext/textobject/svgtextobject.h 1 | |
The data of a text object is usually stored in the QTextCharFormat | |
using QTextCharFormat::setProperty(), and then retrieved with | |
QTextCharFormat::property(). | |
\warning Copy and Paste operations ignore custom text objects. | |
\sa {Text Object Example}, QTextCharFormat, QTextLayout | |
*/ | |
/*! | |
\fn QTextObjectInterface::~QTextObjectInterface() | |
Destroys this QTextObjectInterface. | |
*/ | |
/*! | |
\fn virtual QSizeF QTextObjectInterface::intrinsicSize(QTextDocument *doc, int posInDocument, const QTextFormat &format) = 0 | |
The intrinsicSize() function returns the size of the text object | |
represented by \a format in the given document (\a doc) at the | |
given position (\a posInDocument). | |
The size calculated will be used for subsequent calls to | |
drawObject() for this \a format. | |
\sa drawObject() | |
*/ | |
/*! | |
\fn virtual void QTextObjectInterface::drawObject(QPainter *painter, const QRectF &rect, QTextDocument *doc, int posInDocument, const QTextFormat &format) = 0 | |
Draws this text object using the specified \a painter. | |
The size of the rectangle, \a rect, to draw in is the size | |
previously calculated by intrinsicSize(). The rectangles position | |
is relative to the \a painter. | |
You also get the document (\a doc) and the position (\a | |
posInDocument) of the \a format in that document. | |
\sa intrinsicSize() | |
*/ | |
/*! | |
\fn void QAbstractTextDocumentLayout::update(const QRectF &rect) | |
This signal is emitted when the rectangle \a rect has been updated. | |
Subclasses of QAbstractTextDocumentLayout should emit this signal when | |
the layout of the contents change in order to repaint. | |
*/ | |
/*! | |
\fn void QAbstractTextDocumentLayout::updateBlock(const QTextBlock &block) | |
\since 4.4 | |
This signal is emitted when the specified \a block has been updated. | |
Subclasses of QAbstractTextDocumentLayout should emit this signal when | |
the layout of \a block has changed in order to repaint. | |
*/ | |
/*! | |
\fn void QAbstractTextDocumentLayout::documentSizeChanged(const QSizeF &newSize) | |
This signal is emitted when the size of the document layout changes to | |
\a newSize. | |
Subclasses of QAbstractTextDocumentLayout should emit this signal when the | |
document's entire layout size changes. This signal is useful for widgets | |
that display text documents since it enables them to update their scroll | |
bars correctly. | |
\sa documentSize() | |
*/ | |
/*! | |
\fn void QAbstractTextDocumentLayout::pageCountChanged(int newPages) | |
This signal is emitted when the number of pages in the layout changes; | |
\a newPages is the updated page count. | |
Subclasses of QAbstractTextDocumentLayout should emit this signal when | |
the number of pages in the layout has changed. Changes to the page count | |
are caused by changes to the layout or the document content itself. | |
\sa pageCount() | |
*/ | |
/*! | |
\fn int QAbstractTextDocumentLayout::pageCount() const | |
Returns the number of pages contained in the layout. | |
\sa pageCountChanged() | |
*/ | |
/*! | |
\fn QSizeF QAbstractTextDocumentLayout::documentSize() const | |
Returns the total size of the document's layout. | |
This information can be used by display widgets to update their scroll bars | |
correctly. | |
\sa documentSizeChanged(), QTextDocument::pageSize | |
*/ | |
/*! | |
\fn void QAbstractTextDocumentLayout::draw(QPainter *painter, const PaintContext &context) | |
Draws the layout with the given \a painter using the given \a context. | |
*/ | |
/*! | |
\fn int QAbstractTextDocumentLayout::hitTest(const QPointF &point, Qt::HitTestAccuracy accuracy) const | |
Returns the cursor postion for the given \a point with the specified | |
\a accuracy. Returns -1 if no valid cursor position was found. | |
*/ | |
/*! | |
\fn void QAbstractTextDocumentLayout::documentChanged(int position, int charsRemoved, int charsAdded) | |
This function is called whenever the contents of the document change. A | |
change occurs when text is inserted, removed, or a combination of these | |
two. The change is specified by \a position, \a charsRemoved, and | |
\a charsAdded corresponding to the starting character position of the | |
change, the number of characters removed from the document, and the | |
number of characters added. | |
For example, when inserting the text "Hello" into an empty document, | |
\a charsRemoved would be 0 and \a charsAdded would be 5 (the length of | |
the string). | |
Replacing text is a combination of removing and inserting. For example, if | |
the text "Hello" gets replaced by "Hi", \a charsRemoved would be 5 and | |
\a charsAdded would be 2. | |
For subclasses of QAbstractTextDocumentLayout, this is the central function | |
where a large portion of the work to lay out and position document contents | |
is done. | |
For example, in a subclass that only arranges blocks of text, an | |
implementation of this function would have to do the following: | |
\list | |
\o Determine the list of changed \l{QTextBlock}(s) using the parameters | |
provided. | |
\o Each QTextBlock object's corresponding QTextLayout object needs to | |
be processed. You can access the \l{QTextBlock}'s layout using the | |
QTextBlock::layout() function. This processing should take the | |
document's page size into consideration. | |
\o If the total number of pages changed, the pageCountChanged() signal | |
should be emitted. | |
\o If the total size changed, the documentSizeChanged() signal should | |
be emitted. | |
\o The update() signal should be emitted to schedule a repaint of areas | |
in the layout that require repainting. | |
\endlist | |
\sa QTextLayout | |
*/ | |
/*! | |
\class QAbstractTextDocumentLayout::PaintContext | |
\reentrant | |
\brief The QAbstractTextDocumentLayout::PaintContext class is a convenience | |
class defining the parameters used when painting a document's layout. | |
A paint context is used when rendering custom layouts for QTextDocuments | |
with the QAbstractTextDocumentLayout::draw() function. It is specified by | |
a \l {cursorPosition}{cursor position}, \l {palette}{default text color}, | |
\l clip rectangle and a collection of \l selections. | |
\sa QAbstractTextDocumentLayout | |
*/ | |
/*! | |
\fn QAbstractTextDocumentLayout::PaintContext::PaintContext() | |
\internal | |
*/ | |
/*! | |
\variable QAbstractTextDocumentLayout::PaintContext::cursorPosition | |
\brief the position within the document, where the cursor line should be | |
drawn. | |
The default value is -1. | |
*/ | |
/*! | |
\variable QAbstractTextDocumentLayout::PaintContext::palette | |
\brief the default color that is used for the text, when no color is | |
specified. | |
The default value is the application's default palette. | |
*/ | |
/*! | |
\variable QAbstractTextDocumentLayout::PaintContext::clip | |
\brief a hint to the layout specifying the area around paragraphs, frames | |
or text require painting. | |
Everything outside of this rectangle does not need to be painted. | |
Specifying a clip rectangle can speed up drawing of large documents | |
significantly. Note that the clip rectangle is in document coordinates (not | |
in viewport coordinates). It is not a substitute for a clip region set on | |
the painter but merely a hint. | |
The default value is a null rectangle indicating everything needs to be | |
painted. | |
*/ | |
/*! | |
\variable QAbstractTextDocumentLayout::PaintContext::selections | |
\brief the collection of selections that will be rendered when passing this | |
paint context to QAbstractTextDocumentLayout's draw() function. | |
The default value is an empty vector indicating no selection. | |
*/ | |
/*! | |
\class QAbstractTextDocumentLayout::Selection | |
\reentrant | |
\brief The QAbstractTextDocumentLayout::Selection class is a convenience | |
class defining the parameters of a selection. | |
A selection can be used to specify a part of a document that should be | |
highlighted when drawing custom layouts for QTextDocuments with the | |
QAbstractTextDocumentLayout::draw() function. It is specified using | |
\l cursor and a \l format. | |
\sa QAbstractTextDocumentLayout, PaintContext | |
*/ | |
/*! | |
\variable QAbstractTextDocumentLayout::Selection::format | |
\brief the format of the selection | |
The default value is QTextFormat::InvalidFormat. | |
*/ | |
/*! | |
\variable QAbstractTextDocumentLayout::Selection::cursor | |
\brief the selection's cursor | |
The default value is a null cursor. | |
*/ | |
/*! | |
Creates a new text document layout for the given \a document. | |
*/ | |
QAbstractTextDocumentLayout::QAbstractTextDocumentLayout(QTextDocument *document) | |
: QObject(*new QAbstractTextDocumentLayoutPrivate, document) | |
{ | |
Q_D(QAbstractTextDocumentLayout); | |
d->setDocument(document); | |
} | |
/*! | |
\internal | |
*/ | |
QAbstractTextDocumentLayout::QAbstractTextDocumentLayout(QAbstractTextDocumentLayoutPrivate &p, QTextDocument *document) | |
:QObject(p, document) | |
{ | |
Q_D(QAbstractTextDocumentLayout); | |
d->setDocument(document); | |
} | |
/*! | |
\internal | |
*/ | |
QAbstractTextDocumentLayout::~QAbstractTextDocumentLayout() | |
{ | |
} | |
/*! | |
\fn void QAbstractTextDocumentLayout::registerHandler(int objectType, QObject *component) | |
Registers the given \a component as a handler for items of the given \a objectType. | |
\note registerHandler() has to be called once for each object type. This | |
means that there is only one handler for multiple replacement characters | |
of the same object type. | |
*/ | |
void QAbstractTextDocumentLayout::registerHandler(int formatType, QObject *component) | |
{ | |
Q_D(QAbstractTextDocumentLayout); | |
QTextObjectInterface *iface = qobject_cast<QTextObjectInterface *>(component); | |
if (!iface) | |
return; // ### print error message on terminal? | |
connect(component, SIGNAL(destroyed(QObject*)), this, SLOT(_q_handlerDestroyed(QObject*))); | |
QTextObjectHandler h; | |
h.iface = iface; | |
h.component = component; | |
d->handlers.insert(formatType, h); | |
} | |
/*! | |
Returns a handler for objects of the given \a objectType. | |
*/ | |
QTextObjectInterface *QAbstractTextDocumentLayout::handlerForObject(int objectType) const | |
{ | |
Q_D(const QAbstractTextDocumentLayout); | |
QTextObjectHandler handler = d->handlers.value(objectType); | |
if (!handler.component) | |
return 0; | |
return handler.iface; | |
} | |
/*! | |
Sets the size of the inline object \a item corresponding to the text | |
\a format. | |
\a posInDocument specifies the position of the object within the document. | |
The default implementation resizes the \a item to the size returned by | |
the object handler's intrinsicSize() function. This function is called only | |
within Qt. Subclasses can reimplement this function to customize the | |
resizing of inline objects. | |
*/ | |
void QAbstractTextDocumentLayout::resizeInlineObject(QTextInlineObject item, int posInDocument, const QTextFormat &format) | |
{ | |
Q_D(QAbstractTextDocumentLayout); | |
QTextCharFormat f = format.toCharFormat(); | |
Q_ASSERT(f.isValid()); | |
QTextObjectHandler handler = d->handlers.value(f.objectType()); | |
if (!handler.component) | |
return; | |
QSizeF s = handler.iface->intrinsicSize(document(), posInDocument, format); | |
item.setWidth(s.width()); | |
item.setAscent(s.height() - 1); | |
item.setDescent(0); | |
} | |
/*! | |
Lays out the inline object \a item using the given text \a format. | |
\a posInDocument specifies the position of the object within the document. | |
The default implementation does nothing. This function is called only | |
within Qt. Subclasses can reimplement this function to customize the | |
position of inline objects. | |
\sa drawInlineObject() | |
*/ | |
void QAbstractTextDocumentLayout::positionInlineObject(QTextInlineObject item, int posInDocument, const QTextFormat &format) | |
{ | |
Q_UNUSED(item); | |
Q_UNUSED(posInDocument); | |
Q_UNUSED(format); | |
} | |
/*! | |
\fn void QAbstractTextDocumentLayout::drawInlineObject(QPainter *painter, const QRectF &rect, QTextInlineObject object, int posInDocument, const QTextFormat &format) | |
This function is called to draw the inline object, \a object, with the | |
given \a painter within the rectangle specified by \a rect using the | |
specified text \a format. | |
\a posInDocument specifies the position of the object within the document. | |
The default implementation calls drawObject() on the object handlers. This | |
function is called only within Qt. Subclasses can reimplement this function | |
to customize the drawing of inline objects. | |
\sa draw() | |
*/ | |
void QAbstractTextDocumentLayout::drawInlineObject(QPainter *p, const QRectF &rect, QTextInlineObject item, | |
int posInDocument, const QTextFormat &format) | |
{ | |
Q_UNUSED(item); | |
Q_D(QAbstractTextDocumentLayout); | |
QTextCharFormat f = format.toCharFormat(); | |
Q_ASSERT(f.isValid()); | |
QTextObjectHandler handler = d->handlers.value(f.objectType()); | |
if (!handler.component) | |
return; | |
handler.iface->drawObject(p, rect, document(), posInDocument, format); | |
} | |
void QAbstractTextDocumentLayoutPrivate::_q_handlerDestroyed(QObject *obj) | |
{ | |
HandlerHash::Iterator it = handlers.begin(); | |
while (it != handlers.end()) | |
if ((*it).component == obj) | |
it = handlers.erase(it); | |
else | |
++it; | |
} | |
/*! | |
\internal | |
Returns the index of the format at position \a pos. | |
*/ | |
int QAbstractTextDocumentLayout::formatIndex(int pos) | |
{ | |
QTextDocumentPrivate *pieceTable = qobject_cast<QTextDocument *>(parent())->docHandle(); | |
return pieceTable->find(pos).value()->format; | |
} | |
/*! | |
\fn QTextCharFormat QAbstractTextDocumentLayout::format(int position) | |
Returns the character format that is applicable at the given \a position. | |
*/ | |
QTextCharFormat QAbstractTextDocumentLayout::format(int pos) | |
{ | |
QTextDocumentPrivate *pieceTable = qobject_cast<QTextDocument *>(parent())->docHandle(); | |
int idx = pieceTable->find(pos).value()->format; | |
return pieceTable->formatCollection()->charFormat(idx); | |
} | |
/*! | |
Returns the text document that this layout is operating on. | |
*/ | |
QTextDocument *QAbstractTextDocumentLayout::document() const | |
{ | |
Q_D(const QAbstractTextDocumentLayout); | |
return d->document; | |
} | |
/*! | |
\fn QString QAbstractTextDocumentLayout::anchorAt(const QPointF &position) const | |
Returns the reference of the anchor the given \a position, or an empty | |
string if no anchor exists at that point. | |
*/ | |
QString QAbstractTextDocumentLayout::anchorAt(const QPointF& pos) const | |
{ | |
int cursorPos = hitTest(pos, Qt::ExactHit); | |
if (cursorPos == -1) | |
return QString(); | |
QTextDocumentPrivate *pieceTable = qobject_cast<const QTextDocument *>(parent())->docHandle(); | |
QTextDocumentPrivate::FragmentIterator it = pieceTable->find(cursorPos); | |
QTextCharFormat fmt = pieceTable->formatCollection()->charFormat(it->format); | |
return fmt.anchorHref(); | |
} | |
/*! | |
\fn QRectF QAbstractTextDocumentLayout::frameBoundingRect(QTextFrame *frame) const | |
Returns the bounding rectangle of \a frame. | |
*/ | |
/*! | |
\fn QRectF QAbstractTextDocumentLayout::blockBoundingRect(const QTextBlock &block) const | |
Returns the bounding rectangle of \a block. | |
*/ | |
/*! | |
Sets the paint device used for rendering the document's layout to the given | |
\a device. | |
\sa paintDevice() | |
*/ | |
void QAbstractTextDocumentLayout::setPaintDevice(QPaintDevice *device) | |
{ | |
Q_D(QAbstractTextDocumentLayout); | |
d->paintDevice = device; | |
} | |
/*! | |
Returns the paint device used to render the document's layout. | |
\sa setPaintDevice() | |
*/ | |
QPaintDevice *QAbstractTextDocumentLayout::paintDevice() const | |
{ | |
Q_D(const QAbstractTextDocumentLayout); | |
return d->paintDevice; | |
} | |
QT_END_NAMESPACE | |
#include "moc_qabstracttextdocumentlayout.cpp" |