Contents

• Public Types
• Public Functions
• Signals
• Protected Functions
• Detailed Description

Detailed Description

TheQAbstractTextDocumentLayout class is an abstract base class used to implement custom layouts for QTextDocuments.

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 subclassQAbstractTextDocumentLayout to provide custom layout behavior for your text documents.

An instance of theQAbstractTextDocumentLayout subclass can be installed on aQTextDocument object with thesetDocumentLayout() function.

You can insert custom objects into aQTextDocument; see theQTextObjectInterface class description for details.

Member Function Documentation

QAbstractTextDocumentLayout::QAbstractTextDocumentLayout(QTextDocument * document)

Creates a new text document layout for the givendocument.

QString QAbstractTextDocumentLayout::anchorAt(constQPointF & position) const

Returns the reference of the anchor the givenposition, or an empty string if no anchor exists at that point.

[pure virtual]QRectF QAbstractTextDocumentLayout::blockBoundingRect(constQTextBlock & block) const

Returns the bounding rectangle ofblock.

QTextDocument * QAbstractTextDocumentLayout::document() const

Returns the text document that this layout is operating on.

[pure virtual protected]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 byposition,charsRemoved, andcharsAdded 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,charsRemoved would be 0 andcharsAdded 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",charsRemoved would be 5 andcharsAdded would be 2.

For subclasses ofQAbstractTextDocumentLayout, 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:

• Determine the list of changedQTextBlock(s) using the parameters provided.
• EachQTextBlock object's correspondingQTextLayout object needs to be processed. You can access theQTextBlock's layout using theQTextBlock::layout() function. This processing should take the document's page size into consideration.
• If the total number of pages changed, thepageCountChanged() signal should be emitted.
• If the total size changed, thedocumentSizeChanged() signal should be emitted.
• Theupdate() signal should be emitted to schedule a repaint of areas in the layout that require repainting.

See alsoQTextLayout.

[pure virtual]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.

See alsodocumentSizeChanged() andQTextDocument::pageSize.

[signal]void QAbstractTextDocumentLayout::documentSizeChanged(constQSizeF & newSize)

This signal is emitted when the size of the document layout changes tonewSize.

Subclasses ofQAbstractTextDocumentLayout 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.

See alsodocumentSize().

[pure virtual]void QAbstractTextDocumentLayout::draw(QPainter * painter, constPaintContext & context)

Draws the layout with the givenpainter using the givencontext.

[virtual protected]void QAbstractTextDocumentLayout::drawInlineObject(QPainter * painter, constQRectF & rect,QTextInlineObject object,int posInDocument, constQTextFormat & format)

This function is called to draw the inline object,object, with the givenpainter within the rectangle specified byrect using the specified textformat.

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.

See alsodraw().

[protected]QTextCharFormat QAbstractTextDocumentLayout::format(int position)

Returns the character format that is applicable at the givenposition.

[pure virtual]QRectF QAbstractTextDocumentLayout::frameBoundingRect(QTextFrame * frame) const

Returns the bounding rectangle offrame.

QTextObjectInterface * QAbstractTextDocumentLayout::handlerForObject(int objectType) const

Returns a handler for objects of the givenobjectType.

[pure virtual]int QAbstractTextDocumentLayout::hitTest(constQPointF & point,Qt::HitTestAccuracy accuracy) const

Returns the cursor postion for the givenpoint with the specifiedaccuracy. Returns -1 if no valid cursor position was found.

[pure virtual]int QAbstractTextDocumentLayout::pageCount() const

Returns the number of pages contained in the layout.

See alsopageCountChanged().

[signal]void QAbstractTextDocumentLayout::pageCountChanged(int newPages)

This signal is emitted when the number of pages in the layout changes;newPages is the updated page count.

Subclasses ofQAbstractTextDocumentLayout 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.

See alsopageCount().

QPaintDevice * QAbstractTextDocumentLayout::paintDevice() const

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

See alsosetPaintDevice().

[virtual protected]void QAbstractTextDocumentLayout::positionInlineObject(QTextInlineObject item,int posInDocument, constQTextFormat & format)

Lays out the inline objectitem using the given textformat.

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.

See alsodrawInlineObject().

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

Registers the givencomponent as a handler for items of the givenobjectType.

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.

[virtual protected]void QAbstractTextDocumentLayout::resizeInlineObject(QTextInlineObject item,int posInDocument, constQTextFormat & format)

Sets the size of the inline objectitem corresponding to the textformat.

posInDocument specifies the position of the object within the document.

The default implementation resizes theitem 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::setPaintDevice(QPaintDevice * device)

Sets the paint device used for rendering the document's layout to the givendevice.

See alsopaintDevice().

[signal]void QAbstractTextDocumentLayout::update(constQRectF & rect = QRectF( 0., 0., 1000000000., 1000000000. ))

This signal is emitted when the rectanglerect has been updated.

Subclasses ofQAbstractTextDocumentLayout should emit this signal when the layout of the contents change in order to repaint.

[signal]void QAbstractTextDocumentLayout::updateBlock(constQTextBlock & block)

This signal is emitted when the specifiedblock has been updated.

Subclasses ofQAbstractTextDocumentLayout should emit this signal when the layout ofblock has changed in order to repaint.

This function was introduced in Qt 4.4.