QPlainTextEdit

一、描述

此类继承自 QAbstractScrollArea，提供了一个用于编辑和显示纯文本的小部件。它经过优化，可以处理大型文档并对用户输入做出快速响应。

QPlainTextEdit 适用于段落和字符。段落是一个格式化的字符串，它会自动换行以适应小部件的宽度。默认情况下，当阅读纯文本时，一个段落后有一个换行符。文档多个段落组成。段落中的每个字符都有自己的属性，例如字体和颜色。

1.1、编辑快捷键

• Backspace：删除光标左侧的字符。
• Delete：删除光标右侧的字符。
• Ctrl+C：将所选文本复制到剪贴板。
• Ctrl+Insert：将所选文本复制到剪贴板。
• Ctrl+K：删除到行尾。
• Ctrl+V：将剪贴板文本粘贴到文本编辑中。
• Shift+Insert：将剪贴板文本粘贴到文本编辑中。
• Ctrl+X：删除选定的文本并将其复制到剪贴板。
• Shift+Delete：删除选定的文本并将其复制到剪贴板。
• Ctrl+Z：撤消上一个操作。
• Ctrl+Y：回撤上一个操作。
• LeftArrow：将光标向左移动一个字符。
• Ctrl+LeftArrow：将光标向左移动一个单词。
• RightArrow：将光标向右移动一个字符。
• Ctrl+RightArrow：将光标向右移动一个单词。
• UpArrow：将光标向上移动一行。
• Ctrl+UpArrow：将光标向上移动一个单词。
• DownArrow：将光标向下移动一行。
• Ctrl+DownArrow：将光标向下移动一个单词。
• PageUp：将光标向上移动一页。
• PageDown：将光标向下移动一页。
• Home：将光标移动到行首。
• Ctrl+Home：将光标移动到文本的开头。
• End：将光标移动到行尾。
• Ctrl+End：将光标移动到文本的末尾。
• Alt+Wheel：水平滚动页面。
• Ctrl+Wheel：缩放文本。

二、类型成员

1、enum QPlainTextEdit::LineWrapMode：换行模式。

• NoWrap：在单词中间换行。
• WidgetWidth：使单词在文本编辑的右边缘进行换行。换行发生在空白处，使整个单词保持完整。

三、属性成员

1、backgroundVisible : bool

此属性确定调色板背景在文档区域外是否可见。默认为 false。

2、[read-only] blockCount : const int

文档中的文本块数。默认在空文档中，此属性值为1。

3、centerOnScroll : bool

光标是否应在屏幕上居中。默认值为false。

设置为true，则将垂直滚动文档，使光标在视口中心可见。这也允许文本编辑滚动到文档末尾下方。设置为false，则将滚动尽可能小的量，以确保光标可见。

设置为true：

设置为false：

3、cursorWidth : int

以像素为单位指定光标的宽度。默认值为1。

设置为60：

4、documentTitle : QString

从文本解析的文档的标题。

5、lineWrapMode : LineWrapMode

换行模式。

6、maximumBlockCount : int

指定文档可具有的最大块数。超出此值会从文档的开头删除块。

负值或零值指定文档可能包含无限量的块。默认值为0。

设置此属性将立即对文档内容应用限制。设置此属性还将禁用撤消回撤历史记录。

7、overwriteMode : bool

当鼠标光标不在文本块末尾时，用户输入的文本是否覆盖现有文本。默认为false。

如果为 true ，则现有文本将被新文本逐个字符覆盖。

8、placeholderText : QString

编辑器内容为空时显示的描述文本。如“请输入内容...”此类文本。

9、plainText : QString

内容文本。

10、readOnly : bool

是否为只读，默认值为 false。

11、tabChangesFocus : bool

设置为 true 则按下 Tab 键不是输入一个制表符而是更改输入焦点为其他控件。默认值为false。

12、tabStopDistance : qreal

制表符的长度。默认为80像素。

设置为180：

13、textInteractionFlags : Qt::TextInteractionFlags

在显示文本时应如何与用户输入交互。默认值取决于此小部件是只读的还是可编辑的。

Qt::TextInteractionFlag：

• Qt::NoTextInteraction：不与文本交互。
• Qt::TextSelectableByMouse：可以使用鼠标选择文本并使用上下文菜单或快捷键将文本复制到剪贴板。
• Qt::TextSelectableByKeyboard：可以使用键盘上的光标键选择文本。显示文本光标。
• Qt::LinksAccessibleByMouse：可以用鼠标突出显示和激活链接。
• Qt::LinksAccessibleByKeyboard：链接可以使用 tab 聚焦并使用 enter 激活。
• Qt::TextEditable：文本可编辑。
• Qt::TextEditorInteraction：TextSelectableByMouse | TextSelectableByKeyboard | TextEditable
• Qt::TextBrowserInteraction：TextSelectableByMouse | LinksAccessibleByMouse | LinksAccessibleByKeyboard

14、undoRedoEnabled : bool

是否启用撤消和回撤。默认为 true。

15、wordWrapMode : QTextOption::WrapMode

在按单词换行文本时使用的模式。默认为 WrapAtWordBoundaryOrAnywhere。

enum QTextOption::WrapMode：

• NoWrap：文本不换行。
• WordWrap：文本在单词边界处换行。
• ManualWrap：与 NoWrap 相同。
• wrapany：文本可以在一行上的任何位置进行换行。
• WrapAtWordBoundaryOrAnywhere：如果可能，在单词边界处进行换行；否则在行的任何适当位置进行换行。

四、成员函数

1、void appendHtml(const QString &html)

在末尾添加一个带有html的新段落。

2、 void appendPlainText(const QString &text)

在文本编辑的末尾添加一个新段落和文本。

3、【信号】void blockCountChanged(int newBlockCount)

每当文本块数目改变时，就会发出该信号。

4、void centerCursor()

滚动文档以使光标垂直居中。

5、void clear()

删除文本编辑中的所有文本。撤消/回撤历史记录也被清除。

6、void copy()

将选定文本复制到剪贴板。

7、【信号】void copyAvailable(bool yes)

当选择或取消选择文本时，会发出此信号。参数为是否选择了文本

如果 yes 为 true，则可以使用 copy() 将所选内容复制到剪贴板。

8、【信号】void cursorPositionChanged()

光标的位置发生变化时发出该信号。

9、void cut()

将所选文本复制到剪贴板并从文本编辑中删除。

10、void insertPlainText(const QString &text)

在当前光标位置插入文本。

等同于：

edit->textCursor().insertText(text);

11、【信号】void modificationChanged(bool changed)

每当文档内容以影响修改状态的方式改变时，就会发出此信号。

12、void paste()

将剪贴板中的文本粘贴到当前光标位置。

要更改此函数的行为，即修改 QPlainTextEdit 可以粘贴的内容及其粘贴方式，可重新实现虚函数canInsertFromMimeData() 和 insertFromMimeData()。

示例：实现复制一个文件路径到编辑框，编辑框自动读取文件内容并展示。

#ifndef MYPLAINTEXTEDIT_H
#define MYPLAINTEXTEDIT_H
 
#include 
 
class MyPlainTextEdit : public QPlainTextEdit
{
    Q_OBJECT
public:
    MyPlainTextEdit(QWidget *parent = nullptr);
 
protected:
    bool canInsertFromMimeData(const QMimeData *source) const override;
    void insertFromMimeData(const QMimeData *source) override;
};
 
#endif // MYPLAINTEXTEDIT_H

#include "myplaintextedit.h"
#include 
#include 
 
MyPlainTextEdit::MyPlainTextEdit(QWidget *parent):
    QPlainTextEdit(parent)
{
}
 
bool MyPlainTextEdit::canInsertFromMimeData(const QMimeData *source) const
{
    return source->hasText();
}
 
void MyPlainTextEdit::insertFromMimeData(const QMimeData *source)
{
    QFile file(source->text());
    if(file.exists())
    {
        if(file.open(QFile::ReadOnly))
        {
            auto data = file.readAll();
            this->setPlainText(data);
            file.close();
        }
    }
}

13、void undo() / void redo()

撤销/回撤上次操作。

14、【信号】void undoAvailable(bool available) / 【信号】void redoAvailable(bool available)

每当 撤销/回撤 操作变化时，可用（available为 true）或不可用（available是 false）时，就会发出此信号。

15、void selectAll()

选中所有文本。

16、void selectionChanged()

只要选择内容发生变化，就会发出此信号。

17、【信号】void updateRequest(const QRect &rect, int dy)

内容发生变化（包括光标在编辑器内闪烁时）时会发送此信号。

rect 是重绘的区域，dy就是滚动的垂直方向的像素值。

18、void zoomIn(int range = 1) / void zoomOut(int range = 1)

通过增大减小字体的大小来缩放文本。

19、QString anchorAt(const QPoint &pos)

返回位置 pos 处锚点的引用的文本。

20、QRectF blockBoundingGeometry(const QTextBlock &block)

以文本内容坐标返回文本块的边框。

21、QRectF blockBoundingRect(const QTextBlock &block)

返回文本块在其自身坐标中的边界矩形。

22、bool canInsertFromMimeData(const QMimeData *source)

source 指定的MIME数据对象的内容是否可以解码并插入到文档中。

例如，当在拖动操作过程中，鼠标进入该小部件，并且需要确定是否可以接受拖动时，就会调用此函数。

23、bool canPaste()

返回文本是否可以从剪贴板粘贴到文本编辑中。

24、QPointF contentOffset()

以视口坐标返回内容的原点。内容的原点始终位于第一个可见文本块的左上角。

25、void contextMenuEvent(QContextMenuEvent *event)

显示使用 createStandardContextMenu() 创建的标准上下文菜单。

如果要自定义上下文菜单，可重新实现此功能。

如果要扩展标准上下文菜单，可重新实现此函数，并调用 createStandardContextMenu() 并扩展返回的菜单。

扩展标准上下文菜单：

26、QMimeData * createMimeDataFromSelection()

此函数返回一个新的MIME数据对象，以表示文本编辑当前选择的内容。当选择需要封装到新的 QMimeData 对象中时将调用该函数。例如，当开始拖放操作或将数据复制到剪贴板时。

如果重新实现此函数，注意将返回的 QMimeData 对象的所有权将传递给调用者。可以使用textCursor() 函数检索所选内容。

27、QMenu * createStandardContextMenu()

        QMenu * createStandardContextMenu(const QPoint &position)

此函数用于创建标准上下文菜单，当用户用鼠标右键单击文本编辑时显示该菜单。

此函数在默认的 contextMenuEvent() 处理程序中调用。弹出菜单的所有权转移给调用者。

28、QTextCharFormat currentCharFormat()

当前字符格式，即插入新文本时使用的字符格式。

29、QTextCursor cursorForPosition(const QPoint &pos)

返回视口坐标 pos 的 QTextCursor。

30、QRect cursorRect()

返回包含文本编辑光标的矩形（在视口坐标中）。

31、void ensureCursorVisible()

如有必要，通过滚动滚动条来确保光标可见。

32、bool find(const QString &exp, QTextDocument::FindFlags options = QTextDocument::FindFlags())

       bool find(const QRegularExpression &exp, QTextDocument::FindFlags options = QTextDocument::FindFlags())

使用给定的选项查找字符串 exp 的下一个匹配项。如果找到则返回 true，并更改光标以选择匹配项；找不到则返回 false。

33、QTextBlock firstVisibleBlock()

返回第一个可见块。

34、void insertFromMimeData(const QMimeData *source)

此函数用于将 source 指定的MIME数据对象的内容插入到当前光标位置。每当由于剪贴板粘贴操作而插入文本时，或者当文本编辑接受拖放操作的数据时，都会调用该函数。

35、QVariant loadResource(int type, const QUrl &name)

加载指定的资源。此函数是 QTextDocument::loadResource() 的扩展。

36、void mergeCurrentCharFormat(const QTextCharFormat &modifier)

通过在编辑器光标上调用 QTextCursor::mergeCharFormat()，将 modifier 中指定的属性合并为当前字符格式。如果当前有选择内容，则 modifier 的属性将直接应用于该内容。

37、void moveCursor(QTextCursor::MoveOperation operation, QTextCursor::MoveMode mode = QTextCursor::MoveAnchor)

通过执行给定操作移动光标。

enum QTextCursor::MoveOperation：

• QTextCursor::NoMove：将光标保持在原位
• QTextCursor::Start：移动到文档的开头。
• QTextCursor::StartOfLine：移动到当前行的开头。
• QTextCursor::StartOfBlock：移动到当前块的开头。
• QTextCursor::StartOfWord：移动到当前单词的开头。
• QTextCursor::PreviousBlock：移动到上一个块的开头。
• QTextCursor::PreviousCharacter：移动到上一个字符。
• QTextCursor::PreviousWord：移动到上一个单词的开头。
• QTextCursor::Up：向上移动一行。
• QTextCursor::Left：向左移动一个字符。
• QTextCursor::WordLeft：向左移动一个单词。
• QTextCursor::End：移动到文档末尾。
• QTextCursor::EndOfLine：移动到当前行的末尾。
• QTextCursor::EndOfWord：移动到当前单词的末尾。
• QTextCursor::EndOfBlock：移动到当前块的末尾。
• QTextCursor::NextBlock：移动到下一个块的开头。
• QTextCursor::NextCharacter：移动到下一个字符。
• QTextCursor::NextWord：移动到下一个单词。
• QTextCursor::Down：向下移动一行。
• QTextCursor::Right：向右移动一个字符。
• QTextCursor::WordRight：向右移动一个单词。
• QTextCursor::NextCell：移动到当前单元格的下一个单元格的开头。如果当前单元格是行中的最后一个单元格，光标将移动到下一行的第一个单元格。
• QTextCursor::PreviousCell：移动到当前单元格的上一个单元格的开头。如果当前单元格是行中的第一个单元格，光标将移动到前一行中的最后一个单元格。
• QTextCursor::NextRow：移动到当前单元格的下一行的第一个新单元格。
• QTextCursor::PreviousRow：移动到当前单元格的上一行的最后一个单元格。

enum QTextCursor::MoveMode：

• QTextCursor::MoveAnchor：将锚点移动到与光标本身相同的位置。
• QTextCursor::KeepAnchor：保持锚点的位置。

38、void print(QPagedPaintDevice *printer)

将文本编辑的文档打印到给定打印机的便捷功能。这相当于直接调用文档上的打印方法，只是此函数还支持将 QPrinter::Selection 作为打印范围。

39、void setCurrentCharFormat(const QTextCharFormat &format)

在编辑器光标上调用 QTextCursor::setCharFormat()，设置插入的新文本时使用的字符格式。如果编辑器此时选择了内容，那么字符格式将直接应用于该内容。

40、void setExtraSelections(const QList &selections)

使用指定格式临时标记文档中的某些区域。

    QList selections;
 
    QTextEdit::ExtraSelection extra1;
    extra1.format.setBackground(Qt::red);
    extra1.cursor = ui->plainTextEdit->textCursor();
 
    selections << extra1;
 
    QTextEdit::ExtraSelection extra2;
    extra2.format.setBackground(Qt::green);
    QTextCursor currentCursor(ui->plainTextEdit->textCursor());//光标副本
    currentCursor.movePosition(QTextCursor::Down,QTextCursor::KeepAnchor);//向下一行移动
    currentCursor.select(QTextCursor::LineUnderCursor);//选中这行
    ui->plainTextEdit->setTextCursor(currentCursor);
    extra2.cursor = ui->plainTextEdit->textCursor();
 
    selections << extra2;
 
    ui->plainTextEdit->setExtraSelections(selections);

41、void setTextCursor(const QTextCursor &cursor) / QTextCursor textCursor()

返回表示当前可见光标的QTextCursor的副本。对返回光标的更改不会影响 QPlainTextEdit 的光标。