com.trolltech.qt.gui
Class QAbstractTextDocumentLayout

java.lang.Object
  extended by com.trolltech.qt.internal.QSignalEmitterInternal
      extended by com.trolltech.qt.QSignalEmitter
          extended by com.trolltech.qt.QtJambiObject
              extended by com.trolltech.qt.core.QObject
                  extended by com.trolltech.qt.gui.QAbstractTextDocumentLayout
All Implemented Interfaces:
QtJambiInterface
Direct Known Subclasses:
QPlainTextDocumentLayout

public abstract class QAbstractTextDocumentLayout
extends QObject

The QAbstractTextDocumentLayout 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 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 setDocumentLayout() function.

You can insert custom objects into a QTextDocument; see the QTextObjectInterface class description for details.

See also:
QTextObjectInterface.


Nested Class Summary
 
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
QSignalEmitter.AbstractSignal, QSignalEmitter.PrivateSignal0, QSignalEmitter.PrivateSignal1, QSignalEmitter.PrivateSignal2, QSignalEmitter.PrivateSignal3, QSignalEmitter.PrivateSignal4, QSignalEmitter.PrivateSignal5, QSignalEmitter.PrivateSignal6, QSignalEmitter.PrivateSignal7, QSignalEmitter.PrivateSignal8, QSignalEmitter.PrivateSignal9, QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9
 
Nested classes/interfaces inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
com.trolltech.qt.internal.QSignalEmitterInternal.AbstractSignalInternal
 
Field Summary
 QSignalEmitter.Signal1 documentSizeChanged
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal1 pageCountChanged
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal1 update
          This signal takes 1 generic argument(s).
 QSignalEmitter.Signal1 updateBlock
          This signal takes 1 generic argument(s).
 
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
currentSender
 
Constructor Summary
QAbstractTextDocumentLayout(QTextDocument doc)
          Creates a new text document layout for the given document.
 
Method Summary
 java.lang.String anchorAt(QPointF pos)
          Returns the reference of the anchor the given position, or an empty string if no anchor exists at that point.
abstract  QRectF blockBoundingRect(QTextBlock block)
          Returns the bounding rectangle of block.
 QTextDocument document()
          Returns the text document that this layout is operating on.
protected abstract  void documentChanged(int from, int charsRemoved, int charsAdded)
          This function is called whenever the contents of the document change.
abstract  QSizeF documentSize()
          Returns the total size of the document's layout.
abstract  void draw(QPainter painter, QAbstractTextDocumentLayout_PaintContext context)
          Draws the layout with the given painter using the given context.
protected  void drawInlineObject(QPainter painter, QRectF rect, QTextInlineObject object, int posInDocument, QTextFormat format)
          This function is called to draw the inline object, object, with the given painter within the rectangle specified by rect using the specified text format.
protected  QTextCharFormat format(int pos)
          Returns the character format that is applicable at the given position.
abstract  QRectF frameBoundingRect(QTextFrame frame)
          Returns the bounding rectangle of frame.
 QTextObjectInterface handlerForObject(int objectType)
          Returns a handler for objects of the given objectType.
abstract  int hitTest(QPointF point, Qt.HitTestAccuracy accuracy)
          Returns the cursor postion for the given point with the specified accuracy.
abstract  int pageCount()
          Returns the number of pages contained in the layout.
 QPaintDeviceInterface paintDevice()
          Returns the paint device used to render the document's layout.
protected  void positionInlineObject(QTextInlineObject item, int posInDocument, QTextFormat format)
          Lays out the inline object item using the given text format.
 void registerHandler(int objectType, QObject component)
          Deprecated. 
 void registerHandler(int objectType, QTextObjectInterface component)
          Registers the given component as a handler for items of the given objectType.
protected  void resizeInlineObject(QTextInlineObject item, int posInDocument, QTextFormat format)
          Sets the size of the inline object item corresponding to the text format.
 void setPaintDevice(QPaintDeviceInterface device)
          Sets the paint device used for rendering the document's layout to the given device.
 
Methods inherited from class com.trolltech.qt.core.QObject
childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread
 
Methods inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
__qt_signalInitialization
 
Methods inherited from class java.lang.Object
clone, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Field Detail

documentSizeChanged

public final QSignalEmitter.Signal1 documentSizeChanged

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.core.QSizeF(named: newSize)>:

This signal is emitted when the size of the document layout changes to 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.

See also:
documentSize().


pageCountChanged

public final QSignalEmitter.Signal1 pageCountChanged

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <java.lang.Integer(named: newPages)>:

This signal is emitted when the number of pages in the layout changes; 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.

See also:
pageCount().


update

public final QSignalEmitter.Signal1 update

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.core.QRectF(named: rect)>:

This signal is emitted when the rectangle rect has been updated.

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


updateBlock

public final QSignalEmitter.Signal1 updateBlock

This signal takes 1 generic argument(s). We list their type and the name they go by in the description of this signal. <com.trolltech.qt.gui.QTextBlock(named: rect)>:

This signal is emitted when the rectangle rect has been updated.

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

Constructor Detail

QAbstractTextDocumentLayout

public QAbstractTextDocumentLayout(QTextDocument doc)
Creates a new text document layout for the given document.

Method Detail

anchorAt

public final java.lang.String anchorAt(QPointF pos)
Returns the reference of the anchor the given position, or an empty string if no anchor exists at that point.


document

public final QTextDocument document()
Returns the text document that this layout is operating on.


format

protected final QTextCharFormat format(int pos)
Returns the character format that is applicable at the given position.


paintDevice

public final QPaintDeviceInterface paintDevice()
Returns the paint device used to render the document's layout.

See also:
setPaintDevice().


registerHandler

@Deprecated
public final void registerHandler(int objectType,
                                             QObject component)
Deprecated. 

Registers the given component as a handler for items of the given 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.


setPaintDevice

public final void setPaintDevice(QPaintDeviceInterface device)
Sets the paint device used for rendering the document's layout to the given device.

See also:
paintDevice().


blockBoundingRect

public abstract QRectF blockBoundingRect(QTextBlock block)
Returns the bounding rectangle of block.


documentChanged

protected abstract void documentChanged(int from,
                                        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 position, charsRemoved, and 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, charsRemoved would be 0 and 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", charsRemoved would be 5 and 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:

See also:
QTextLayout.


documentSize

public abstract QSizeF documentSize()
Returns the total size of the document's layout.

This information can be used by display widgets to update their scroll bars correctly.

See also:
documentSizeChanged() , and QTextDocument::pageSize.


draw

public abstract void draw(QPainter painter,
                          QAbstractTextDocumentLayout_PaintContext context)
Draws the layout with the given painter using the given context.


drawInlineObject

protected void drawInlineObject(QPainter painter,
                                QRectF rect,
                                QTextInlineObject object,
                                int posInDocument,
                                QTextFormat format)
This function is called to draw the inline object, object, with the given painter within the rectangle specified by rect using the specified text format.

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 also:
draw().


frameBoundingRect

public abstract QRectF frameBoundingRect(QTextFrame frame)
Returns the bounding rectangle of frame.


hitTest

public abstract int hitTest(QPointF point,
                            Qt.HitTestAccuracy accuracy)
Returns the cursor postion for the given point with the specified accuracy. Returns -1 if no valid cursor position was found.


pageCount

public abstract int pageCount()
Returns the number of pages contained in the layout.

See also:
pageCountChanged() .


positionInlineObject

protected void positionInlineObject(QTextInlineObject item,
                                    int posInDocument,
                                    QTextFormat format)
Lays out the inline object item using the given text format.

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 also:
drawInlineObject().


resizeInlineObject

protected void resizeInlineObject(QTextInlineObject item,
                                  int posInDocument,
                                  QTextFormat format)
Sets the size of the inline object item corresponding to the text format.

posInDocument specifies the position of the object within the document.

The default implementation resizes the 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.


handlerForObject

public final QTextObjectInterface handlerForObject(int objectType)
Returns a handler for objects of the given objectType.


registerHandler

public final void registerHandler(int objectType,
                                  QTextObjectInterface component)
Registers the given component as a handler for items of the given 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.

Parameters:
objectType - The type for which to register a handler.
component - The handler for the given type.