--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/gui/text/qtextobject.cpp Mon Jan 11 14:00:40 2010 +0000
@@ -0,0 +1,1701 @@
+/****************************************************************************
+**
+** 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