/****************************************************************************
**
** Copyright (C) 2009 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$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Lesser General Public License Usage
** Alternatively, 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
**
**
**
**
**
**
**
**
** $QT_END_LICENSE$
**
****************************************************************************/
#include "qtextobject.h"
#include "qtextobject_p.h"
#include "qtextdocument.h"
#include "qtextformat_p.h"
#include "qtextdocument_p.h"
#include "qtextcursor.h"
#include "qtextlist.h"
#include "qabstracttextdocumentlayout.h"
#include "qtextengine_p.h"
#include "qdebug.h"
QT_BEGIN_NAMESPACE
// ### DOC: We ought to explain the CONCEPT of objectIndexes if
// relevant to the public API
/*!
\class QTextObject
\reentrant
\brief The QTextObject class is a base class for different kinds
of objects that can group parts of a QTextDocument together.
\ingroup richtext-processing
The common grouping text objects are lists (QTextList), frames
(QTextFrame), and tables (QTextTable). A text object has an
associated format() and document().
There are essentially two kinds of text objects: those that are used
with blocks (block formats), and those that are used with characters
(character formats). The first kind are derived from QTextBlockGroup,
and the second kind from QTextFrame.
You rarely need to use this class directly. When creating custom text
objects, you will also need to reimplement QTextDocument::createObject()
which acts as a factory method for creating text objects.
\sa QTextDocument, {Text Object Example}
*/
/*!
\fn QTextObject::QTextObject(QTextDocument *document)
Creates a new QTextObject for the given \a document.
\warning This function should never be called directly, but only
from QTextDocument::createObject().
*/
QTextObject::QTextObject(QTextDocument *doc)
: QObject(*new QTextObjectPrivate(doc), doc)
{
}
/*!
\fn QTextObject::QTextObject(QTextObjectPrivate &p, QTextDocument *document)
\internal
*/
QTextObject::QTextObject(QTextObjectPrivate &p, QTextDocument *doc)
: QObject(p, doc)
{
}
/*!
Destroys the text object.
\warning Text objects are owned by the document, so you should
never destroy them yourself.
*/
QTextObject::~QTextObject()
{
}
/*!
Returns the text object's format.
\sa setFormat() document()
*/
QTextFormat QTextObject::format() const
{
Q_D(const QTextObject);
return d->pieceTable->formatCollection()->objectFormat(d->objectIndex);
}
/*!
Returns the index of the object's format in the document's internal
list of formats.
\sa QTextDocument::allFormats()
*/
int QTextObject::formatIndex() const
{
Q_D(const QTextObject);
return d->pieceTable->formatCollection()->objectFormatIndex(d->objectIndex);
}
/*!
Sets the text object's \a format.
\sa format()
*/
void QTextObject::setFormat(const QTextFormat &format)
{
Q_D(QTextObject);
int idx = d->pieceTable->formatCollection()->indexForFormat(format);
d->pieceTable->changeObjectFormat(this, idx);
}
/*!
Returns the object index of this object. This can be used together with
QTextFormat::setObjectIndex().
*/
int QTextObject::objectIndex() const
{
Q_D(const QTextObject);
return d->objectIndex;
}
/*!
Returns the document this object belongs to.
\sa format()
*/
QTextDocument *QTextObject::document() const
{
return static_cast<QTextDocument *>(parent());
}
/*!
\internal
*/
QTextDocumentPrivate *QTextObject::docHandle() const
{
return static_cast<const QTextDocument *>(parent())->docHandle();
}
/*!
\class QTextBlockGroup
\reentrant
\brief The QTextBlockGroup class provides a container for text blocks within
a QTextDocument.
\ingroup richtext-processing
Block groups can be used to organize blocks of text within a document.
They maintain an up-to-date list of the text blocks that belong to
them, even when text blocks are being edited.
Each group has a parent document which is specified when the group is
constructed.
Text blocks can be inserted into a group with blockInserted(), and removed
with blockRemoved(). If a block's format is changed, blockFormatChanged()
is called.
The list of blocks in the group is returned by blockList(). Note that the
blocks in the list are not necessarily adjacent elements in the document;
for example, the top-level items in a multi-level list will be separated
by the items in lower levels of the list.
\sa QTextBlock QTextDocument
*/
void QTextBlockGroupPrivate::markBlocksDirty()
{
for (int i = 0; i < blocks.count(); ++i) {
const QTextBlock &block = blocks.at(i);
pieceTable->documentChange(block.position(), block.length());
}
}
/*!
\fn QTextBlockGroup::QTextBlockGroup(QTextDocument *document)
Creates a new new block group for the given \a document.
\warning This function should only be called from
QTextDocument::createObject().
*/
QTextBlockGroup::QTextBlockGroup(QTextDocument *doc)
: QTextObject(*new QTextBlockGroupPrivate(doc), doc)
{
}
/*!
\internal
*/
QTextBlockGroup::QTextBlockGroup(QTextBlockGroupPrivate &p, QTextDocument *doc)
: QTextObject(p, doc)
{
}
/*!
Destroys this block group; the blocks are not deleted, they simply
don't belong to this block anymore.
*/
QTextBlockGroup::~QTextBlockGroup()
{
}
// ### DOC: Shouldn't this be insertBlock()?
/*!
Appends the given \a block to the end of the group.
\warning If you reimplement this function you must call the base
class implementation.
*/
void QTextBlockGroup::blockInserted(const QTextBlock &block)
{
Q_D(QTextBlockGroup);
QTextBlockGroupPrivate::BlockList::Iterator it = qLowerBound(d->blocks.begin(), d->blocks.end(), block);
d->blocks.insert(it, block);
d->markBlocksDirty();
}
// ### DOC: Shouldn't this be removeBlock()?
/*!
Removes the given \a block from the group; the block itself is not
deleted, it simply isn't a member of this group anymore.
*/
void QTextBlockGroup::blockRemoved(const QTextBlock &block)
{
Q_D(QTextBlockGroup);
d->blocks.removeAll(block);
d->markBlocksDirty();
if (d->blocks.isEmpty()) {
document()->docHandle()->deleteObject(this);
return;
}
}
/*!
This function is called whenever the specified \a block of text is changed.
The text block is a member of this group.
The base class implementation does nothing.
*/
void QTextBlockGroup::blockFormatChanged(const QTextBlock &)
{
}
/*!
Returns a (possibly empty) list of all the blocks that are part of
the block group.
*/
QList<QTextBlock> QTextBlockGroup::blockList() const
{
Q_D(const QTextBlockGroup);
return d->blocks;
}
QTextFrameLayoutData::~QTextFrameLayoutData()
{
}
/*!
\class QTextFrame
\reentrant
\brief The QTextFrame class represents a frame in a QTextDocument.
\ingroup richtext-processing
Text frames provide structure for the text in a document. They are used
as generic containers for other document elements.
Frames are usually created by using QTextCursor::insertFrame().
\omit
Each frame in a document consists of a frame start character,
QChar(0xFDD0), followed by the frame's contents, followed by a
frame end character, QChar(0xFDD1). The character formats of the
start and end character contain a reference to the frame object's
objectIndex.
\endomit
Frames can be used to create hierarchical structures in rich text documents.
Each document has a root frame (QTextDocument::rootFrame()), and each frame
beneath the root frame has a parent frame and a (possibly empty) list of
child frames. The parent frame can be found with parentFrame(), and the
childFrames() function provides a list of child frames.
Each frame contains at least one text block to enable text cursors to
insert new document elements within. As a result, the QTextFrame::iterator
class is used to traverse both the blocks and child frames within a given
frame. The first and last child elements in the frame can be found with
begin() and end().
A frame also has a format (specified using QTextFrameFormat) which can be set
with setFormat() and read with format().
Text cursors can be obtained that point to the first and last valid cursor
positions within a frame; use the firstCursorPosition() and
lastCursorPosition() functions for this. The frame's extent in the
document can be found with firstPosition() and lastPosition().
You can iterate over a frame's contents using the
QTextFrame::iterator class: this provides read-only access to its
internal list of text blocks and child frames.
\sa QTextCursor QTextDocument
*/
/*!
\typedef QTextFrame::Iterator
Qt-style synonym for QTextFrame::iterator.
*/
/*!
\fn QTextFrame *QTextFrame::iterator::parentFrame() const
Returns the parent frame of the current frame.
\sa currentFrame() QTextFrame::parentFrame()
*/
/*!
\fn bool QTextFrame::iterator::operator==(const iterator &other) const
Retuns true if the iterator is the same as the \a other iterator;
otherwise returns false.
*/
/*!
\fn bool QTextFrame::iterator::operator!=(const iterator &other) const
Retuns true if the iterator is different from the \a other iterator;
otherwise returns false.
*/
/*!
\fn QTextFrame::iterator QTextFrame::iterator::operator++(int)
The postfix ++ operator (\c{i++}) advances the iterator to the
next item in the text frame, and returns an iterator to the old item.
*/
/*!
\fn QTextFrame::iterator QTextFrame::iterator::operator--(int)
The postfix -- operator (\c{i--}) makes the preceding item in the
current frame, and returns an iterator to the old item.
*/
/*!
\fn void QTextFrame::setFrameFormat(const QTextFrameFormat &format)
Sets the frame's \a format.
\sa frameFormat()
*/
/*!
\fn QTextFrameFormat QTextFrame::frameFormat() const
Returns the frame's format.
\sa setFrameFormat()
*/
/*!
\fn QTextFrame::QTextFrame(QTextDocument *document)
Creates a new empty frame for the text \a document.
*/
QTextFrame::QTextFrame(QTextDocument *doc)
: QTextObject(*new QTextFramePrivate(doc), doc)
{
}
// ### DOC: What does this do to child frames?
/*!
Destroys the frame, and removes it from the document's layout.
*/
QTextFrame::~QTextFrame()
{
Q_D(QTextFrame);
delete d->layoutData;
}
/*!
\internal
*/
QTextFrame::QTextFrame(QTextFramePrivate &p, QTextDocument *doc)
: QTextObject(p, doc)
{
}
/*!
Returns a (possibly empty) list of the frame's child frames.
\sa parentFrame()
*/
QList<QTextFrame *> QTextFrame::childFrames() const
{
Q_D(const QTextFrame);
return d->childFrames;
}
/*!
Returns the frame's parent frame. If the frame is the root frame of a
document, this will return 0.
\sa childFrames() QTextDocument::rootFrame()
*/
QTextFrame *QTextFrame::parentFrame() const
{
Q_D(const QTextFrame);
return d->parentFrame;
}
/*!
Returns the first cursor position inside the frame.
\sa lastCursorPosition() firstPosition() lastPosition()
*/
QTextCursor QTextFrame::firstCursorPosition() const
{
Q_D(const QTextFrame);
return QTextCursor(d->pieceTable, firstPosition());
}
/*!
Returns the last cursor position inside the frame.
\sa firstCursorPosition() firstPosition() lastPosition()
*/
QTextCursor QTextFrame::lastCursorPosition() const
{
Q_D(const QTextFrame);
return QTextCursor(d->pieceTable, lastPosition());
}
/*!
Returns the first document position inside the frame.
\sa lastPosition() firstCursorPosition() lastCursorPosition()
*/
int QTextFrame::firstPosition() const
{
Q_D(const QTextFrame);
if (!d->fragment_start)
return 0;
return d->pieceTable->fragmentMap().position(d->fragment_start) + 1;
}
/*!
Returns the last document position inside the frame.
\sa firstPosition() firstCursorPosition() lastCursorPosition()
*/
int QTextFrame::lastPosition() const
{
Q_D(const QTextFrame);
if (!d->fragment_end)
return d->pieceTable->length() - 1;
return d->pieceTable->fragmentMap().position(d->fragment_end);
}
/*!
\internal
*/
QTextFrameLayoutData *QTextFrame::layoutData() const
{
Q_D(const QTextFrame);
return d->layoutData;
}
/*!
\internal
*/
void QTextFrame::setLayoutData(QTextFrameLayoutData *data)
{
Q_D(QTextFrame);
delete d->layoutData;
d->layoutData = data;
}
void QTextFramePrivate::fragmentAdded(const QChar &type, uint fragment)
{
if (type == QTextBeginningOfFrame) {
Q_ASSERT(!fragment_start);
fragment_start = fragment;
} else if (type == QTextEndOfFrame) {
Q_ASSERT(!fragment_end);
fragment_end = fragment;
} else if (type == QChar::ObjectReplacementCharacter) {
Q_ASSERT(!fragment_start);
Q_ASSERT(!fragment_end);
fragment_start = fragment;
fragment_end = fragment;
} else {
Q_ASSERT(false);
}
}
void QTextFramePrivate::fragmentRemoved(const QChar &type, uint fragment)
{
Q_UNUSED(fragment); // --release warning
if (type == QTextBeginningOfFrame) {
Q_ASSERT(fragment_start == fragment);
fragment_start = 0;
} else if (type == QTextEndOfFrame) {
Q_ASSERT(fragment_end == fragment);
fragment_end = 0;
} else if (type == QChar::ObjectReplacementCharacter) {
Q_ASSERT(fragment_start == fragment);
Q_ASSERT(fragment_end == fragment);
fragment_start = 0;
fragment_end = 0;
} else {
Q_ASSERT(false);
}
remove_me();
}
void QTextFramePrivate::remove_me()
{
Q_Q(QTextFrame);
if (fragment_start == 0 && fragment_end == 0
&& !parentFrame) {
q->document()->docHandle()->deleteObject(q);
return;
}
if (!parentFrame)
return;
int index = parentFrame->d_func()->childFrames.indexOf(q);
// iterator over all children and move them to the parent
for (int i = 0; i < childFrames.size(); ++i) {
QTextFrame *c = childFrames.at(i);
parentFrame->d_func()->childFrames.insert(index, c);
c->d_func()->parentFrame = parentFrame;
++index;
}
Q_ASSERT(parentFrame->d_func()->childFrames.at(index) == q);
parentFrame->d_func()->childFrames.removeAt(index);
childFrames.clear();
parentFrame = 0;
}
/*!
\class QTextFrame::iterator
\reentrant
\brief The iterator class provides an iterator for reading
the contents of a QTextFrame.
\ingroup richtext-processing
A frame consists of an arbitrary sequence of \l{QTextBlock}s and
child \l{QTextFrame}s. This class provides a way to iterate over the
child objects of a frame, and read their contents. It does not provide
a way to modify the contents of the frame.
*/
/*!
\fn bool QTextFrame::iterator::atEnd() const
Returns true if the current item is the last item in the text frame.
*/
/*!
Returns an iterator pointing to the first document element inside the frame.
\sa end()
*/
QTextFrame::iterator QTextFrame::begin() const
{
const QTextDocumentPrivate *priv = docHandle();
int b = priv->blockMap().findNode(firstPosition());
int e = priv->blockMap().findNode(lastPosition()+1);
return iterator(const_cast<QTextFrame *>(this), b, b, e);
}
/*!
Returns an iterator pointing to the last document element inside the frame.
\sa begin()
*/
QTextFrame::iterator QTextFrame::end() const
{
const QTextDocumentPrivate *priv = docHandle();
int b = priv->blockMap().findNode(firstPosition());
int e = priv->blockMap().findNode(lastPosition()+1);
return iterator(const_cast<QTextFrame *>(this), e, b, e);
}
/*!
Constructs an invalid iterator.
*/
QTextFrame::iterator::iterator()
{
f = 0;
b = 0;
e = 0;
cf = 0;
cb = 0;
}
/*!
\internal
*/
QTextFrame::iterator::iterator(QTextFrame *frame, int block, int begin, int end)
{
f = frame;
b = begin;
e = end;
cf = 0;
cb = block;
}
/*!
Copy constructor. Constructs a copy of the \a other iterator.
*/
QTextFrame::iterator::iterator(const iterator &other)
{
f = other.f;
b = other.b;
e = other.e;
cf = other.cf;
cb = other.cb;
}
/*!
Assigns \a other to this iterator and returns a reference to
this iterator.
*/
QTextFrame::iterator &QTextFrame::iterator::operator=(const iterator &other)
{
f = other.f;
b = other.b;
e = other.e;
cf = other.cf;
cb = other.cb;
return *this;
}
/*!
Returns the current frame pointed to by the iterator, or 0 if the
iterator currently points to a block.
\sa currentBlock()
*/
QTextFrame *QTextFrame::iterator::currentFrame() const
{
return cf;
}
/*!
Returns the current block the iterator points to. If the iterator
points to a child frame, the returned block is invalid.
\sa currentFrame()
*/
QTextBlock QTextFrame::iterator::currentBlock() const
{
if (!f)
return QTextBlock();
return QTextBlock(f->docHandle(), cb);
}
/*!
Moves the iterator to the next frame or block.
\sa currentBlock() currentFrame()
*/
QTextFrame::iterator &QTextFrame::iterator::operator++()
{
const QTextDocumentPrivate *priv = f->docHandle();
const QTextDocumentPrivate::BlockMap &map = priv->blockMap();
if (cf) {
int end = cf->lastPosition() + 1;
cb = map.findNode(end);
cf = 0;
} else if (cb) {
cb = map.next(cb);
if (cb == e)
return *this;
if (!f->d_func()->childFrames.isEmpty()) {
int pos = map.position(cb);
// check if we entered a frame
QTextDocumentPrivate::FragmentIterator frag = priv->find(pos-1);
if (priv->buffer().at(frag->stringPosition) != QChar::ParagraphSeparator) {
QTextFrame *nf = qobject_cast<QTextFrame *>(priv->objectForFormat(frag->format));
if (nf) {
if (priv->buffer().at(frag->stringPosition) == QTextBeginningOfFrame && nf != f) {
cf = nf;
cb = 0;
} else {
Q_ASSERT(priv->buffer().at(frag->stringPosition) != QTextEndOfFrame);
}
}
}
}
}
return *this;
}
/*!
Moves the iterator to the previous frame or block.
\sa currentBlock() currentFrame()
*/
QTextFrame::iterator &QTextFrame::iterator::operator--()
{
const QTextDocumentPrivate *priv = f->docHandle();
const QTextDocumentPrivate::BlockMap &map = priv->blockMap();
if (cf) {
int start = cf->firstPosition() - 1;
cb = map.findNode(start);
cf = 0;
} else {
if (cb == b)
goto end;
if (cb != e) {
int pos = map.position(cb);
// check if we have to enter a frame
QTextDocumentPrivate::FragmentIterator frag = priv->find(pos-1);
if (priv->buffer().at(frag->stringPosition) != QChar::ParagraphSeparator) {
QTextFrame *pf = qobject_cast<QTextFrame *>(priv->objectForFormat(frag->format));
if (pf) {
if (priv->buffer().at(frag->stringPosition) == QTextBeginningOfFrame) {
Q_ASSERT(pf == f);
} else if (priv->buffer().at(frag->stringPosition) == QTextEndOfFrame) {
Q_ASSERT(pf != f);
cf = pf;
cb = 0;
goto end;
}
}
}
}
cb = map.previous(cb);
}
end:
return *this;
}
/*!
\class QTextBlockUserData
\reentrant
\brief The QTextBlockUserData class is used to associate custom data with blocks of text.
\since 4.1
\ingroup richtext-processing
QTextBlockUserData provides an abstract interface for container classes that are used
to associate application-specific user data with text blocks in a QTextDocument.
Generally, subclasses of this class provide functions to allow data to be stored
and retrieved, and instances are attached to blocks of text using
QTextBlock::setUserData(). This makes it possible to store additional data per text
block in a way that can be retrieved safely by the application.
Each subclass should provide a reimplementation of the destructor to ensure that any
private data is automatically cleaned up when user data objects are deleted.
\sa QTextBlock
*/
/*!
Destroys the user data.
*/
QTextBlockUserData::~QTextBlockUserData()
{
}
/*!
\class QTextBlock
\reentrant
\brief The QTextBlock class provides a container for text fragments in a
QTextDocument.
\ingroup richtext-processing
A text block encapsulates a block or paragraph of text in a QTextDocument.
QTextBlock provides read-only access to the block/paragraph structure of
QTextDocuments. It is mainly of use if you want to implement your own
layouts for the visual representation of a QTextDocument, or if you want to
iterate over a document and write out the contents in your own custom
format.
Text blocks are created by their parent documents. If you need to create
a new text block, or modify the contents of a document while examining its
contents, use the cursor-based interface provided by QTextCursor instead.
Each text block is located at a specific position() in a document().
The contents of the block can be obtained by using the text() function.
The length() function determines the block's size within the document
(including formatting characters).
The visual properties of the block are determined by its text layout(),
its charFormat(), and its blockFormat().
The next() and previous() functions enable iteration over consecutive
valid blocks in a document under the condition that the document is not
modified by other means during the iteration process. Note that, although
blocks are returned in sequence, adjacent blocks may come from different
places in the document structure. The validity of a block can be determined
by calling isValid().
QTextBlock provides comparison operators to make it easier to work with
blocks: \l operator==() compares two block for equality, \l operator!=()
compares two blocks for inequality, and \l operator<() determines whether
a block precedes another in the same document.
\img qtextblock-sequence.png
\sa QTextBlockFormat QTextCharFormat QTextFragment
*/
/*!
\fn QTextBlock::QTextBlock(QTextDocumentPrivate *priv, int b)
\internal
*/
/*!
\fn QTextBlock::QTextBlock()
\internal
*/
/*!
\fn QTextBlock::QTextBlock(const QTextBlock &other)
Copies the \a other text block's attributes to this text block.
*/
/*!
\fn bool QTextBlock::isValid() const
Returns true if this text block is valid; otherwise returns false.
*/
/*!
\fn QTextBlock &QTextBlock::operator=(const QTextBlock &other)
Assigns the \a other text block to this text block.
*/
/*!
\fn bool QTextBlock::operator==(const QTextBlock &other) const
Returns true if this text block is the same as the \a other text
block.
*/
/*!
\fn bool QTextBlock::operator!=(const QTextBlock &other) const
Returns true if this text block is different from the \a other
text block.
*/
/*!
\fn bool QTextBlock::operator<(const QTextBlock &other) const
Returns true if this text block occurs before the \a other text
block in the document.
*/
/*!
\class QTextBlock::iterator
\reentrant
\brief The QTextBlock::iterator class provides an iterator for reading
the contents of a QTextBlock.
\ingroup richtext-processing
A block consists of a sequence of text fragments. This class provides
a way to iterate over these, and read their contents. It does not provide
a way to modify the internal structure or contents of the block.
An iterator can be constructed and used to access the fragments within
a text block in the following way:
\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 4
\snippet doc/src/snippets/textblock-fragments/xmlwriter.cpp 7
\sa QTextFragment
*/
/*!
\typedef QTextBlock::Iterator
Qt-style synonym for QTextBlock::iterator.
*/
/*!
\fn QTextBlock::iterator::iterator()
Constructs an iterator for this text block.
*/
/*!
\fn QTextBlock::iterator::iterator(const iterator &other)
Copy constructor. Constructs a copy of the \a other iterator.
*/
/*!
\fn bool QTextBlock::iterator::atEnd() const
Returns true if the current item is the last item in the text block.
*/
/*!
\fn bool QTextBlock::iterator::operator==(const iterator &other) const
Retuns true if this iterator is the same as the \a other iterator;
otherwise returns false.
*/
/*!
\fn bool QTextBlock::iterator::operator!=(const iterator &other) const
Retuns true if this iterator is different from the \a other iterator;
otherwise returns false.
*/
/*!
\fn QTextBlock::iterator QTextBlock::iterator::operator++(int)
The postfix ++ operator (\c{i++}) advances the iterator to the
next item in the text block and returns an iterator to the old current
item.
*/
/*!
\fn QTextBlock::iterator QTextBlock::iterator::operator--(int)
The postfix -- operator (\c{i--}) makes the preceding item current and
returns an iterator to the old current item.
*/
/*!
\fn QTextDocumentPrivate *QTextBlock::docHandle() const
\internal
*/
/*!
\fn int QTextBlock::fragmentIndex() const
\internal
*/
/*!
Returns the index of the block's first character within the document.
*/
int QTextBlock::position() const
{
if (!p || !n)
return 0;
return p->blockMap().position(n);
}
/*!
Returns the length of the block in characters.
\note The length returned includes all formatting characters,
for example, newline.
\sa text() charFormat() blockFormat()
*/
int QTextBlock::length() const
{
if (!p || !n)
return 0;
return p->blockMap().size(n);
}
/*!
Returns true if the given \a position is located within the text
block; otherwise returns false.
*/
bool QTextBlock::contains(int position) const
{
if (!p || !n)
return false;
int pos = p->blockMap().position(n);
int len = p->blockMap().size(n);
return position >= pos && position < pos + len;
}
/*!
Returns the QTextLayout that is used to lay out and display the
block's contents.
Note that the returned QTextLayout object can only be modified from the
documentChanged implementation of a QAbstractTextDocumentLayout subclass.
Any changes applied from the outside cause undefined behavior.
\sa clearLayout()
*/
QTextLayout *QTextBlock::layout() const
{
if (!p || !n)
return 0;
const QTextBlockData *b = p->blockMap().fragment(n);
if (!b->layout)
b->layout = new QTextLayout(*this);
return b->layout;
}
/*!
\since 4.4
Clears the QTextLayout that is used to lay out and display the
block's contents.
\sa layout()
*/
void QTextBlock::clearLayout()
{
if (!p || !n)
return;
const QTextBlockData *b = p->blockMap().fragment(n);
if (b->layout)
b->layout->clearLayout();
}
/*!
Returns the QTextBlockFormat that describes block-specific properties.
\sa charFormat()
*/
QTextBlockFormat QTextBlock::blockFormat() const
{
if (!p || !n)
return QTextFormat().toBlockFormat();
return p->formatCollection()->blockFormat(p->blockMap().fragment(n)->format);
}
/*!
Returns an index into the document's internal list of block formats
for the text block's format.
\sa QTextDocument::allFormats()
*/
int QTextBlock::blockFormatIndex() const
{
if (!p || !n)
return -1;
return p->blockMap().fragment(n)->format;
}
/*!
Returns the QTextCharFormat that describes the block's character
format. The block's character format is used when inserting text into
an empty block.
\sa blockFormat()
*/
QTextCharFormat QTextBlock::charFormat() const
{
if (!p || !n)
return QTextFormat().toCharFormat();
return p->formatCollection()->charFormat(charFormatIndex());
}
/*!
Returns an index into the document's internal list of character formats
for the text block's character format.
\sa QTextDocument::allFormats()
*/
int QTextBlock::charFormatIndex() const
{
if (!p || !n)
return -1;
return p->blockCharFormatIndex(n);
}
/*!
Returns the block's contents as plain text.
\sa length() charFormat() blockFormat()
*/
QString QTextBlock::text() const
{
if (!p || !n)
return QString();
const QString buffer = p->buffer();
QString text;
text.reserve(length());
const int pos = position();
QTextDocumentPrivate::FragmentIterator it = p->find(pos);
QTextDocumentPrivate::FragmentIterator end = p->find(pos + length() - 1); // -1 to omit the block separator char
for (; it != end; ++it) {
const QTextFragmentData * const frag = it.value();
text += QString::fromRawData(buffer.constData() + frag->stringPosition, frag->size_array[0]);
}
return text;
}
/*!
Returns the text document this text block belongs to, or 0 if the
text block does not belong to any document.
*/
const QTextDocument *QTextBlock::document() const
{
return p ? p->document() : 0;
}
/*!
If the block represents a list item, returns the list that the item belongs
to; otherwise returns 0.
*/
QTextList *QTextBlock::textList() const
{
if (!isValid())
return 0;
const QTextBlockFormat fmt = blockFormat();
QTextObject *obj = p->document()->objectForFormat(fmt);
return qobject_cast<QTextList *>(obj);
}
/*!
\since 4.1
Returns a pointer to a QTextBlockUserData object if previously set with
setUserData() or a null pointer.
*/
QTextBlockUserData *QTextBlock::userData() const
{
if (!p || !n)
return 0;
const QTextBlockData *b = p->blockMap().fragment(n);
return b->userData;
}
/*!
\since 4.1
Attaches the given \a data object to the text block.
QTextBlockUserData can be used to store custom settings. The
ownership is passed to the underlying text document, i.e. the
provided QTextBlockUserData object will be deleted if the
corresponding text block gets deleted. The user data object is
not stored in the undo history, so it will not be available after
undoing the deletion of a text block.
For example, if you write a programming editor in an IDE, you may
want to let your user set breakpoints visually in your code for an
integrated debugger. In a programming editor a line of text
usually corresponds to one QTextBlock. The QTextBlockUserData
interface allows the developer to store data for each QTextBlock,
like for example in which lines of the source code the user has a
breakpoint set. Of course this could also be stored externally,
but by storing it inside the QTextDocument, it will for example be
automatically deleted when the user deletes the associated
line. It's really just a way to store custom information in the
QTextDocument without using custom properties in QTextFormat which
would affect the undo/redo stack.
*/
void QTextBlock::setUserData(QTextBlockUserData *data)
{
if (!p || !n)
return;
const QTextBlockData *b = p->blockMap().fragment(n);
if (data != b->userData)
delete b->userData;
b->userData = data;
}
/*!
\since 4.1
Returns the integer value previously set with setUserState() or -1.
*/
int QTextBlock::userState() const
{
if (!p || !n)
return -1;
const QTextBlockData *b = p->blockMap().fragment(n);
return b->userState;
}
/*!
\since 4.1
Stores the specified \a state integer value in the text block. This may be
useful for example in a syntax highlighter to store a text parsing state.
*/
void QTextBlock::setUserState(int state)
{
if (!p || !n)
return;
const QTextBlockData *b = p->blockMap().fragment(n);
b->userState = state;
}
/*!
\since 4.4
Returns the blocks revision.
\sa setRevision(), QTextDocument::revision()
*/
int QTextBlock::revision() const
{
if (!p || !n)
return -1;
const QTextBlockData *b = p->blockMap().fragment(n);
return b->revision;
}
/*!
\since 4.4
Sets a blocks revision to \a rev.
\sa revision(), QTextDocument::revision()
*/
void QTextBlock::setRevision(int rev)
{
if (!p || !n)
return;
const QTextBlockData *b = p->blockMap().fragment(n);
b->revision = rev;
}
/*!
\since 4.4
Returns true if the block is visible; otherwise returns false.
\sa setVisible()
*/
bool QTextBlock::isVisible() const
{
if (!p || !n)
return true;
const QTextBlockData *b = p->blockMap().fragment(n);
return !b->hidden;
}
/*!
\since 4.4
Sets the block's visibility to \a visible.
\sa isVisible()
*/
void QTextBlock::setVisible(bool visible)
{
if (!p || !n)
return;
const QTextBlockData *b = p->blockMap().fragment(n);
b->hidden = !visible;
}
/*!
\since 4.4
Returns the number of this block, or -1 if the block is invalid.
\sa QTextCursor::blockNumber()
*/
int QTextBlock::blockNumber() const
{
if (!p || !n)
return -1;
return p->blockMap().position(n, 1);
}
/*!
\since 4.5
Returns the first line number of this block, or -1 if the block is invalid.
Unless the layout supports it, the line number is identical to the block number.
\sa QTextBlock::blockNumber()
*/
int QTextBlock::firstLineNumber() const
{
if (!p || !n)
return -1;
return p->blockMap().position(n, 2);
}
/*!
\since 4.5
Sets the line count to \a count.
\sa lineCount()
*/
void QTextBlock::setLineCount(int count)
{
if (!p || !n)
return;
p->blockMap().setSize(n, count, 2);
}
/*!
\since 4.5
Returns the line count. Not all document layouts support this feature.
\sa setLineCount()
*/
int QTextBlock::lineCount() const
{
if (!p || !n)
return -1;
return p->blockMap().size(n, 2);
}
/*!
Returns a text block iterator pointing to the beginning of the
text block.
\sa end()
*/
QTextBlock::iterator QTextBlock::begin() const
{
if (!p || !n)
return iterator();
int pos = position();
int len = length() - 1; // exclude the fragment that holds the paragraph separator
int b = p->fragmentMap().findNode(pos);
int e = p->fragmentMap().findNode(pos+len);
return iterator(p, b, e, b);
}
/*!
Returns a text block iterator pointing to the end of the text
block.
\sa begin() next() previous()
*/
QTextBlock::iterator QTextBlock::end() const
{
if (!p || !n)
return iterator();
int pos = position();
int len = length() - 1; // exclude the fragment that holds the paragraph separator
int b = p->fragmentMap().findNode(pos);
int e = p->fragmentMap().findNode(pos+len);
return iterator(p, b, e, e);
}
/*!
Returns the text block in the document after this block, or an empty
text block if this is the last one.
Note that the next block may be in a different frame or table to this block.
\sa previous() begin() end()
*/
QTextBlock QTextBlock::next() const
{
if (!p)
return QTextBlock();
return QTextBlock(p, p->blockMap().next(n));
}
/*!
Returns the text block in the document before this block, or an empty text
block if this is the first one.
Note that the next block may be in a different frame or table to this block.
\sa next() begin() end()
*/
QTextBlock QTextBlock::previous() const
{
if (!p)
return QTextBlock();
return QTextBlock(p, p->blockMap().previous(n));
}
/*!
Returns the text fragment the iterator currently points to.
*/
QTextFragment QTextBlock::iterator::fragment() const
{
int ne = n;
int formatIndex = p->fragmentMap().fragment(n)->format;
do {
ne = p->fragmentMap().next(ne);
} while (ne != e && p->fragmentMap().fragment(ne)->format == formatIndex);
return QTextFragment(p, n, ne);
}
/*!
The prefix ++ operator (\c{++i}) advances the iterator to the
next item in the hash and returns an iterator to the new current
item.
*/
QTextBlock::iterator &QTextBlock::iterator::operator++()
{
int ne = n;
int formatIndex = p->fragmentMap().fragment(n)->format;
do {
ne = p->fragmentMap().next(ne);
} while (ne != e && p->fragmentMap().fragment(ne)->format == formatIndex);
n = ne;
return *this;
}
/*!
The prefix -- operator (\c{--i}) makes the preceding item
current and returns an iterator pointing to the new current item.
*/
QTextBlock::iterator &QTextBlock::iterator::operator--()
{
n = p->fragmentMap().previous(n);
if (n == b)
return *this;
int formatIndex = p->fragmentMap().fragment(n)->format;
int last = n;
while (n != b && p->fragmentMap().fragment(n)->format != formatIndex) {
last = n;
n = p->fragmentMap().previous(n);
}
n = last;
return *this;
}
/*!
\class QTextFragment
\reentrant
\brief The QTextFragment class holds a piece of text in a
QTextDocument with a single QTextCharFormat.
\ingroup richtext-processing
A text fragment describes a piece of text that is stored with a single
character format. Text in which the character format changes can be
represented by sequences of text fragments with different formats.
If the user edits the text in a fragment and introduces a different
character format, the fragment's text will be split at each point where
the format changes, and new fragments will be created.
For example, changing the style of some text in the middle of a
sentence will cause the fragment to be broken into three separate fragments:
the first and third with the same format as before, and the second with
the new style. The first fragment will contain the text from the beginning
of the sentence, the second will contain the text from the middle, and the
third takes the text from the end of the sentence.
\img qtextfragment-split.png
A fragment's text and character format can be obtained with the text()
and charFormat() functions. The length() function gives the length of
the text in the fragment. position() gives the position in the document
of the start of the fragment. To determine whether the fragment contains
a particular position within the document, use the contains() function.
\sa QTextDocument, {Rich Text Document Structure}
*/
/*!
\fn QTextFragment::QTextFragment(const QTextDocumentPrivate *priv, int f, int fe)
\internal
*/
/*!
\fn QTextFragment::QTextFragment()
Creates a new empty text fragment.
*/
/*!
\fn QTextFragment::QTextFragment(const QTextFragment &other)
Copies the content (text and format) of the \a other text fragment
to this text fragment.
*/
/*!
\fn QTextFragment &QTextFragment::operator=(const QTextFragment
&other)
Assigns the content (text and format) of the \a other text fragment
to this text fragment.
*/
/*!
\fn bool QTextFragment::isValid() const
Returns true if this is a valid text fragment (i.e. has a valid
position in a document); otherwise returns false.
*/
/*!
\fn bool QTextFragment::operator==(const QTextFragment &other) const
Returns true if this text fragment is the same (at the same
position) as the \a other text fragment; otherwise returns false.
*/
/*!
\fn bool QTextFragment::operator!=(const QTextFragment &other) const
Returns true if this text fragment is different (at a different
position) from the \a other text fragment; otherwise returns
false.
*/
/*!
\fn bool QTextFragment::operator<(const QTextFragment &other) const
Returns true if this text fragment appears earlier in the document
than the \a other text fragment; otherwise returns false.
*/
/*!
Returns the position of this text fragment in the document.
*/
int QTextFragment::position() const
{
if (!p || !n)
return 0; // ### -1 instead?
return p->fragmentMap().position(n);
}
/*!
Returns the number of characters in the text fragment.
\sa text()
*/
int QTextFragment::length() const
{
if (!p || !n)
return 0;
int len = 0;
int f = n;
while (f != ne) {
len += p->fragmentMap().size(f);
f = p->fragmentMap().next(f);
}
return len;
}
/*!
Returns true if the text fragment contains the text at the given
\a position in the document; otherwise returns false.
*/
bool QTextFragment::contains(int position) const
{
if (!p || !n)
return false;
int pos = this->position();
return position >= pos && position < pos + length();
}
/*!
Returns the text fragment's character format.
\sa text()
*/
QTextCharFormat QTextFragment::charFormat() const
{
if (!p || !n)
return QTextCharFormat();
const QTextFragmentData *data = p->fragmentMap().fragment(n);
return p->formatCollection()->charFormat(data->format);
}
/*!
Returns an index into the document's internal list of character formats
for the text fragment's character format.
\sa QTextDocument::allFormats()
*/
int QTextFragment::charFormatIndex() const
{
if (!p || !n)
return -1;
const QTextFragmentData *data = p->fragmentMap().fragment(n);
return data->format;
}
/*!
Returns the text fragment's as plain text.
\sa length(), charFormat()
*/
QString QTextFragment::text() const
{
if (!p || !n)
return QString();
QString result;
QString buffer = p->buffer();
int f = n;
while (f != ne) {
const QTextFragmentData * const frag = p->fragmentMap().fragment(f);
result += QString(buffer.constData() + frag->stringPosition, frag->size_array[0]);
f = p->fragmentMap().next(f);
}
return result;
}
QT_END_NAMESPACE