Qt例子学习笔记 - Examples/Qt-6.2.0/assistant/simpletextviewer

main.cpp

#include "mainwindow.h"

#include 
//QApplication 专门为 QGuiApplication 提供了一些基于 QWidget 的应用程序所需的功能。
// 它处理特定于小部件的初始化、完成。
//对于任何使用 Qt 的 GUI 应用程序，无论应用程序在任何给定时间是否有 0、1、2 或更多窗口，
//都恰好有一个 QApplication 对象。
//对于非基于 QWidget 的 Qt 应用程序，请改用 QGuiApplication，因为它不依赖于 QtWidgets 库。
//一些 GUI 应用程序提供了一种特殊的批处理模式，即。
//提供命令行参数，无需人工干预即可执行任务。
//在这种非 GUI 模式下，实例化一个普通的 QCoreApplication 通常就足够了，
//以避免不必要地初始化图形用户界面所需的资源。
//以下示例显示了如何动态创建适当类型的应用程序实例：
/*
QCoreApplication* createApplication(int &argc,char *argv[])
{
    for(int i = 1;i < argc; ++i)
    {
        if(!qstrcmp(argv[i],"-no-gui"))
            return new QCoreApplication(argc,argv);
    }
    return new QApplication(argc,argv);
}

int main(int argc,char *argv[])
{
    QScopedPointer app(createApplication(argc,argv));

    if(qobject_cast(app.data()))
    {
        //start GUI version
    }
    else
    {
        //start non-GUI version
    }
    return app->exec();
}
*/
//QApplication 对象可通过 instance() 函数访问，该函数返回等效于全局 qApp 指针的指针。
//QApplication 的主要职责范围是：
//它使用用户的桌面设置初始化应用程序，例如palette()、font() 和doubleClickInterval()。
//它会跟踪这些属性，以防用户全局更改桌面，例如通过某种控制面板。
//它执行事件处理，这意味着它从底层窗口系统接收事件并将它们分派给相关的小部件。
//通过使用 sendEvent() 和 postEvent()，您可以将自己的事件发送到小部件。
//它解析常见的命令行参数并相应地设置其内部状态。 有关更多详细信息，请参阅下面的构造函数文档。
//它定义了应用程序的外观和感觉，它被封装在一个 QStyle 对象中。
//这可以在运行时使用 setStyle() 进行更改。
//它通过 translate() 提供对用户可见的字符串的本地化。
//它提供了一些神奇的对象，比如 clipboard()。
//它知道应用程序的窗口。您可以使用 widgetAt() 询问哪个小部件位于某个位置，
//获取 topLevelWidgets() 和 closeAllWindows() 等列表。
//它管理应用程序的鼠标光标处理，参见 setOverrideCursor()
//由于 QApplication 对象进行了如此多的初始化，因此必须在创建与用户界面相关的任何其他对象之前创建它。
//QApplication 还处理常见的命令行参数。
//因此，在应用程序本身对 argv 进行任何解释或修改之前创建它通常是一个好主意。
//Groups of functions
//系统设置
/*
desktopSettingsAware(), 
setDesktopSettingsAware(), 
cursorFlashTime(), 
setCursorFlashTime(), 
doubleClickInterval(), 
setDoubleClickInterval(), 
setKeyboardInputInterval(), 
wheelScrollLines(), 
setWheelScrollLines(), 
palette(), setPalette(), 
font(), setFont(), fontMetrics().
*/
//事件处理
/*
exec(), 
processEvents(), 
exit(), 
quit(). 
sendEvent(), 
postEvent(), 
sendPostedEvents(), 
removePostedEvents(), notify().
*/

//GUI styles
/*
style(), setStyle().
*/

//文本处理
/*
installTranslator(), removeTranslator() translate().
*/
//Widgets

/*
allWidgets(), 
topLevelWidgets(), 
activePopupWidget(), 
activeModalWidget(), 
clipboard(), 
focusWidget(), 
activeWindow(), 
widgetAt().
*/

//Advanced cursor handling
/*
overrideCursor(), setOverrideCursor(), restoreOverrideCursor().
*/

//这个例子展示了如何在自定义应用程序中使用 Qt Assistant 作为自定义帮助查看器。
//这是分两个阶段完成的。
//首先创建文档，定制Qt助手；
//其次，在应用程序中添加了启动和控制 Qt 助手的功能。
//该示例由四个类组成：
//Assistant 提供了启动 Qt Assistant 的功能。
//MainWindow 是主应用程序窗口。
//FindFileDialog 允许用户使用通配符匹配来搜索文件。
//TextEdit 提供了一个富文本浏览器，可确保 HTML 文档中引用的图像正确显示。
//注意：我们只会评论与主要问题相关的实现部分，即让 Qt Assistant 充当我们的 Simple Text Viewer 应用程序的自定义帮助查看器。
int main(int argc, char *argv[])
{
    QApplication app(argc, argv);
    MainWindow window;
    window.show();
    return app.exec();
}

mainwindow.h

#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include 

//在应用程序中，可以通过菜单、工具栏按钮和键盘快捷键调用许多常用命令。
//由于用户希望每个命令都以相同的方式执行，而不管使用的用户界面如何，将每个命令表示为一个动作是很有用的。
//操作可以添加到菜单和工具栏，并自动保持同步。
//例如，在文字处理器中，如果用户按下粗体工具栏按钮，粗体菜单项将被自动选中。
//QAction 可能包含图标、菜单文本、快捷方式、状态文本、“这是什么？” 文本和工具提示。
//其中大部分可以在构造函数中设置。 它们也可以通过 
//setIcon()、setText()、setIconText()、setShortcut()、
//setStatusTip()、setWhatsThis() 和 setToolTip() 独立设置。 
//对于菜单项，可以使用 setFont() 设置单独的字体。

//我们建议将操作创建为使用它们的窗口的子项。在大多数情况下，操作将是应用程序主窗口的子项。

//小部件应用程序中的 QAction
//创建 QAction 后，应将其添加到相关菜单和工具栏，然后连接到将执行操作的槽。 例如：
/*
    const QIcon openIcon = QIcon::fromTheme("document-open",QIcon(":/images/open.png"))
    QAction *openAct = new QAction(openIcon,tr("&Open..."),this);
    openAct->setShortcuts(QKeySequence::Open);
    openAct->setStatusTip(tr("Open an existing file"));
    connect(openAct,&QAction::triggered,this,&MainWindow::open);
    fileMenu->addAction(openAct);
    fileToolBar->addAction(openAct);
*/
//使用 QWidget::addAction() 或 QGraphicsWidget::addAction() 将Action添加到小部件。
//。 请注意，操作必须先添加到小部件才能使用。
//当快捷方式应该是全局的（即 Qt::ApplicationShortcut 作为 Qt::ShortcutContext）时，这也是正确的。
//动作可以创建为独立的对象。
//但它们也可能是在构建菜单期间创建的。
//QMenu 类包含用于创建适合用作菜单项的操作的函数。

//菜单小部件是一个选择菜单。
//它可以是菜单栏中的下拉菜单，也可以是独立的上下文菜单。
//当用户单击相应的项目或按下指定的快捷键时，菜单栏会显示下拉菜单。
//使用 QMenuBar::addMenu() 将菜单插入菜单栏中
//上下文菜单通常由一些特殊的键盘键或右键单击来调用。
//它们可以与 popup() 异步执行，也可以与 exec() 同步执行。
//菜单也可以响应按钮按下而被调用； 这些就像上下文菜单，只是它们的调用方式不同。

//Actions
//菜单由一系列操作项组成。使用 addAction()、addActions() 和 insertAction() 函数添加动作。
//一个动作垂直表示并由 QStyle 呈现。
//此外，动作可以有一个文本标签，一个在最左侧绘制的可选图标，以及诸如“Ctrl+X”之类的快捷键序列。
//可以使用 actions() 找到菜单所包含的现有操作。
//有四种操作项：分隔符、显示子菜单的操作、小部件和执行操作的操作。
//分隔符使用 addSeparator() 插入，子菜单使用 addMenu() 插入，所有其他项都被视为操作项。
//插入操作项时，您通常指定接收器和插槽。
//每当项目被触发（）时，接收者都会收到通知。
//此外，QMenu 提供了两个信号，triggered() 和 hovered()，它们表示从菜单触发的 QAction。
//您可以使用 clear() 清除菜单并使用 removeAction() 删除单个操作项。
//QMenu 还可以提供 tear-off 菜单。  tear-off 菜单是包含菜单副本的顶级窗口。
//这使得用户可以“tear off”经常使用的菜单并将它们放置在屏幕上方便的位置。
//如果您想要特定菜单的此功能，请使用 setTearOffEnabled() 插入tear-off的句柄。
//可以使用 QWidgetAction 类将小部件插入菜单中。
//此类的实例用于保存小部件，并通过采用 QAction 的 addAction() 重载插入菜单。
//如果 QWidgetAction 触发了 trigger() 信号，菜单将关闭。


QT_BEGIN_NAMESPACE
class QAction;
class QMenu;
QT_END_NAMESPACE

class Assistant;
class TextEdit;

class MainWindow : public QMainWindow
{
    Q_OBJECT

public:
    MainWindow();

private slots:
    void about();
    void showDocumentation();
    void open();

protected:
    void closeEvent(QCloseEvent *event) override;

private:
    void createActions();
    void createMenus();

    Assistant *assistant;
    TextEdit *textViewer;

    QMenu *fileMenu;
    QMenu *helpMenu;

    QAction *assistantAct;
    QAction *clearAct;
    QAction *openAct;
    QAction *exitAct;
    QAction *aboutAct;
    QAction *aboutQtAct;
};

#endif

mainwindow.cpp

#include "assistant.h"
#include "findfiledialog.h"
#include "mainwindow.h"
#include "textedit.h"

#include 
#include 
#include 
#include 
#include 
#include 

//MainWindow 类为应用程序主窗口提供两个菜单：
//文件菜单让用户打开和查看现有文件，
//而帮助菜单提供有关应用程序和 Qt 的信息，
//并让用户打开 Qt 助手以显示应用程序的文档 .
//为了能够访问帮助功能，我们在 MainWindow 的构造函数中初始化 Assistant 对象。
MainWindow::MainWindow()
{
    assistant = new Assistant;
// ![0]
    textViewer = new TextEdit;
    //[static, since 6.0] QString QLibraryInfo::path(QLibraryInfo::LibraryPath p)
    //返回由 p 指定的路径。    
    //QLibraryInfo::ExamplesPath 安装时示例的路径。
    //QLatin1String 许多 QString 的成员函数被重载以接受 const char * 而不是 QString。
    //这包括复制构造函数、赋值运算符、比较运算符以及各种其他函数，
    //例如 insert()、replace() 和 indexOf()。
    //这些函数通常经过优化，以避免为 const char * 数据构造 QString 对象。
    //例如，假设 str 是一个 QString，
    /*
        if(str == "auto" || str == "extern"
            ||str == "static"||str == "register")
            {
                ...
            }
            //is much faster than
        if(str == QString("auto") || str == QString("extern")
            ||str == QString("static") || str == QString("register"))
        {
    
        }
    */
    //因为它没有构造四个临时 QString 对象并对字符数据进行深拷贝。
    //定义 QT_NO_CAST_FROM_ASCII 的应用程序（如 QString 文档中所述）无权访问 QString 的 const char * API。
    //为了提供一种指定常量 Latin-1 字符串的有效方法，
    //Qt 提供了 QLatin1String，它只是一个非常薄的 const char * 包装器。
    //使用QLatin1String，上面的示例代码变成
    /*
        if(str == QLatin1String("auto")
            ||str ==  QLatin1String("extern")
            ||str ==  QLatin1String("static")
            ||str ==  QLatin1String("register"))
        {}
    */
    //这输入的时间有点长，但它提供了与代码的第一个版本完全相同的好处，
    //并且比使用 QString::fromLatin1() 转换 Latin-1 字符串更快。
    //多亏了 QString(QLatin1String) 构造函数，
    //QLatin1String 可以在任何需要 QString 的地方使用。 例如：
    //QLabel *label = new QLabel(QLatin1String("MOD"),this);
    //注意：如果您使用 QLatin1String 参数调用的函数实际上并未重载以采用 QLatin1String
    //则隐式转换为 QString 将触发内存分配，这通常是您首先要使用 QLatin1String 避免的情况。
    //在这些情况下，使用 QStringLiteral 可能是更好的选择。


    textViewer->setContents(QLibraryInfo::path(QLibraryInfo::ExamplesPath)
            + QLatin1String("/assistant/simpletextviewer/documentation/intro.html"));
    //void QMainWindow::setCentralWidget(QWidget *widget)
    //将给定的小部件设置为主窗口的中央小部件。
    //注意： QMainWindow 获得小部件指针的所有权并在适当的时候将其删除。
    setCentralWidget(textViewer);

    createActions();
    createMenus();
    //此属性保存窗口标题（标题）
    //此属性仅对顶级小部件有意义，例如窗口和对话框。
    //如果未设置标题，则标题基于 windowFilePath。
    //如果这些都没有设置，则标题是一个空字符串。
    setWindowTitle(tr("Simple Text Viewer"));
    resize(750, 400);
// ![1]
}
//! [1]

//最后，我们必须重新实现受保护的 QWidget::closeEvent() 事件处理程序，
//以确保在终止应用程序之前正确关闭应用程序的 Qt Assistant 实例。
void MainWindow::closeEvent(QCloseEvent *)
{
    delete assistant;
}

void MainWindow::about()
{
    QMessageBox::about(this, tr("About Simple Text Viewer"),
                       tr("This example demonstrates how to use\n"
                          "Qt Assistant as help system for your\n"
                          "own application."));
}

//在 showDocumentation() 槽中，我们使用文档主页的 
//URL 调用 Assistant 类的 showDocumentation() 函数。
void MainWindow::showDocumentation()
{
    assistant->showDocumentation("index.html");
}

void MainWindow::open()
{
    FindFileDialog dialog(textViewer, assistant);
    dialog.exec();
}

//然后我们为 Simple Text Viewer 应用程序创建所有操作。
//特别感兴趣的是可以通过 F1 快捷方式或帮助 > 帮助目录菜单项访问的assistantAct 操作。
//此操作连接到 MainWindow 类的 showDocumentation() 槽。
void MainWindow::createActions()
{
    assistantAct = new QAction(tr("Help Contents"), this);
    assistantAct->setShortcut(QKeySequence::HelpContents);
    connect(assistantAct, &QAction::triggered, this, &MainWindow::showDocumentation);

    openAct = new QAction(tr("&Open..."), this);
    openAct->setShortcut(QKeySequence::Open);
    connect(openAct, &QAction::triggered, this, &MainWindow::open);

    clearAct = new QAction(tr("&Clear"), this);
    clearAct->setShortcut(tr("Ctrl+C"));
    connect(clearAct, &QAction::triggered, textViewer, &QTextEdit::clear);

    exitAct = new QAction(tr("E&xit"), this);
    exitAct->setShortcuts(QKeySequence::Quit);
    connect(exitAct, &QAction::triggered, this, &QWidget::close);

    aboutAct = new QAction(tr("&About"), this);
    connect(aboutAct, &QAction::triggered, this, &MainWindow::about);

    aboutQtAct = new QAction(tr("About &Qt"), this);
    connect(aboutQtAct, &QAction::triggered, QApplication::aboutQt);
//! [5]
}
//! [5]

void MainWindow::createMenus()
{
    fileMenu = new QMenu(tr("&File"), this);
    fileMenu->addAction(openAct);
    fileMenu->addAction(clearAct);
    fileMenu->addSeparator();
    fileMenu->addAction(exitAct);

    helpMenu = new QMenu(tr("&Help"), this);
    helpMenu->addAction(assistantAct);
    helpMenu->addSeparator();
    helpMenu->addAction(aboutAct);
    helpMenu->addAction(aboutQtAct);


    menuBar()->addMenu(fileMenu);
    menuBar()->addMenu(helpMenu);
}

textedit.h

#ifndef TEXTEDIT_H
#define TEXTEDIT_H

#include 
#include 

class TextEdit : public QTextEdit
{
    Q_OBJECT

public:
    TextEdit(QWidget *parent = nullptr);
    void setContents(const QString &fileName);

private:
    //QVariant 由于 C++ 禁止联合包含具有非默认构造函数或析构函数的类型，
    //因此大多数有趣的 Qt 类不能在unions中使用。
    //如果没有 QVariant，这对于 QObject::property() 和数据库工作等来说将是一个问题。
    //QVariant 对象一次保存一个 typeId() 的单个值。 
    //（某些类型是多值的，例如字符串列表。）
    //您可以找出变体包含的类型 T，
    //使用 convert() 将其转换为其他类型，
    //使用 toT() 函数之一获取其值 （例如，toSize()），
    //并检查是否可以使用 canConvert() 将类型转换为特定类型。
    //名为 toT() 的方法（例如，toInt()、toString()）是常量。
    //如果您要求存储类型，它们将返回存储对象的副本。
    //如果您要求可以从存储的类型生成的类型， toT() 会复制并转换对象本身并保持不变。
    //如果您要求的类型无法从存储的类型中生成，则结果取决于类型； 有关详细信息，请参阅函数文档。
    //下面是一些示例代码来演示 QVariant 的使用：
    /*
        QDataStream out(...);
        QVariant v(123);  变体现在包含一个 int
        int x = v.toInt(); //x = 123
        out<> v;  读取一个 Int 变量
        int z = v.toInt(); //z = 123
        qDebug("Type is %s",v.typeName());
        v = v.toInt() + 100; //The Variant now holds the value 223
        v = QVariant(QStringList()); //The variant now holds a QStrringList
    */
    //您甚至可以将 QList 和 QMap 值存储在一个变体中，
    //，因此您可以轻松构建任意类型的任意复杂的数据结构。
    //这是非常强大和通用的，但可能比在标准数据结构中存储特定类型的内存和速度效率低。
    //QVariant 还支持空值的概念。
    //如果变体不包含初始化值或包含空指针，则变体为空。
    /*
        QVariant x; // x.isNull() == true
        QVariant y = QVariant::fromValue(nullptr); // y.isNull() == true
       //QVariant 可以扩展以支持 QMetaType::Type 枚举中提到的类型之外的其他类型。 有关详细信息，请参阅创建自定义 Qt 类型。 
    */
    //关于 GUI 类型的说明
    //由于 QVariant 是 Qt Core 模块的一部分，
    //因此无法提供 Qt GUI 中定义的数据类型的转换功能，
    //例如 QColor、QImage 和 QPixmap。
    //换句话说，没有 toColor() 函数。
    //相反，您可以使用 QVariant::value() 或 qvariant_cast() 模板函数。 例如：
    /*
        QVariant variant;
        QColor color = variant.value();
    */

    //对于 QVariant 支持的所有数据类型，包括 GUI 相关类型，逆转换（例如，从 QColor 到 QVariant）是自动的：
    /*
        QColor color = palette().backgroud().color();
        QVariant variant = color;
    */

    QVariant loadResource(int type, const QUrl &name) override;
    QUrl srcUrl;
};

#endif

textedit.cpp

#include "textedit.h"

#include 
#include 
//QTextEdit 是一个先进的 WYSIWYG 查看器/编辑器，支持使用 HTML 样式标签或 
//Markdown 格式的富文本格式。 它经过优化，可处理大型文档并快速响应用户输入。
//QTextEdit 适用于段落和字符。
//一个段落是一个格式化的字符串，它被自动换行以适应小部件的宽度。
//默认情况下，阅读纯文本时，换行符表示一个段落。
//一个文档由零个或多个段落组成。 段落中的单词按照段落的对齐方式对齐。
//段落由硬换行符分隔。 段落中的每个字符都有自己的属性，例如字体和颜色。


//QTextEdit 可以显示图像、列表和表格。
//如果文本太大而无法在文本编辑的视口中查看，则会出现滚动条。
//文本编辑可以加载纯文本和富文本文件。
//可以使用 HTML 4 标记的子集来描述富文本； 有关更多信息，请参阅支持的 HTML 子集页面。
//如果您只需要显示一小段富文本，请使用 QLabel。
//Qt 中的富文本支持旨在提供一种快速、可移植和
//高效的方式来向应用程序添加合理的在线帮助工具，并为富文本编辑器提供基础。
//如果您发现 HTML 支持不足以满足您的需求，
//您可以考虑使用 Qt WebKit，它提供了一个全功能的 Web 浏览器小部件。
//QTextEdit 上鼠标光标的形状默认为 Qt::IBeamCursor。
//它可以通过 viewport() 的 cursor 属性进行更改。
//使用 QTextEdit 作为显示小部件
//QTextEdit 可以显示一个大的 HTML 子集，包括表格和图像。
//可以使用 setHtml() 设置或替换文本，它会删除任何现有文本并将其替换为在 setHtml() 调用中传递的文本。
//如果您使用旧版 HTML 调用 setHtml()，然后调用 toHtml()，则返回的文本可能具有不同的标记，但会呈现相同的内容。
//可以使用 clear() 删除整个文本。
//也可以使用 setMarkdown() 设置或替换文本，同样的警告也适用：
//如果您随后调用 toMarkdown()，返回的文本可能会有所不同，
//但会尽可能保留其含义。
//可以解析带有一些嵌入 HTML 的 Markdown，具有与 setHtml() 相同的限制；
//但是 toMarkdown() 只写“纯”的 Markdown，没有任何嵌入的 HTML。
//可以使用 QTextCursor 类或使用便利函数 insertHtml()、
//insertPlainText()、append() 或 paste() 插入文本本身。
//QTextCursor 还能够将复杂的对象（如表格或列表）插入到文档中
//并处理创建选择并将更改应用于所选文本。
//默认情况下，文本编辑在空格处包装单词以适合文本编辑小部件。
//setLineWrapMode() 函数用于指定您想要的换行类型，如果您不想要任何换行，则使用 NoWrap。
//调用 setLineWrapMode() 以设置固定像素宽度 FixedPixelWidth 或字符列（例如 80 列）
//FixedColumnWidth 与 setLineWrapColumnOrWidth() 指定的像素或列。
//如果您对小部件的宽度 WidgetWidth 使用自动换行
//您可以使用 setWordWrapMode() 指定是在空白处还是在任何地方换行。
//find() 函数可用于在文本中查找和选择给定的字符串。
//如果您想限制 QTextEdit 中的段落总数
//例如它在日志查看器中通常很有用
//那么您可以使用 QTextDocument 的 maximumBlockCount 属性。
//只读键绑定
//当 QTextEdit 以只读方式使用时，键绑定仅限于导航，并且只能使用鼠标选择文本：
// UpMoves 向上移动一行。
// DownMoves 向下移动一行。
// Left 向左移动一个字符。
// Right 向右移动一个字符。
// PageUp 向上移动一页（视口）。
// PageDown 向下移动一页（视口）。
// Home移动到文本的开头。
// EndMoves 到文本的结尾。
// Alt+Wheel 水平滚动页面（Wheel 是鼠标滚轮）。
// Ctrl+滚轮缩放文本。
// Ctrl+A 选择所有文本。
//文本编辑可能能够提供一些元信息。 
//例如，documentTitle() 函数将返回 HTML