f9f395c28b
Updated version of LGPL and FDL licenseheaders. Apply release phase licenseheaders for all source files. Reviewed-by: Trust Me
624 lines
20 KiB
C++
624 lines
20 KiB
C++
/****************************************************************************
|
|
**
|
|
** 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"
|