Qt 富文本处理（09）：文本块和文本块格式

前言

  文本块可以看做是一个具有多行文本片段的段落。

  富文本文档的文档元素：QTextBlock类和QTextBlockFormat 类的层次结构如下图所示：

QTextBlock类

  QTextBlock类为QTextDocument中的文本片段提供了一个容器。

  文本块将文本块或段落封装在QTextDocument中。 QTextBlock提供对QTextDocuments的块/段落结构的只读访问。 如果要为QTextDocument的视觉表示实现自己的布局，或者要遍历文档并以自己的自定义格式写出内容，则主要使用它。

  文本块由其父文档创建。 如果需要创建新的文本块，或修改文档的内容，请用QTextCursor提供的基于光标的界面。

  每个文本块位于document( ) 中的特定position( ) 处。 可以使用text( ) 函数获得该块的内容。 length( ) 函数确定文档中块的大小（包括格式字符）。

  块的可视属性由它的文本layout()、charFormat() 和 blockFormat() 决定。

  next() 和 previous() 函数可以在文档的迭代过程中不被其他方式修改的情况下，对文档中的连续有效块进行迭代。 注意，尽管块按顺序返回，但是相邻的块可能来自文档结构中的不同位置。

  可以通过调用isValid() 确定块的有效性。

  QTextBlock提供了比较运算符，以使其更易于使用块：operator ==() 比较两个块是否相等，operator！=() 比较两个块是否不相等，operator <() 确定一个块是否在同一文档中位于另一个块之前 。

QTextBlockFormat 类

  QTextBlockFormat类提供QTextDocument中文本块的格式设置信息。

  文档由QTextBlock对象表示系列块组成。每个块可以包含某种项目，例如文本的段落，表格，列表或图像。每个块都有一个关联的QTextBlockFormat，用于指定其特征。

  为了适应从左到右和从右到左的语言，您可以使用setDirection() 设置块的方向。

  使用setAlignment() 设置段落对齐方式。

  边距由setTopMargin() ，setBottomMargin() ，setLeftMargin() ，setRightMargin() 控制。

  整体缩进使用setIndent() 设置，第一行的缩进使用setTextIndent() 设置。

  行间距由setLineHeight() 设置，并通过lineHeight() 和lineHeightType() 检索。可用的行距类型在LineHeightTypes枚举中。

  可以使用setNonBreakableLines() 启用和禁用换行。

  用于绘制段落背景的笔刷使用setBackground()设置，文本外观的其他方面可以通过使用setProperty()函数和 QTextFormat::Property的OutlinePen、ForegroundBrush和BackgroundBrush定制。

  如果文本块是列表的一部分，则它也可以具有可通过listFormat() 函数访问的列表格式。

代码示例

主要代码如下：

Widget::Widget(QWidget *parent)
    : QWidget(parent)
{
    edit = new QTextEdit;
    QVBoxLayout *mainLayout = new QVBoxLayout(this);
    mainLayout->addWidget(edit);
    resize(600,400);


    QTextDocument *doc = edit->document();  //获取文本文档
    QFont font("楷体",12);
    doc->setDefaultFont(font);      //设置文本文档的默认字体

    //通过文本编辑器加入一个段落文本
    edit->append("五星出东方，利中国");

    //通过文本编辑器获取当前文本光标
    QTextCursor cursor = edit->textCursor();

    //定义QTextBlock类型的文本块
    QTextBlock textBlock;
    //获取光标坐在行的文本块
    textBlock = cursor.block();

    //定义文本块格式 blockFormat变量
    QTextBlockFormat blockFormat = textBlock.blockFormat();

    //通过文本编辑器加入一个段落文本
    edit->append("五星出东方，利中国");

    /* 设置段落的缩进。
     * 使用setLeftMargin()和setTextIndent()可以独立于缩进设置页边距。
     * 缩进是一个整数，它与文档范围的标准缩进相乘，从而产生段落的实际缩进。*/
    QFontMetrics fm(doc->defaultFont());    // 获取 QTextEdit默认字体的字体度量
    qDebug() << fm.averageCharWidth();      // 字体度量的平均宽度

    qDebug() << doc->indentWidth();                 // 察看文档默认的缩进宽度  40
    doc->setIndentWidth(fm.averageCharWidth()*2);     // 设置2个字符的宽度为缩进宽度
    blockFormat.setIndent(2);            //段落的整体实际缩进 = 2 * 文档范围的标准缩进相乘

    blockFormat.setTextIndent(fm.averageCharWidth()*2);    //文本块首行缩进
    cursor.setBlockFormat(blockFormat);  //设置光标所在段落的文本块格式

    /* 设置段落的背景色*/
    blockFormat.setBackground(Qt::red);
    cursor.insertBlock(blockFormat);
    cursor.insertText("The QTextBlock class provides a container for text fragments in a QTextDocument.");
}

总结

  QTextBlock文本块其实际的含义和段落是一个概念。没有太多复杂的东西，同时本身又是一个文本片段的容器，所以文本的迭代器针对的是其内部的文本片段。