QT6 源，七章对话框与多窗体（3） 对话框 QDialog：本类的槽函数，信号函数以及源代码带注释

（1）本类的继承关系如下 ：

（2）本类很短，没有太多的代码 。

++

（3）关于本类的槽函数 ：

++关于本类的信号函数 ：

++测试一下 ：

++以及 ：

++以及 ：

（4）补充关于本类的构造函数中的形参 parent 的含义 ：

++ 我们可以搭建极为简单的举例程序，只要在主窗体里把自定义对话框调用起来就可以，以验证 QT 官方文档里的注释，此处举例来自于课本例题 ：

++以及 ：

（5）本源代码定义于头文件 qdialog . h ：

#ifndef QDIALOG_H
#define QDIALOG_H

#include <QtWidgets/qtwidgetsglobal.h>
#include <QtWidgets/qwidget.h>

QT_REQUIRE_CONFIG(dialog);

QT_BEGIN_NAMESPACE


class QPushButton;
class QDialogPrivate;

/*
The QDialog class is the base class of dialog windows.

Detailed Description:
对话框窗口是一种顶层窗口，主要用于短期任务以及与用户的简短交流。
QDialogs可以是模态的，也可以是非模型态的。
QDialogs可以提供返回值，并且可以具有默认按钮。

QDialogs还可以在其右下角包含一个QSizeGrip，使用`setSizeGripEnabled()、函数来启用它。

请注意，QDialog(以及任何具有类型Qt:Dialog的其他小部件)在用法上与Qt中的其他类略有不同。
对话框始终是个顶级小部件，
但如果它有一个父级，其默认位置将位于父级顶级小部件的顶部(如果它本身不是顶级小部件)。
它还将共享父级的任务栏条目。

使用QWidget:setParent()函数的覆盖版本来更改QDialog窗口组件的所有权。
该函数允许您显式设置被重新关联的窗口组件的窗口标志;
使用该覆盖函数将清除指定窗口系统属性的窗口标志(特别是会重置Qt::Dialog标志)。

注:对话框的父级关系并不意味着该对话框将始终堆叠在父窗口之上。
为确保对话框始终位于最上方，应使该对话框成为模态对话框。
这同样适用于对话框本身的子窗口。
为确保对话框的子窗口始终位于对话框之上，也应使这些子窗口成为模态对话框。

Modal Dialogs :
模态对话框是一种会阻止对同一应用程序中其他可见窗口进行输入的对话框。
用于向用户请求文件名或用于设置应用程序首选项的对话框通常为模态对话框。
对话框可以是应用程序模态(默认状态)或窗口模态.

当打开一个应用程序模态对话框时，
用户必须完成与该对话框的交互并关闭它，之后才能访问应用程序中的任何其他窗口。
窗口模态对话框仅阻止对与对话框关联的窗口的访问，从而允许用户继续使用应用程序中的其他窗口。

显示模态对话框最常用的方法是调用其`exec()、函数。
当用户关闭对话框时，`exec()、会提供一个有用的返回值。
为了关闭对话框并返回适当的值，您必须将默认按钮(例如OK按钮)连接到槽`accept()、，
而将取消按钮连接到槽`reject()、。或者，您也可以调用`done()、槽，并传入“接受”或“拒绝”的值。

-个替代方法是调用`setModal(true)、或`setWindowModality()'，然后调用`show().
因与`exec()不同,`show ()'会立即将控制权交还给调用者。对干进度对话框尤其有用.
调用`setModal(true)()为用户必须能够与对话框进行交互，例如取消一项耗时操作。
如果您同时使用`show()'和`setModal(true)来执行一项耗时操作，
那么在处理过程中必须定期调用`QCoreApplication::processEvents()、，
以允许用户与对话框进行交互。(见QProgressDialog.)

Modeless Dialogs :
无模态对话框是一种独立于同一应用程序中的其他窗口而运行的对话框。
在文字处理程序中，查找和替换对话框通常是无模态的，
    以便用户既能与应用程序的主窗口交互，也能与该对话框进行交互。

无模式对话框使用show()显示，该函数会立即将控制权返回给调用者。

如果在隐藏对话框后调用show()函数，该对话框将显示在原来的位置上。
这是因为窗口管理器为那些未由程序员明确放置的窗口确定位置。

为了保留已由用户移动的对话框的位置，应在closeEvent()、处理程序中保存其位置，
然后在再次显示对话框之前将其移动到该位置。

Default Button :
对话框的默认按钮是在用户按下Enter(回车)时触发的按钮。
该按钮用于表示用户接受对话框的设置并想要关闭对话框。
使用QPushButton::setDefault()、QPushButton::isDefault 和
    QPushButton::autoDefault()来设置和控制对话框的默认按钮。

Escape Key :
如果用户在对话框中按下ESc键，将调用QDialog::reject()。这将导致窗口关闭:关闭事件不能被忽略。

Extensibility :
扩展性是指能够以两种方式显示对话框:一种是显示最常用选项的局部对话框，另一种是显示所有选项的全局对话框。
通常，一个可扩展的对话框最初会以局部对话框的形式出现，但带有“更多”切换按钮。
如果用户按下“更多”按钮，对话框会被展开。扩展示例展示了如何使用Qt实现可扩展对话框。

Return Value (Modal Dialogs) :
模态对话框通常用于需要返回值的情况，例如以表明用户是按下了“确定”还是“取消”按钮。
通过调用“接accept()或“拒绝reject()”可以关闭对话框，
而“exec()”将相应地返回“接受”或“拒绝”。调用“执行exec()获取该结果。会返回对话框的结果。
如果对话框未被销毁，还可以通过“result()”.

为了修改对话框的关闭行为，您可以重写接受(accept())、拒绝(reject())或完成done()函数。
重写closeEvent()函数时，应仅用于保留对话框的位置或覆盖标准的关闭或拒绝行为。

Code Examples :

A modal dialog:
    void EditorWindow::countWords()
    {
        WordCountDialog dialog(this);
        dialog.setWordCount(document().wordCount()); //读取某文件里的单词个数
        dialog.exec();
    }

A modeless dialog:
     void EditorWindow::find()
     {
         if (!findDialog) {
             findDialog = new FindDialog(this);
             connect(findDialog, &FindDialog::findNext,
                     this, &EditorWindow::findNext);
         }

         findDialog->show();
         findDialog->raise();
         findDialog->activateWindow();
     }


*/

class Q_WIDGETS_EXPORT QDialog : public QWidget
{
    Q_OBJECT //又插入了此宏

    friend class QPushButton; //本类视普通按钮为友元类

    //此属性决定show()方法应以模态还是非模态方式弹出对话框。
    //默认情况下，此属性为假，`show ()、函数会以非模态对话框的形式弹出。
    //将该属性设置为真，等同于将`QWidget::windowModality`设置为`Qt::ApplicationModal'。
    //exec()忽略此属性的值，并始终以模态方式弹出对话框。
    Q_PROPERTY(bool modal READ isModal WRITE setModal)

    //此属性表示是否启用大小握把。//测试发现，即使不显示此手柄，对话框依然是可以被调整大小的。
    //当此属性启用时，会在对话框的右下角放置一个大小握把。默认情况下，大小握把手是禁用的。
    Q_PROPERTY(bool     sizeGripEnabled
                READ  isSizeGripEnabled   WRITE   setSizeGripEnabled)

    /*
    //这个枚举定义了模态窗口的行为。模态窗口会阻止对其他窗口的输入。
    //请注意，作为模态窗口子窗口的窗口不受此限制。
    enum Qt::WindowModality {
                NonModal, //该窗口不是模态窗口，不会阻止其他窗口的输入。
             WindowModal, //该窗口属于单个窗口层次结构，并阻止其父窗口、
                //所有祖级窗口以及其父窗口和祖级窗口的所有兄弟窗口接收输入。
                //The window is modal to a single window hierarchy and
                //  blocks input to its parent window, all grandparent windows,
                //  and all siblings of its parent and grandparent windows.
        ApplicationModal  //窗口对应用程序是模态的，并且阻止所有窗口的输入。
    };
    */

private:
    Q_DECLARE_PRIVATE(QDialog)
    Q_DISABLE_COPY(QDialog)

protected:
    QDialog(QDialogPrivate &, QWidget * parent, Qt::WindowFlags f = Qt::WindowFlags());

    void adjustPosition(QWidget *); //无注释

    bool            eventFilter(QObject *, QEvent *) override; //事件过滤，代理
    void        showEvent(QShowEvent        *) override;
    void    keyPressEvent(QKeyEvent         *) override;
    void      resizeEvent(QResizeEvent      *) override;
    void contextMenuEvent(QContextMenuEvent *) override;
    void       closeEvent(QCloseEvent       *) override;

public:
    //Constructs a dialog with parent parent.
    //The widget flags f are passed on to the QWidget constructor.
    //对话框始终是一个顶级小部件，但如果它有一个父级，其默认位置将位于父级的顶部中心。
    //它还将共享父级的任务栏条目。
    //例如，如果您不想在对话框的标题栏中显示“这是什么”按钮，
    //请在f中传递 Qt::WindowTitleHint | Qt::WindowSystemMenuHint.
    explicit QDialog(   QWidget *        parent = nullptr,
                        Qt::WindowFlags  f      = Qt::WindowFlags());

    ~QDialog();

/*
class QWidget
{
    Q_PROPERTY(bool modal READ isModal)
    inline     bool            isModal() const
    { return data->window_modality != Qt::NonModal; }
}
*/
//QWidget::Q_PROPERTY(bool    modal     READ    isModal)
//   Q_PROPERTY(bool          modal
//              READ        isModal  //父类 QWidget 里已有这个函数了
//              WRITE      setModal)
                void       setModal(bool modal);

//   Q_PROPERTY(bool          sizeGripEnabled
//              READ        isSizeGripEnabled   WRITE   setSizeGripEnabled)
                bool        isSizeGripEnabled() const;
                void       setSizeGripEnabled(bool);


    enum DialogCode { //The value returned by a modal dialog.
        Rejected,
        Accepted
    };
    //通常返回模态对话框的结果代码，Accepted或Rejected。
    //注意:当在QMessageBox实例上调用时，返回值是QMessageBox::StandardButton枚举的值。
    //如果对话框是用Qt::WA_DeleteOnClose属性构建的，则不要调用此函数。
    int     result() const;
    void setResult(int r);
    //将模态对话框的结果代码设置为 r。
    //注意:我们建议您使用由QDialog::Dialogcode定义的值之一。

    QSize        sizeHint() const override;
    QSize minimumSizeHint() const override;
    void  setVisible(bool visible) override;

public Q_SLOTS: //为本对话框预定义好的槽函数

    //将对话框显示为模态对话框，直到用户关闭它。该函数返回一个DialogCode结果。
    //如果该对话框是应用模态  application modal对话框，
    //用户在关闭该对话框之前无法与同一应用中的任何其他窗口进行交互。
    //如果该对话框是窗口模态  window modal对话框，那么在对话框打开期间，仅阻止与父窗口的交互。
    //默认情况下，该对话框是应用漠态对话框。
    //注:应避免使用此函数;取而代之的是使用open()。
    //与exec()不同，open()是异步的，不会启动额外的事件循环。
    //这可以防止一系列危险的错误发生(例如，在通过`exec()、打开对话框时删除对话框的父窗口)。
    //在使用`open()、时，您可以连接到QDialog的`finished()、信号，以便在对话框关闭时收到通知。
    virtual int  exec  ();

    virtual void open  (); //将对话框显示为窗口模态 window modal dialog对话框，并立即返回。

    virtual void accept(); //隐藏模态对话框并将结果代码设置为已接受  Accepted。
    //测试表明，本槽函数会触发本类的 accepted() 与 finished(Accepted) 信号函数的执行。

    //测试表明，本槽函数会触发本类的 rejected() 与 finished(rejected) 信号函数的执行。
    virtual void reject(); //隐藏而已，并非删除。
    //Hides the modal dialog and sets the result code to Rejected.

    virtual void done  (int r);
    //本槽函数会触发 accepted() 或 rejected()之一, 并与finished( r )的执行。
    //关闭对话框并将结果代码设置为 r。finished()信号将发出 r;
    //如果 r是 QDialog::Accepted 或QDialog::Rejected，则分别会发出accepted()或rejected()信号。
    //如果此对话框通过exec()显示，done()也会导致本地事件循环完成，并使exec()返回 r。
    //与QWidget::close()类似，done()会在设置Qt::WA_DeleteOnclose标志时删除对话框。
    //如果该对话框是应用程序的主窗口，则应用程序将终止。
    //如果该对话框是最后一个关闭的窗口，将发出QGuiApplication::lastWindowClosed()信号。

Q_SIGNALS:

    //当对话框被用户接受或通过调用accept()或done()并传递QDialog:Accepted参数来完成时，会触发此信号。
    //请注意，当使用hide()或setVisible(false)隐藏对话框时，不会发出此信号。这包括在对话框可见时删除它。
    void accepted(); //本类的 accept()函数或 done(Accepted) 都会触发本信号

    void rejected(); //本类的 reject()函数或 done(Rejected) 都会触发本信号
    //当对话框被用户拒绝或通过调用reject()或done()并传递QDialog::Rejected参数来拒绝时，会触发此信号。
    //请注意，当使用hide()或setVisible(false)隐藏对话框时，不会发出此信号。这包括在对话框可见时删除它。

    void finished(int result); //本类的 accept()、reject()、done(...)函数都会触发本信号。
    //This signal is emitted when the dialog's result code has been set,
    //  either by the user or by calling done(), accept(), or reject().
    //Note that this signal is not emitted when hiding the dialog with hide() or
    //  setVisible(false). This includes deleting the dialog while it is visible.


}; //完结 class QDialog : public QWidget

QT_END_NAMESPACE

#endif // QDIALOG_H

（6）

谢谢