~oif-team/ubuntu/natty/qt4-x11/xi2.1

<td width="1">  </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a> · <a href="classes.html"><font color="#004faf">All Classes</font></a> · <a href="mainclasses.html"><font color="#004faf">Main Classes</font></a> · <a href="annotated.html"><font color="#004faf">Annotated</font></a> · <a href="groups.html"><font color="#004faf">Grouped Classes</font></a> · <a href="functions.html"><font color="#004faf">Functions</font></a></td>

[Previous: <a href="richtext-structure.html">Rich Text Document Structure</a>]

[<a href="richtext.html">Contents</a>]

[Next: <a href="richtext-common-tasks.html">Common Rich Text Editing Tasks</a>]

</p>

<h1 align="center">The QTextCursor Interface</h1>

<ul><li><a href="#cursor-based-editing">Cursor-Based Editing</a></li>

<ul><li><a href="#using-a-cursor">Using a Cursor</a></li>

<li><a href="#grouping-cursor-operations">Grouping Cursor Operations</a></li>

<li><a href="#multiple-cursors">Multiple Cursors</a></li>

</ul>

<li><a href="#inserting-document-elements">Inserting Document Elements</a></li>

<ul><li><a href="#text-and-text-fragments">Text and Text Fragments</a></li>

<li><a href="#blocks">Blocks</a></li>

<li><a href="#frames">Frames</a></li>

<li><a href="#tables">Tables</a></li>

<li><a href="#lists">Lists</a></li>

<li><a href="#images">Images</a></li>

</ul>

<p>The <a href="qtextcursor.html">QTextCursor</a> interface allows documents and their structure to be edited in a way that should be familiar to most users of text editors and document editing software. Rich text documents can have multiple cursors associated with them, and each of these contains information about their position in the document and any selections that they may hold. This cursor-based paradigm makes common operations, such as cutting and pasting text, simple to implement programatically, yet it also allows more complex editing operations to be performed on the document.</p>

<p>This chapter describes most of the common editing operations that you will need to perform using a cursor, from basic insertion of text and document elements to more complex manipulation of document structures.</p>

<h2>Cursor-Based Editing</h2>

<p>At the simplest level, text documents are made up of a string of characters, marked up in some way to represent the block structure of the text within the document. <tt>QTextCursor</tt> provides a cursor-based interface that allows the contents of a <tt>QTextDocument</tt> to be manipulated at the character level. Since the elements (blocks, frames, tables, etc.) are also encoded in the character stream, the document structure can itself be changed by the cursor.</p>

<p>The cursor keeps track of its location within its parent document, and can report information about the surrounding structure, such as the enclosing text block, frame, table, or list. The formats of the enclosing structures can also be directly obtained through the cursor.</p>

<h3>Using a Cursor</h3>

<p>The main use of a cursor is to insert or modify text within a block. We can use a text editor's cursor to do this:</p>

<pre>  QTextEdit *editor = new QTextEdit();

QTextCursor cursor(editor->textCursor());</pre>

<p>Alternatively, we can obtain a cursor directly from a document:</p>

<pre>  QTextDocument *document = new QTextDocument(editor);

QTextCursor cursor(document);</pre>

<p>The cursor is positioned at the start of the document so that we can write into the first (empty) block in the document.</p>

<h3>Grouping Cursor Operations</h3>

<p>A series of editing operations can be packaged together so that they can be replayed, or undone together in a single action. This is achieved by using the <tt>beginEditBlock()</tt> and <tt>endEditBlock()</tt> functions in the following way, as in the following example where we select the word that contains the cursor:</p>

<pre>  cursor.beginEditBlock();

cursor.movePosition(QTextCursor::StartOfWord);

cursor.movePosition(QTextCursor::EndOfWord, QTextCursor::KeepAnchor);

cursor.endEditBlock();</pre>

<p>If editing operations are not grouped, the document automatically records the individual operations so that they can be undone later. Grouping operations into larger packages can make editing more efficient both for the user and for the application, but care has to be taken not to group too many useful operations together.</p>

<h3>Multiple Cursors</h3>

<p>Multiple cursors can be used to simultaneously edit the same document, although only one will be visible to the user in a <tt>QTextEdit</tt> widget. The <tt>QTextDocument</tt> ensures that each cursor writes text correctly and does not interfere with any of the others.</p>

<h2>Inserting Document Elements</h2>

<p><a href="qtextcursor.html">QTextCursor</a> provides several functions that can be used to change the structure of a rich text document. Generally, these functions allow document elements to be created with relevant formatting information, and they are inserted into the document at the cursor's position.</p>

<p>The first group of functions insert block-level elements, and update the cursor position, but they do not return the element that was inserted:</p>

<ul>

<li><a href="qtextcursor.html#insertBlock">insertBlock()</a> inserts a new text block (paragraph) into a document at the cursor's position, and moves the cursor to the start of the new block.</li>

<li><a href="qtextcursor.html#insertFragment">insertFragment()</a> inserts an existing text fragment into a document at the cursor's position.</li>

<li><a href="qtextcursor.html#insertImage">insertImage()</a> inserts an image into a document at the cursor's position.</li>

<li><a href="qtextcursor.html#insertText">insertText()</a> inserts text into the document at the cursor's position.</li>

</ul>

<p>You can examine the contents of the element that was inserted through the cursor interface.</p>

<p>The second group of functions insert elements that provide structure to the document, and return the structure that was inserted:</p>

<ul>

<li><a href="qtextcursor.html#insertFrame">insertFrame()</a> inserts a frame into the document <i>after</i> the cursor's current block, and moves the cursor to the start of the empty block in the new frame.</li>

<li><a href="qtextcursor.html#insertList">insertList()</a> inserts a list into the document at the cursor's position, and moves the cursor to the start of the first item in the list.</li>

<li><a href="qtextcursor.html#insertTable">insertTable()</a> inserts a table into the document <i>after</i> the cursor's current block, and moves the cursor to the start of the block following the table.</li>

</ul>

<p>These elements either contain or group together other elements in the document.</p>

<h3>Text and Text Fragments</h3>

<p>Text can be inserted into the current block in the current character format, or in a custom format that is specified with the text:</p>

<pre>  cursor.insertText(QObject::tr("Character formats"),

headingFormat);

cursor.insertBlock();

cursor.insertText(QObject::tr("Text can be displayed in a variety of "

"different character formats. "), plainFormat);

cursor.insertText(QObject::tr("We can emphasize text by "));

cursor.insertText(QObject::tr("making it italic"), emphasisFormat);</pre>

<p>Once the character format has been used with a cursor, that format becomes the default format for any text inserted with that cursor until another character format is specified.</p>

100

<p>If a cursor is used to insert text without specifying a character format, the text will be given the character format used at that position in the document.</p>

101

102

<h3>Blocks</h3>

103

<p>Text blocks are inserted into the document with the <a href="qtextcursor.html#insertBlock">insertBlock()</a> function.</p>

104

<pre>  QTextBlockFormat backgroundFormat = blockFormat;

105

backgroundFormat.setBackground(QColor("#dddddd"));

106

107

cursor.setBlockFormat(backgroundFormat);</pre>

108

<p>The cursor is positioned at the start of the new block.</p>

109

110

<h3>Frames</h3>

111

<p>Frames are inserted into a document using the cursor, and will be placed within the cursor's current frame <i>after</i> the current block. The following code shows how a frame can be inserted between two text blocks in a document's root frame. We begin by finding the cursor's current frame:</p>

112

<pre>  QTextFrame *mainFrame = cursor.currentFrame();

113

cursor.insertText(...);</pre>

114

<p>We insert some text in this frame then set up a frame format for the child frame:</p>

115

<pre>  QTextFrameFormat frameFormat;

116

frameFormat.setMargin(32);

117

frameFormat.setPadding(8);

118

frameFormat.setBorder(4);</pre>

119

<p>The frame format will give the frame an external margin of 32 pixels, internal padding of 8 pixels, and a border that is 4 pixels wide. See the <a href="qtextframeformat.html">QTextFrameFormat</a> documentation for more information about frame formats.</p>

120

<p>The frame is inserted into the document after the preceding text:</p>

121

<pre>  cursor.insertFrame(frameFormat);

122

cursor.insertText(...);</pre>

123

<p>We add some text to the document immediately after we insert the frame. Since the text cursor is positioned <i>inside the frame</i> when it is inserted into the document, this text will also be inserted inside the frame.</p>

124

<p>Finally, we position the cursor outside the frame by taking the last available cursor position inside the frame we recorded earlier:</p>

125

<pre>  cursor = mainFrame->lastCursorPosition();

126

cursor.insertText(...);</pre>

127

<p>The text that we add last is inserted after the child frame in the document. Since each frame is padded with text blocks, this ensures that more elements can always be inserted with a cursor.</p>

128

129

<h3>Tables</h3>

130

<p>Tables are inserted into the document using the cursor, and will be placed within the cursor's current frame <i>after</i> the current block:</p>

131

<pre>  QTextCursor cursor(editor->textCursor());

132

QTextTable *table = cursor.insertTable(rows, columns, tableFormat);</pre>

133

<p>Tables can be created with a specific format that defines the overall properties of the table, such as its alignment, background color, and the cell spacing used. It can also determine the constraints on each column, allowing each of them to have a fixed width, or resize according to the available space.</p>

134

<pre>  QTextTableFormat tableFormat;

135

tableFormat.setBackground(QColor("#e0e0e0"));

136

QVector<QTextLength> constraints;

137

constraints << QTextLength(QTextLength::PercentageLength, 16);

138

constraints << QTextLength(QTextLength::PercentageLength, 28);

139

constraints << QTextLength(QTextLength::PercentageLength, 28);

140

constraints << QTextLength(QTextLength::PercentageLength, 28);

141

tableFormat.setColumnWidthConstraints(constraints);

142

QTextTable *table = cursor.insertTable(rows, columns, tableFormat);</pre>

143

<p>The columns in the table created above will each take up a certain percentage of the available width. Note that the table format is optional; if you insert a table without a format, some sensible default values will be used for the table's properties.</p>

144

<p>Since cells can contain other document elements, they too can be formatted and styled as necessary.</p>

145

<p>Text can be added to the table by navigating to each cell with the cursor and inserting text.</p>

146

<pre>  cell = table->cellAt(0, 0);

147

cellCursor = cell.firstCursorPosition();

148

cellCursor.insertText(tr("Week"), charFormat);</pre>

149

<p>We can create a simple timetable by following this approach:</p>

150

<pre>  for (column = 1; column < columns; ++column) {

151

cell = table->cellAt(0, column);

152

cellCursor = cell.firstCursorPosition();

153

cellCursor.insertText(tr("Team %1").arg(column), charFormat);

154

}

155

156

for (row = 1; row < rows; ++row) {

157

cell = table->cellAt(row, 0);

158

cellCursor = cell.firstCursorPosition();

159

cellCursor.insertText(tr("%1").arg(row), charFormat);

160

161

for (column = 1; column < columns; ++column) {

162

if ((row-1) % 3 == column-1) {

163

cell = table->cellAt(row, column);

164

QTextCursor cellCursor = cell.firstCursorPosition();

165

cellCursor.insertText(tr("On duty"), charFormat);

166

}

167

}

168

}</pre>

169

170

<h3>Lists</h3>

171

<p>Lists of block elements can be automatically created and inserted into the document at the current cursor position. Each list that is created in this way requires a list format to be specified:</p>

172

<pre>  QTextListFormat listFormat;

173

if (list) {

174

listFormat = list->format();

175

listFormat.setIndent(listFormat.indent() + 1);

176

}

177

178

listFormat.setStyle(QTextListFormat::ListDisc);

179

cursor.insertList(listFormat);</pre>

180

<p>The above code first checks whether the cursor is within an existing list and, if so, gives the list format for the new list a suitable level of indentation. This allows nested lists to be created with increasing levels of indentation. A more sophisticated implementation would also use different kinds of symbol for the bullet points in each level of the list.</p>

181

182

<h3>Images</h3>

183

<p>Inline images are added to documents through the cursor in the usual manner. Unlike many other elements, all of the image properties are specified by the image's format. This means that a <tt>QTextImageFormat</tt> object has to be created before an image can be inserted:</p>

184

<pre>  QTextImageFormat imageFormat;

185

imageFormat.setName(":/images/advert.png");

186

cursor.insertImage(imageFormat);</pre>

187

<p>The image name refers to an entry in the application's resource file. The method used to derive this name is described in <a href="resources.html">The Qt Resource System</a>.</p>

188

<p>

189

[Previous: <a href="richtext-structure.html">Rich Text Document Structure</a>]

190

[<a href="richtext.html">Contents</a>]

191

[Next: <a href="richtext-common-tasks.html">Common Rich Text Editing Tasks</a>]

192

</p>

193

194

195

196

<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>

197

198

</tr></table></div></address></body>

199

</html>

Older »