Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.trolltech.qt.gui
Class QAbstractTextDocumentLayout

    java.lang.Object
      com.trolltech.qt.internal.QSignalEmitterInternal
          com.trolltech.qt.QSignalEmitter
              com.trolltech.qt.QtJambiObject
                  com.trolltech.qt.core.QObject
                      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` using the following steps:

- Choose an `objectType`. The `objectType` is an integer with a value greater or equal to `QTextFormat::UserObject` .
- Create a `QTextCharFormat` object and set the object type to the chosen type using the setObjectType() function.
- Implement the `QTextObjectInterface` class.
- Call `registerHandler()` with an instance of your `QTextObjectInterface` subclass to register your object type.
- Insert `QChar::ObjectReplacementCharacter` with the aforementioned `QTextCharFormat` of the chosen object type into the document. As a result, the functions of `QTextObjectInterface`: intrinsicSize() and drawObject() will be called with the `QTextFormat` as parameter whenever the replacement character is encountered.

Nested Class Summary

Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
`QSignalEmitter.AbstractSignal, 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)` 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`.

### handlerForObject

    public final QTextObjectInterface handlerForObject(int objectType)

  Returns a handler for objects of the given `objectType`.

### paintDevice

    public final QPaintDeviceInterface paintDevice()

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

See also:
  `setPaintDevice()`.

### registerHandler

    public final void registerHandler(int objectType,
                                      QObject 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.

### 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:

  - Determine the list of changed `QTextBlock`(s) using the parameters provided.
  - Each `QTextBlock` object's corresponding `QTextLayout` object needs to be processed. You can access the `QTextBlock`'s layout using the `QTextBlock::layout()` function. This processing should take the document's page size into consideration.
  - If the total number of pages changed, the `pageCountChanged()` signal should be emitted.
  - If the total size changed, the `documentSizeChanged()` signal should be emitted.
  - The `update()` signal should be emitted to schedule a repaint of areas in the layout that require repainting.

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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD