Rich Text Processing富文本处理
Scribe框架提供一系列读和控制富文本文档的类。Qt4提供像QTextDocument类，他能够为开发提供创建和修改结构的富文本文档。
文档内的信息通过两个补充的接口存取：
1. 基于光标的接口用来编辑。2. 可读的分层接口它提供文档结构的高层次预览。使用前者的优点是他可以使用操纵符编辑，提供了一个很好的用户交互接口，不会损失潜在的文档结构。而后者的接口在查询和文档展示时最有用。
帮助文档分为了六个章节来介绍Rich Text Processing，可以仔细查阅：
Rich Text Document Structure
The QTextCursor Interface
Document Layouts
Common Rich Text Editing Tasks
Advanced Rich Text Processing
Supported HTML Subset
Rich Text Document Structure
QTextDocument类是文本文档的代表，它包含了构建富文本文档所需的信息。文档的结构是由分层的文本块（text blocks），frames，tables和一些其他的内容对象组成。新元素的创建和插入可以使用QTextCursor或者editor widget（例如QTextEdit）。如下图表示了他们的分层结构：
使用QTextEdit使展示编辑富文本非常容易，文档可以为任何编辑部件无关地创建，例如：
QTextDocument *newDocument = new QTextDocument;
也可以为已存在的编辑部件创建：
QTextEdit *editor = new QTextEdit;
QTextDocument *editorDocument = editor->document();
一个空文档包含一个root frame，这个root frame自己是包含一个空text block的。Frame不仅有分隔文档的功能，也有提供如何显示的功能。下面是获得root frame的方法：
QTextDocument *textDocument;
QTextFrame *root = textDocument->rootFrame();
Table是frame的专门类型，由一些单位（cells）组成，它们被安排成行和列，每一个都包含结构和文本。Table提供管理和呈现的特征，这样可以灵活的创建单位。Text blocks包含特殊化的文本和字符格式信息，例如字符的颜色，对齐，背景等等。以上的元素对应的类是QTextFrame, QTextTable, QTextBlock, (还有一个对应列表的类QTextList）。图片元素由特殊的text block代表。一组元素可以一起子类化为QTextBlockGroup，QTextBlockGroup是QTextFrame子类。
Text blocks可以通过QTextBlock::iterator遍历块的内部结构：
QTextBlock::iterator it;
for (it = currentBlock.begin(); !(it.atEnd()); ++it) {
QTextFragment currentFragment = it.fragment();
if (currentFragment.isValid())
processFragment(currentFragment);
}
QTextBlock提供了比较操纵符：== != <用来判断两个块是否相同，出现的先后。
Text frames可以由一组块和子frames组成。所有的frame除了root frame，都有父frame。使用QTextFrame::iterator遍历frame的子元素：
QDomElement frameElement = ...
QTextFrame::iterator it;
for (it = frame->begin(); !(it.atEnd()); ++it) {
QTextFrame *childFrame = it.currentFrame();
QTextBlock childBlock = it.currentBlock();
if (childFrame)
processFrame(frameElement, childFrame);
else if (childBlock.isValid())
processBlock(frameElement, childBlock);
}
QTextTable是QTextFrame的子类，所以tables可以像对待QTextFrame一样对待。它每一个单位（cell）的检查可以通过行列号：
for (int row = 0; row < table->rows(); ++row) {
for (int column = 0; column < table->columns(); ++column) {
QTextTableCell tableCell = table->cellAt(row, column);
processTableCell(tableCell);
}
}
QTextList是QTextBlockGroup的子类，它可以使用索引获得QTextList对象的项。
for (int index = 0; index < list->count(); ++index) {
QTextBlock listItem = list->item(index);
processListItem(listItem);
}
Images在QTextDocument中由text fragment代表，由光标（cursor）接口创建，可以被字符格式修改：
if (fragment.isValid()) {
QTextImageFormat newImageFormat = fragment.charFormat().toImageFormat();
if (newImageFormat.isValid()) {
newImageFormat.setName(":/images/newimage.png");
QTextCursor helper = cursor;
helper.setPosition(fragment.position());
helper.setPosition(fragment.position() + fragment.length(), QTextCursor::KeepAnchor);
helper.setCharFormat(newImageFormat);
}
}
The QTextCursor Interface
文档可以通过QTextCursor提供的接口编辑，
使用cursor主要是用来插入或修改块中的文本，我们可以在编辑器中使用：
QTextEdit *editor = new QTextEdit();
QTextCursor cursor(editor->textCursor());
也可以直接从一个文档中获取。
QTextDocument *document = new QTextDocument(editor);
QTextCursor cursor(document);
一系列的编辑操作可以打包到一起去，这样可以使用beginEditBlock(),endEditBlock()实现，下面代码示例：
cursor.beginEditBlock();
cursor.movePosition(QTextCursor::StartOfWord);
cursor.movePosition(QTextCursor::EndOfWord, QTextCursor::KeepAnchor);
cursor.endEditBlock();
QTextCursor提供一些插入文档元素的操作：
insertBlock()
insertFrament()
insertImage()
insertText()
以上都不会返回插入元素，下面的操作会返回插入的元素：
insertFrame()
insertList()
insertTable()
一下是一些示例：
// insert Text
cursor.insertText(tr("Character formats"),
headingFormat);
cursor.insertBlock();
cursor.insertText(tr("Text can be displayed in a variety of " "different character formats. "), plainFormat); // 以某格式插入文本
cursor.insertText(tr("We can emphasize text by "));
cursor.insertText(tr("making it italic"), emphasisFormat);
// insert block
QTextBlockFormat backgroundFormat = blockFormat;
backgroundFormat.setBackground(QColor("lightGray"));
cursor.setBlockFormat(backgroundFormat);
// insert frame
QTextFrame *mainFrame = cursor.currentFrame();
cursor.insertText(...);
// 为子frame建立一个frame格式
QTextFrameFormat frameFormat;
frameFormat.setMargin(32);
frameFormat.setPadding(8);
frameFormat.setBorder(4);
QTextFrameFormat的格式示意图：
cursor.insertFrame(frameFormat);
cursor.insertText(...);
插入table：
QTextCursor cursor(editor->textCursor());
QTextTable *table = cursor.insertTable(rows, columns, tableFormat);
它也可以定义格式：
QTextTableFormat tableFormat;
tableFormat.setBackground(QColor("#e0e0e0"));
QVector<QTextLength> constraints;
constraints << QTextLength(QTextLength::PercentageLength, 16);
constraints << QTextLength(QTextLength::PercentageLength, 28);
constraints << QTextLength(QTextLength::PercentageLength, 28);
constraints << QTextLength(QTextLength::PercentageLength, 28);
tableFormat.setColumnWidthConstraints(constraints);
QTextTable *table = cursor.insertTable(rows, columns, tableFormat);
插入list：
QTextListFormat listFormat;
if (list) {
listFormat = list->format();
listFormat.setIndent(listFormat.indent() + 1);
}
listFormat.setStyle(QTextListFormat::ListDisc);
cursor.insertList(listFormat);
插入images：
QTextImageFormat imageFormat;
imageFormat.setName(":/images/advert.png");
cursor.insertImage(imageFormat);：
Document Layouts
每个文档的布局都是子类化的QAbstractTextDocumentLayout类。QTextLayout可以帮助开发者呈现渲染文本，它可以用在plain和rich text。QTextLine是QTextLayout内的一排文本，可以QTextLayout::createLine()创建。
下面是个例子：
QTextLayout textLayout(text, font);
qreal margin = 10;
qreal radius = qMin(width()/2.0, height()/2.0) - margin;
QFontMetrics fm(font);
qreal lineHeight = fm.height();
qreal y = 0;
textLayout.beginLayout();
while (1) {
// create a new line
QTextLine line = textLayout.createLine();
if (!line.isValid())
break;
qreal x1 = qMax(0.0, pow(pow(radius,2)-pow(radius-y,2), 0.5));
qreal x2 = qMax(0.0, pow(pow(radius,2)-pow(radius-(y+lineHeight),2), 0.5));
qreal x = qMax(x1, x2) + margin;
qreal lineWidth = (width() - margin) - x;
line.setLineWidth(lineWidth);
line.setPosition(QPointF(x, margin+y));
y += line.height();
}
textLayout.endLayout();
QPainter painter;
painter.begin(this);
painter.setRenderHint(QPainter::Antialiasing);
painter.fillRect(rect(), Qt::white);
painter.setBrush(QBrush(Qt::black));
painter.setPen(QPen(Qt::black));
textLayout.draw(&painter, QPoint(0,0));
painter.setBrush(QBrush(QColor("#a6ce39")));
painter.setPen(QPen(Qt::black));
painter.drawEllipse(QRectF(-radius, margin, 2*radius, 2*radius));
painter.end();
Common Rich Text Editing Tasks
我们通常用QTextBrowser和QTextEdit完成富文本编辑任务，通过QTextDocument创建文档，QTextCursor编辑，用文档结构展示。
例如利用文本编辑器部件展示HTML：
QTextEdit *editor = new QTextEdit(parent);
editor->setHtml(aStringContainingHTMLtext);
editor->show();
默认情况下，文本编辑器包含一个带有root frame的文档，可以editor->document()获得，可使用editor->textCursor()获得编辑器的光标QTextCursor。
选择文本，通过移动光标，例如：QTextCursor::MoveMode(MoveAnchor, KeepAnchor)
cursor.movePosition(QTextCursor::StartOfWord);
cursor.movePosition(QTextCursor::EndOfWord, QTextCursor::KeepAnchor);
查找文本，下面是查找一个单词，并改变它的颜色以显示：
QTextCursor newCursor(document);
while (!newCursor.isNull() && !newCursor.atEnd()) {
newCursor = document->find(searchString, newCursor);
if (!newCursor.isNull()) {
newCursor.movePosition(QTextCursor::WordRight,
QTextCursor::KeepAnchor);
newCursor.mergeCharFormat(colorFormat);
}
}
打印文本，QTextEdit可以自动在一页大小的地方断开，以适应打印。QTextDocument提供print()函数允许打印。例如所示代码：
QTextDocument *document = editor->document();
QPrinter printer;
QPrintDialog *dlg = new QPrintDialog(&printer, this);
if (dlg->exec() != QDialog::Accepted)
return;
document->print(&printer);
Advanced Rich Text Processing
处理大文件
Qt 不限制文本处理的文件大小，对于大多数情况而言，这将不会出现问题。文件大小依赖于你硬件和你的Qt程序实现。
如果你面对了这个问题，我们推荐你
1. 你应该考虑断开大段成为更小的段落，你也可以定期插入换行符，这样就看起来像QTextEdit的一个大段。
2. 你可以在QTextDocument中用maximumBlockCount()减少块的数量，文档只和QTextEdit涉及到的块数量大小相当。
3. 当增加文本到一个文本编辑时，这是一个增加文本到编辑块（看下例）的优势。结果是文本编辑不是立刻需要全部文档结构的。
下面的例子我们假设文本编辑是可见的。
textEdit.show();
textCursor.beginEditBlock();
for (int i = 0; i < 1000; ++i) {
textCursor.insertBlock();
textCursor.insertText(paragraphText.at(i));
}
textCursor.endEditBlock();
Supported HTML Subset
Widgets使用QTextDocument能够展示特殊的富文本，例如QLabel, QTextEdit。
在Text Widget使用HTML标记
Widget会在展示时自动删除HTML标记，并根据含义展示富文本。例如，设置一个文本标签："<b>Hello</b> <i>Qt!</i>"，它会展示出这样：Hello Qt！
所支持的标记有：
| Tag |
Description |
Comment |
| a |
Anchor or link |
Supports the href and name attributes. Note that the :visited selector is one of those that is not supported by the rich text engine. See below for a list of others. |
| address |
Address |
|
| b |
Bold |
|
| big |
Larger font |
|
| blockquote |
Indented paragraph |
|
| body |
Document body |
Supports the bgcolor attribute, which can be a Qt color name or a #RRGGBB color specification. |
| br |
Line break |
|
| center |
Centered paragraph |
|
| cite |
Inline citation |
Same as i. |
| code |
Code |
Same as tt. |
| dd |
Definition data |
|
| dfn |
Definition |
Same as i. |
| div |
Document division |
Supports the standard block attributes. |
| dl |
Definition list |
Supports the standard block attributes. |
| dt |
Definition term |
Supports the standard block attributes. |
| em |
Emphasized |
Same as i. |
| font |
Font size, family, and/or color |
Supports the following attributes: size, face, and color (Qt color names or #RRGGBB). |
| h1 |
Level 1 heading |
Supports the standard block attributes. |
| h2 |
Level 2 heading |
Supports the standard block attributes. |
| h3 |
Level 3 heading |
Supports the standard block attributes. |
| h4 |
Level 4 heading |
Supports the standard block attributes. |
| h5 |
Level 5 heading |
Supports the standard block attributes. |
| h6 |
Level 6 heading |
Supports the standard block attributes. |
| head |
Document header |
|
| hr |
Horizontal line |
Supports the width attribute, which can be specified as an absolute or relative (%) value. |
| html |
HTML document |
|
| i |
Italic |
|
| img |
Image |
Supports the src, source (for Qt 3 compatibility), width, and height attributes. |
| kbd |
User-entered text |
|
| meta |
Meta-information |
If a text encoding is specified using the meta tag, it is picked up by Qt::codecForHtml(). Likewise, if an encoding is specified toQTextDocument::toHtml(), the encoding is stored using a meta tag, for example: <meta http-equiv="Content-Type" content="text/html; charset=EUC-JP" /> |
| li |
List item |
|
| nobr |
Non-breakable text |
|
| ol |
Ordered list |
Supports the standard list attributes. |
| p |
Paragraph |
Left-aligned by default. Supports the standard block attributes. |
| pre |
Preformated text |
|
| qt |
Qt rich-text document |
Synonym for html. Provided for compatibility with earlier versions of Qt. |
| s |
Strikethrough |
|
| samp |
Sample code |
Same as tt. |
| small |
Small font |
|
| span |
Grouped elements |
|
| strong |
Strong |
Same as b. |
| style |
Style sheet |
Allows styling information to be included with the rich text. A limited subset of CSS syntax can be used to change the appearance of the text. |
| sub |
Subscript |
|
| sup |
Superscript |
|
| table |
Table |
Supports the following attributes: border, bgcolor (Qt color names or #RRGGBB), cellspacing, cellpadding, width(absolute or relative), and height. |
| tbody |
Table body |
Does nothing. |
| td |
Table data cell |
Supports the standard table cell attributes. |
| tfoot |
Table footer |
Does nothing. |
| th |
Table header cell |
Supports the standard table cell attributes. |
| thead |
Table header |
If the thead tag is specified, it is used when printing tables that span multiple pages. |
| title |
Document title |
The value specified using the title tag is available through QTextDocument::metaInformation(). |
| tr |
Table row |
Supports the bgcolor attribute, which can be a Qt color name or a #RRGGBB color specification. |
| tt |
Typewrite font |
|
| u |
Underlined |
|
| ul |
Unordered list |
Supports the standard list attributes. |
| var |
Variable |
Same as i. |
块block属性。这下面的属性被div, dl, dt, h1, h2, h3, h4, h5, h6, p支持：
align(left, right, center, justify)
dir(ltr, rtl)
列表list属性。下面的属性被ol, ul支持：
type (1, a, A, square, disc, circle)
表单位Table Cell属性。下面的被td, th标记支持：
width (absolute, relative, or no-value)
bgcolor (Qt color names or #RRGGBB )
colspan
rowspan
align (left, right, center, justify)
valign (top, middle, bottom)
CSS属性
| Version:Property |
Values |
Description |
| background-color |
<color> |
Background color for elements |
| background-image |
<uri> |
Background image for elements |
| color |
<color> |
Text foreground color |
| font-family |
<family name> |
Font family name |
| font-size |
[ small | medium | large | x-large | xx-large ] | <size>pt | <size>px |
Font size relative to the document font, or specified in points or pixels |
| font-style |
[ normal | italic | oblique ] |
|
| font-weight |
[ normal | bold | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 ] |
Specifies the font weight used for text, where normal and bold are mapped to the corresponding QFont weights. Numeric values are 8 times the equivalent QFont weight values. |
| text-decoration |
none | [ underline || overline || line-through ] |
Additional text effects |
| font |
[ [ <'font-style'> || <'font-weight'> ]? <'font-size'> <'font-family'> ] |
Font shorthand property |
| text-indent |
<length>px |
First line text indentation in pixels |
| white-space |
normal | pre | nowrap | pre-wrap |
Declares how whitespace in HTML is handled. |
| margin-top |
<length>px |
Top paragraph margin in pixels |
| margin-bottom |
<length>px |
Bottom paragraph margin in pixels |
| margin-left |
<length>px |
Left paragraph margin in pixels |
| margin-right |
<length>px |
Right paragraph margin in pixels |
| padding-top |
<length>px |
Top table cell padding in pixels |
| padding-bottom |
<length>px |
Bottom table cell padding in pixels |
| padding-left |
<length>px |
Left table cell padding in pixels |
| padding-right |
<length>px |
Right table cell padding in pixels |
| padding |
<length>px |
Shorthand for setting all the padding properties at once. |
| vertical-align |
baseline | sub | super | middle | top | bottom |
Vertical text alignment. For vertical alignment in text table cells only middle, top, and bottom apply. |
| border-color |
<color> |
Border color for text tables. |
| border-style |
none | dotted | dashed | dot-dash | dot-dot-dash | solid | double | groove | ridge | inset | outset |
Border style for text tables. |
| background |
[ <'background-color'> || <'background-image'> ] |
Background shorthand property |
| page-break-before |
[ auto | always ] |
Make it possible to enforce a page break before the paragraph/table |
| page-break-after |
[ auto | always ] |
Make it possible to enforce a page break after the paragraph/table |
| float |
[ left | right | none ] |
Specifies where an image or a text will be placed in another element. Note that the floatproperty is only supported for tables and images. |
| text-transform |
[ uppercase | lowercase ] |
Select the transformation that will be performed on the text prior to displaying it. |
| font-variant |
small-caps |
Perform the smallcaps transformation on the text prior to displaying it. |
| word-spacing |
<width>px |
Specifies an alternate spacing between each word. |
支持CSS选择器，所有CSS2.1选择器都支持，除了pseudo-class选择器，例如：first-child, :visited 和 :hover