com.trolltech.qt.gui
Class QTextLayout

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.gui.QTextLayout
All Implemented Interfaces:
QtJambiInterface

public class QTextLayout
extends QtJambiObject

The QTextLayout class is used to lay out and paint a single paragraph of text. It offers most features expected from a modern text layout engine, including Unicode compliant rendering, line breaking and handling of cursor positioning. It can also produce and render device independent layout, something that is important for WYSIWYG applications.

The class has a rather low level API and unless you intend to implement your own text rendering for some specialized widget, you probably won't need to use it directly.

QTextLayout can currently deal with plain text and rich text paragraphs that are part of a QTextDocument.

QTextLayout can be used to create a sequence of QTextLine's with given widths and can position them independently on the screen. Once the layout is done, these lines can be drawn on a paint device.

Here's some pseudo code that presents the layout phase:

        int leading = fontMetrics.leading();
        double height = 0;
        double widthUsed = 0;
        textLayout.beginLayout();
        while (1==1) {
            QTextLine line = textLayout.createLine();
            if (!line.isValid())
                break;

            line.setLineWidth(lineWidth);
            height += leading;
            line.setPosition(new QPointF(0.0, height));
            height += line.height();
            widthUsed = Math.max(widthUsed, line.naturalTextWidth());
        }
        textLayout.endLayout();
The text can be drawn by calling the layout's draw() function:
        QPainter painter = new QPainter();
        textLayout.draw(painter,new QPointF(), new ArrayList<QTextLayout_FormatRange>());
The text layout's text is set in the constructor or with setText(). The layout can be seen as a sequence of QTextLine objects; use lineAt() or lineForTextPosition() to get a QTextLine, createLine() to create one. For a given position in the text you can find a valid cursor position with isValidCursorPosition(), nextCursorPosition(), and previousCursorPosition(). The layout itself can be positioned with setPosition(); it has a boundingRect(), and a minimumWidth() and a maximumWidth(). A text layout can be drawn on a painter device using draw().


Nested Class Summary
static class QTextLayout.CursorMode
           
 
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
 
Fields inherited from class com.trolltech.qt.internal.QSignalEmitterInternal
currentSender
 
Constructor Summary
QTextLayout()
          Constructs an empty text layout.
QTextLayout(java.lang.String text)
          Constructs a text layout to lay out the given text.
QTextLayout(java.lang.String text, QFont font)
          Constructs a text layout to lay out the given text with the specified font.
QTextLayout(java.lang.String text, QFont font, QPaintDeviceInterface paintdevice)
          Constructs a text layout to lay out the given text with the specified font.
 
Method Summary
 java.util.List additionalFormats()
          Returns the list of additional formats supported by the text layout.
 void beginLayout()
          Begins the layout process.
 QRectF boundingRect()
          The smallest rectangle that contains all the lines in the layout.
 boolean cacheEnabled()
          Returns true if the complete layout information is cached; otherwise returns false.
 void clearAdditionalFormats()
          Clears the list of additional formats supported by the text layout.
 void clearLayout()
          Clears the line information in the layout.
 QTextLine createLine()
          Returns a new text line to be laid out if there is text to be inserted into the layout; otherwise returns an invalid text line.
 void draw(QPainter p, QPointF pos, java.util.List selections)
          Draws the whole layout on the painter p at the position specified by pos.
 void draw(QPainter p, QPointF pos, java.util.List selections, QRectF clip)
          Draws the whole layout on the painter p at the position specified by pos.
 void drawCursor(QPainter p, QPointF pos, int cursorPosition)
          This is an overloaded member function, provided for convenience.
 void drawCursor(QPainter p, QPointF pos, int cursorPosition, int width)
          Draws a text cursor with the current pen and the specified width at the given position using the painter specified.
 void endLayout()
          Ends the layout process.
 QFont font()
          Returns the current font that is used for the layout, or a default font if none is set.
 boolean isValidCursorPosition(int pos)
          Returns true if position pos is a valid cursor position.
 QTextLine lineAt(int i)
          Returns the i-th line of text in this text layout.
 int lineCount()
          Returns the number of lines in this text layout.
 QTextLine lineForTextPosition(int pos)
          Returns the line that contains the cursor position specified by pos.
 double maximumWidth()
          The maximum width the layout could expand to; this is essentially the width of the entire text.
 double minimumWidth()
          The minimum width the layout needs.
 int nextCursorPosition(int oldPos)
          Returns the next valid cursor position after oldPos that respects the given cursor mode.
 int nextCursorPosition(int oldPos, QTextLayout.CursorMode mode)
          Returns the next valid cursor position after oldPos that respects the given cursor mode.
 QPointF position()
          The global position of the layout.
 int preeditAreaPosition()
          Returns the position of the area in the text layout that will be processed before editing occurs.
 java.lang.String preeditAreaText()
          Returns the text that is inserted in the layout before editing occurs.
 int previousCursorPosition(int oldPos)
          Returns the first valid cursor position before oldPos that respects the given cursor mode.
 int previousCursorPosition(int oldPos, QTextLayout.CursorMode mode)
          Returns the first valid cursor position before oldPos that respects the given cursor mode.
 void setAdditionalFormats(java.util.List overrides)
          Sets the additional formats supported by the text layout to formatList.
 void setCacheEnabled(boolean enable)
          Enables caching of the complete layout information if enable is true; otherwise disables layout caching.
 void setFont(QFont f)
          Sets the layout's font to the given font.
 void setPosition(QPointF p)
          Moves the text layout to point p.
 void setPreeditArea(int position, java.lang.String text)
          Sets the position and text of the area in the layout that is processed before editing occurs.
 void setText(java.lang.String string)
          Sets the layout's text to the given string.
 void setTextOption(QTextOption option)
          Sets the text option structure that controls the layout process to the given option.
 java.lang.String text()
          Returns the layout's text.
 QTextOption textOption()
          Returns the current text option used to control the layout process.
 
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, toString, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Constructor Detail

QTextLayout

public QTextLayout()
Constructs an empty text layout.

See also:
setText().


QTextLayout

public QTextLayout(java.lang.String text)
Constructs a text layout to lay out the given text.


QTextLayout

public QTextLayout(java.lang.String text,
                   QFont font)
Constructs a text layout to lay out the given text with the specified font.

All the metric and layout calculations will be done in terms of the paint device, paintdevice. If paintdevice is 0 the calculations will be done in screen metrics.


QTextLayout

public QTextLayout(java.lang.String text,
                   QFont font,
                   QPaintDeviceInterface paintdevice)
Constructs a text layout to lay out the given text with the specified font.

All the metric and layout calculations will be done in terms of the paint device, paintdevice. If paintdevice is 0 the calculations will be done in screen metrics.

Method Detail

additionalFormats

public final java.util.List additionalFormats()
Returns the list of additional formats supported by the text layout.

See also:
setAdditionalFormats(), and clearAdditionalFormats().


beginLayout

public final void beginLayout()
Begins the layout process.


boundingRect

public final QRectF boundingRect()
The smallest rectangle that contains all the lines in the layout.


cacheEnabled

public final boolean cacheEnabled()
Returns true if the complete layout information is cached; otherwise returns false.

See also:
setCacheEnabled().


clearAdditionalFormats

public final void clearAdditionalFormats()
Clears the list of additional formats supported by the text layout.

See also:
additionalFormats(), and setAdditionalFormats().


clearLayout

public final void clearLayout()
Clears the line information in the layout. After having called this function, lineCount() returns 0.


createLine

public final QTextLine createLine()
Returns a new text line to be laid out if there is text to be inserted into the layout; otherwise returns an invalid text line.

The text layout creates a new line object that starts after the last line in the layout, or at the beginning if the layout is empty. The layout maintains an internal cursor, and each line is filled with text from the cursor position onwards when the QTextLine::setLineWidth() function is called.

Once QTextLine::setLineWidth() is called, a new line can be created and filled with text. Repeating this process will lay out the whole block of text contained in the QTextLayout. If there is no text left to be inserted into the layout, the QTextLine returned will not be valid (isValid() will return false).


draw

public final void draw(QPainter p,
                       QPointF pos,
                       java.util.List selections)
Draws the whole layout on the painter p at the position specified by pos. The rendered layout includes the given selections.


draw

public final void draw(QPainter p,
                       QPointF pos,
                       java.util.List selections,
                       QRectF clip)
Draws the whole layout on the painter p at the position specified by pos. The rendered layout includes the given selections and is clipped within the rectangle specified by clip.


drawCursor

public final void drawCursor(QPainter p,
                             QPointF pos,
                             int cursorPosition)
This is an overloaded member function, provided for convenience.

Draws a text cursor with the current pen at the given position using the painter specified. The corresponding position within the text is specified by cursorPosition.


drawCursor

public final void drawCursor(QPainter p,
                             QPointF pos,
                             int cursorPosition,
                             int width)
Draws a text cursor with the current pen and the specified width at the given position using the painter specified. The corresponding position within the text is specified by cursorPosition.


endLayout

public final void endLayout()
Ends the layout process.


font

public final QFont font()
Returns the current font that is used for the layout, or a default font if none is set.

See also:
setFont().


isValidCursorPosition

public final boolean isValidCursorPosition(int pos)
Returns true if position pos is a valid cursor position.

In a Unicode context some positions in the text are not valid cursor positions, because the position is inside a Unicode surrogate or a grapheme cluster.

A grapheme cluster is a sequence of two or more Unicode characters that form one indivisible entity on the screen. For example the latin character `Ä' can be represented in Unicode by two characters, `A' (0x41), and the combining diaresis (0x308). A text cursor can only validly be positioned before or after these two characters, never between them since that wouldn't make sense. In indic languages every syllable forms a grapheme cluster.


lineAt

public final QTextLine lineAt(int i)
Returns the i-th line of text in this text layout.

See also:
lineCount(), and lineForTextPosition().


lineCount

public final int lineCount()
Returns the number of lines in this text layout.

See also:
lineAt().


lineForTextPosition

public final QTextLine lineForTextPosition(int pos)
Returns the line that contains the cursor position specified by pos.

See also:
isValidCursorPosition(), and lineAt().


maximumWidth

public final double maximumWidth()
The maximum width the layout could expand to; this is essentially the width of the entire text.

Warning: This function only returns a valid value after the layout has been done.

See also:
minimumWidth().


minimumWidth

public final double minimumWidth()
The minimum width the layout needs. This is the width of the layout's smallest non-breakable substring.

Warning: This function only returns a valid value after the layout has been done.

See also:
maximumWidth().


nextCursorPosition

public final int nextCursorPosition(int oldPos)
Returns the next valid cursor position after oldPos that respects the given cursor mode.

See also:
isValidCursorPosition(), and previousCursorPosition().


nextCursorPosition

public final int nextCursorPosition(int oldPos,
                                    QTextLayout.CursorMode mode)
Returns the next valid cursor position after oldPos that respects the given cursor mode.

See also:
isValidCursorPosition(), and previousCursorPosition().


position

public final QPointF position()
The global position of the layout. This is independent of the bounding rectangle and of the layout process.

See also:
setPosition().


preeditAreaPosition

public final int preeditAreaPosition()
Returns the position of the area in the text layout that will be processed before editing occurs.


preeditAreaText

public final java.lang.String preeditAreaText()
Returns the text that is inserted in the layout before editing occurs.


previousCursorPosition

public final int previousCursorPosition(int oldPos)
Returns the first valid cursor position before oldPos that respects the given cursor mode.

See also:
isValidCursorPosition(), and nextCursorPosition().


previousCursorPosition

public final int previousCursorPosition(int oldPos,
                                        QTextLayout.CursorMode mode)
Returns the first valid cursor position before oldPos that respects the given cursor mode.

See also:
isValidCursorPosition(), and nextCursorPosition().


setAdditionalFormats

public final void setAdditionalFormats(java.util.List overrides)
Sets the additional formats supported by the text layout to formatList.

See also:
additionalFormats(), and clearAdditionalFormats().


setCacheEnabled

public final void setCacheEnabled(boolean enable)
Enables caching of the complete layout information if enable is true; otherwise disables layout caching. Usually QTextLayout throws most of the layouting information away after a call to endLayout() to reduce memory consumption. If you however want to draw the laid out text directly afterwards enabling caching might speed up drawing significantly.

See also:
cacheEnabled().


setFont

public final void setFont(QFont f)
Sets the layout's font to the given font. The layout is invalidated and must be laid out again.

See also:
font(), and text().


setPosition

public final void setPosition(QPointF p)
Moves the text layout to point p.

See also:
position().


setPreeditArea

public final void setPreeditArea(int position,
                                 java.lang.String text)
Sets the position and text of the area in the layout that is processed before editing occurs.


setText

public final void setText(java.lang.String string)
Sets the layout's text to the given string. The layout is invalidated and must be laid out again.

Notice that when using this QTextLayout as part of a QTextDocument this method will have no effect.

See also:
text().


setTextOption

public final void setTextOption(QTextOption option)
Sets the text option structure that controls the layout process to the given option.

See also:
textOption(), and QTextOption.


text

public final java.lang.String text()
Returns the layout's text.

See also:
setText().


textOption

public final QTextOption textOption()
Returns the current text option used to control the layout process.

See also:
setTextOption(), and QTextOption.