QObject Class

成员函数文档

[explicit invokable] QObject::QObject(QObject *parent = nullptr)

创建一个父对象为parent 的对象。

对象的父对象可视为该对象的所有者。例如，dialog box 是其包含的OK 和Cancel 按钮的父对象。

父对象的析构函数会销毁所有子对象。

将 `parent ` 设置为 `nullptr ` 将创建一个没有父对象的对象。如果该对象是小部件，它将成为顶级窗口。

另请参阅 parent()、findChild() 和findChildren()。

[virtual noexcept] QObject::~QObject()

销毁该对象，并删除其所有子对象。

该对象的所有信号收发都会自动断开，且该对象所有待处理的已发布事件都会从事件队列中移除。不过，通常使用 `deleteLater()` 比直接删除 `QObject ` 的子类更为安全。

另请参阅 deleteLater()。

[noexcept] bool QObject::blockSignals(bool block)

如果 `block ` 为真，则该对象发出的信号将被阻塞（即，发出信号不会触发任何与其关联的处理程序）。如果 `block ` 为假，则不会发生此类阻塞。

返回值为signalsBlocked() 的上一次值。

请注意，即使该对象的信号已被阻塞，destroyed() 信号仍会被发出。

在被阻塞期间发出的信号不会被缓冲。

另请参阅 signalsBlocked() 和QSignalBlocker 。

[virtual protected] void QObject::childEvent(QChildEvent *event)

可以在子类中重写此事件处理程序，以接收子节点事件。该事件通过event 参数传递进来。

QEvent::ChildAdded 当子对象被添加或移除时，系统会向对象发送QEvent::ChildRemoved 事件。在这两种情况下，您只能假设该子对象是QObject ，或者当isWidgetType()返回true 时，该子对象是QWidget 。（这是因为，在ChildAdded 的情况下，子对象尚未完全构造完成；而在ChildRemoved 的情况下，它可能已被销毁。）

QEvent::ChildPolished 当子控件完成“polished”操作，或已“polished”的子控件被添加时，事件会发送给控件。若收到子控件的“polished”事件，通常表示该子控件的构建已完成。但这并非绝对保证，在控件构造函数执行期间，可能会收到多个“polished”事件。

对于每个子控件，你会收到一个 `ChildAdded ` 事件、零个或多个 `ChildPolished ` 事件，以及一个 `ChildRemoved ` 事件。

如果子控件在添加后立即被移除，则会省略ChildPolished 事件。如果子控件在构造和销毁过程中被多次polished，您可能会收到针对同一子控件的多个childpolished事件，每次事件对应的虚拟表都不同。

另请参阅 event()。

const QObjectList &QObject::children() const

返回一个子对象列表。QObjectList 类在头文件<QObject> 中定义如下：

typedef QList<QObject*> QObjectList;

列表中第一个添加的子对象是 `first ` 对象，最后一个添加的子对象是 `last ` 对象，即新添加的子对象会被追加到列表末尾。

请注意，当QWidget 的子项为raised 或lowered 时，列表顺序会发生变化。被提升的小部件将成为列表中的最后一个对象，而被降低的小部件将成为列表中的第一个对象。

另请参阅 findChild()、findChildren()、parent() 以及setParent()。

[static] QMetaObject::Connection QObject::connect(const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type = Qt::AutoConnection)

创建从sender 对象中的signal 到receiver 对象中的method 的连接，该连接基于给定的type 。返回该连接的句柄，该句柄可用于稍后断开连接。

如果无法建立连接（例如参数无效），则该连接句柄将失效。您可以通过将其强制转换为 bool 类型来检查QMetaObject::Connection 是否有效。

该函数的工作方式与 `connect(const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type) ` 相同，但使用 `QMetaMethod ` 来指定信号和方法。

另请参阅 connect(const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)。

[static] QMetaObject::Connection QObject::connect(const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type = Qt::AutoConnection)

创建一个连接，将sender 对象中的signal 中的给定type 与receiver 对象中的method 连接起来。返回该连接的句柄，该句柄可用于稍后断开连接。

在指定 `signal ` 和 `method` 时，必须使用 `SIGNAL() ` 和 `SLOT() ` 宏，例如：

QLabel *label = new QLabel;
QScrollBar *scrollBar = new QScrollBar;
QObject::connect(scrollBar, SIGNAL(valueChanged(int)),
                 label,  SLOT(setNum(int)));

此示例确保标签始终显示当前滚动条的数值。请注意，信号和插槽参数中不得包含任何变量名，只能指定类型。例如，以下代码将无法正常工作并返回 false：

// WRONG
QObject::connect(scrollBar, SIGNAL(valueChanged(int value)),
                 label, SLOT(setNum(int value)));

信号还可以连接到另一个信号：

class MyWidget : public QWidget
{
    Q_OBJECT

public:
    MyWidget();

signals:
    void buttonClicked();

private:
    QPushButton *myButton;
};

MyWidget::MyWidget()
{
    myButton = new QPushButton(this);
    connect(myButton, SIGNAL(clicked()),
            this, SIGNAL(buttonClicked()));
}

在此示例中，MyWidget 构造函数转发来自私有成员变量的信号，并使其以与MyWidget 相关的名称提供。

一个信号可以连接到多个插槽和信号。一个插槽也可以连接到多个信号。

如果一个信号连接到多个槽，则当该信号被发出时，这些槽将按照建立连接时的顺序依次被激活。

如果该函数成功将信号连接到插槽，则返回一个QMetaObject::Connection ，该对象表示连接的句柄。如果无法建立连接，例如QObject 无法验证signal 或method 是否存在，或者它们的签名不兼容，则该连接句柄将无效。您可以通过将其强制转换为bool类型来检查句柄是否有效。

默认情况下，每次建立连接时都会触发一个信号；若建立重复连接，则会触发两个信号。您可以通过一次disconnect()调用断开所有这些连接。 若传入Qt::UniqueConnection type ，则仅当连接非重复时才会建立。若已存在重复连接（即对同一对象上完全相同的信号与完全相同的槽的连接），则连接将失败，且connect将返回一个无效的QMetaObject::Connection 。

可选参数type 用于描述要建立的连接类型。具体而言，它决定了特定信号是立即传递给槽，还是被排队以便稍后传递。 如果信号被排队，参数的类型必须是 Qt 元对象系统所认知的，因为 Qt 需要在后台将参数复制并存储到事件中。如果您尝试使用排队连接并收到错误信息

QObject::connect: Cannot queue arguments of type 'MyType'
(Make sure 'MyType' is registered using qRegisterMetaType().)

请在建立连接之前调用 `qRegisterMetaType()` 来注册该数据类型。

注意：此函数是线程安全的。

另请参阅 disconnect()、sender()、qRegisterMetaType()、Q_DECLARE_METATYPE()以及“基于字符串的连接与基于函子的连接之间的区别”。

[static] template <typename PointerToMemberFunction, typename Functor> QMetaObject::Connection QObject::connect(const QObject *sender, PointerToMemberFunction signal, Functor functor)

在sender 对象中，从signal 建立到functor 的连接，并返回该连接的句柄

该信号必须是在头文件中作为信号声明的函数。槽函数可以是任何能够与该信号连接的函数或 functor。如果信号的参数个数至少与槽函数的参数个数相同，则槽函数即可与该信号连接。信号和槽中对应参数的类型之间必须存在隐式转换。

示例：

void someFunction();
//...
void someOtherFunction()
{
    QPushButton *button = new QPushButton;
    QObject::connect(button, &QPushButton::clicked, someFunction);
}

也可以使用 lambda 表达式：

    QByteArray page = "...";
    QTcpSocket *socket = new QTcpSocket;
    socket->connectToHost("qt-project.org", 80);
    QObject::connect(socket, &QTcpSocket::connected, [=] () {
            socket->write("GET " + page + "\r\n");
        });

如果发送者被销毁，连接将自动断开。但是，您应确保在发出信号时，函数对象内部使用的任何对象仍然存活。

因此，建议使用那个同时将QObject 作为接收者/上下文的connect()重载。可以通过定义QT_NO_CONTEXTLESS_CONNECT 宏来禁用无上下文的重载。

可以借助 `qOverload` 来解析重载函数。

注意：此函数是线程安全的。

QMetaObject::Connection QObject::connect(const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type = Qt::AutoConnection) const

将sender 对象中的signal 连接到该对象的method 。

等同于 connect(sender,signal,this,method,type)。

每次建立连接都会触发一个信号，因此重复建立连接会触发两个信号。您可以使用disconnect() 断开连接。

注意：此函数是线程安全的。

另请参阅 disconnect()。

[static] template <typename PointerToMemberFunction, typename Functor> QMetaObject::Connection QObject::connect(const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type = Qt::AutoConnection)

创建一个连接，将sender 对象中signal 的type 连接到functor ，并将其放置在context 的特定事件循环中，同时返回该连接的句柄。

信号必须是在头文件中作为信号声明的函数。槽函数可以是任何能够与该信号连接的函数或函子。如果信号的参数个数至少与槽函数的参数个数相同，则该槽函数即可连接到该信号。信号和槽中对应参数的类型之间必须存在隐式转换。

示例：

void someFunction();
//...
void someOtherFunction()
{
    QPushButton *button = new QPushButton;
    QObject::connect(button, &QPushButton::clicked, this, someFunction, Qt::QueuedConnection);
}

也可以使用 lambda 表达式：

QByteArray page = "...";
QTcpSocket *socket = new QTcpSocket;
socket->connectToHost("qt-project.org", 80);
QObject::connect(socket, &QTcpSocket::connected, this, [=] () {
        socket->write("GET " + page + "\r\n");
    }, Qt::AutoConnection);

如果发送者或上下文被销毁，连接将自动断开。但是，应确保在信号被触发时，函子内部使用的任何对象仍然存在。

可以借助 `qOverload` 来解析重载函数。

注意：此函数是线程安全的。

[static] template <typename PointerToMemberFunction> QMetaObject::Connection QObject::connect(const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type = Qt::AutoConnection)

创建从sender 对象中的signal 到receiver 对象中的method 的连接，该连接基于给定的type 。返回该连接的句柄，该句柄可用于日后断开连接。

该信号必须是在头文件中作为信号声明的函数。槽函数可以是任何能够与该信号连接的成员函数。如果信号的参数个数至少与槽函数的参数个数相同，且信号与槽函数中对应参数的类型之间存在隐式转换，则该槽函数即可与该信号建立连接。

示例：

QLabel *label = new QLabel;
QLineEdit *lineEdit = new QLineEdit;
QObject::connect(lineEdit, &QLineEdit::textChanged,
                label,  &QLabel::setText);

此示例确保标签始终显示当前行编辑框中的文本。

一个信号可以连接到多个槽和信号。一个槽可以连接到多个信号。

如果一个信号连接到多个槽，则当信号被触发时，这些槽将按照连接建立时的顺序依次被激活

如果函数成功将信号连接到插槽，则返回一个连接句柄。如果无法建立连接（例如，当QObject 无法验证signal 是否存在时——若该信号未被声明为信号），则该连接句柄将无效。您可以通过将其强制转换为bool类型来检查QMetaObject::Connection 是否有效。

默认情况下，每次建立连接都会触发一个信号；若建立重复连接，则会触发两个信号。您可以通过一次disconnect() 调用断开所有这些连接。 若将 `Qt::UniqueConnection ` 作为 `type` 参数传入，则仅当连接非重复时才会建立。若已存在重复连接（即对同一对象上完全相同的槽发送完全相同的信号），连接将失败，且 `connect` 会返回一个无效的 `QMetaObject::Connection`。

可选参数type 用于描述要建立的连接类型。具体而言，它决定特定信号是立即传递给槽，还是被排队以供稍后传递。 如果信号被排队，参数的类型必须是 Qt 元对象系统所识别的，因为 Qt 需要在后台将参数复制并存储到事件中。如果您尝试使用排队连接却收到错误信息

QObject::connect: Cannot queue arguments of type 'MyType'
(Make sure 'MyType' is registered using qRegisterMetaType().)

请确保使用Q_DECLARE_METATYPE

可以借助qOverload 来解析重载函数。

注意：此函数是线程安全的。

另请参阅 “基于字符串的连接与基于函子的连接之间的区别”。

[virtual protected] void QObject::connectNotify(const QMetaMethod &signal)

当有对象连接到该对象的signal 时，将调用此虚拟函数。

若要将signal 与特定信号进行比较，可按如下方式使用QMetaMethod::fromSignal()：

    if (signal == QMetaMethod::fromSignal(&MyObject::valueChanged)) {
        // signal is valueChanged
    }

另请参阅 connect() 和disconnectNotify()。

[virtual protected] void QObject::customEvent(QEvent *event)

可以在子类中重写此事件处理程序以接收自定义事件。自定义事件是由用户定义的事件，其类型值至少与QEvent::Type 枚举中的QEvent::User 项一样大，通常是QEvent 的子类。该事件通过event 参数传递进来。

另请参阅 event() 和QEvent 。

[slot] void QObject::deleteLater()

将此对象排入删除队列。

当控制权返回事件循环时，该对象将被删除。如果在调用此函数时事件循环未运行（例如，在调用QCoreApplication::exec()之前对某个对象调用了deleteLater()），则该对象将在事件循环启动后被删除。 如果在主事件循环停止后调用 deleteLater()，则该对象不会被删除。如果对位于没有运行中事件循环的线程中的对象调用 deleteLater()，则该对象将在线程结束时被销毁。

在QThread 中使用工作者QObject 时，一种常见的模式是将线程的finished() 信号连接到工作者的deleteLater() 槽，以确保其被安全删除：

connect(thread, &QThread::finished, worker, &QObject::deleteLater);

请注意，进入或离开一个新的事件循环（例如通过打开模态对话框）并不会执行延迟删除；要使对象被删除，控制权必须返回至最初调用 deleteLater() 的那个事件循环。 这不适用于在先前嵌套事件循环仍在运行时被删除的对象：Qt 事件循环会在新的嵌套事件循环开始时立即删除这些对象。

在 Qt 未通过 `QCoreApplication::exec()` 或 `QEventLoop::exec()` 等方式驱动事件分发器的情况下，延迟删除操作不会自动处理。为确保在此场景下执行延迟删除，可采用以下变通方案：

const auto *eventDispatcher = QThread::currentThread()->eventDispatcher();
QObject::connect(eventDispatcher, &QAbstractEventDispatcher::aboutToBlock,
    QThread::currentThread(), []{
        if (QThread::currentThread()->loopLevel() == 0)
            QCoreApplication::sendPostedEvents(nullptr, QEvent::DeferredDelete);
    }
);

注意：此函数是线程安全的。

另请参阅 destroyed() 和QPointer 。

[signal] void QObject::destroyed(QObject *obj = nullptr)

该信号在对象obj 被销毁之前立即发出，且在所有QPointer 的实例均已收到通知之后，并且无法被阻塞。

该信号发出后，该对象的所有子对象将立即被销毁。

另请参阅 deleteLater() 和QPointer 。

断开连接。

如果 `connection ` 为 `invalid ` 或已断开连接，则不执行任何操作并返回 `false`。

这些函数是在 Qt 6.12 中引入的。

另请参阅 connect()。

[static] bool QObject::disconnect(const QMetaObject::Connection &connection)

断开connection 连接，并将其重置为invalid 。

如果connection 无效或已被断开连接，则不执行任何操作并返回 false。

另请参阅 QT_NO_DISCONNECT_CONST_CONNECTION 和connect()。

[static] bool QObject::disconnect(const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)

断开对象sender 中signal 与对象receiver 中method 之间的连接。若连接成功断开，则返回true ；否则返回false 。

该函数提供的功能与disconnect(const QObject *sender, const char *signal, const QObject *receiver, const char *method) 相同，但使用QMetaMethod 来表示待断开的信号及其对应的方法。

此外，在以下情况下，该函数将返回 false，且不会断开任何信号和插槽：

1. signal 该信号并非发送者类的成员，也不是其父类之一的成员。
2. method 不是接收者类或其父类之一的成员。
3. signal instance 代表的不是信号。

为避免不匹配，请保存connect() 返回的连接句柄，并在调用disconnect() 时使用它。

QMetaMethod() 可作为通配符，表示“任何信号”或“接收对象中的任何槽”。同样地，nullptr 也可用于receiver ，表示“任何接收对象”。在这种情况下，方法也应为 QMetaMethod()。sender 参数绝不能是nullptr 。

另请参阅 disconnect(const QObject *sender, const char *signal, const QObject *receiver, const char *method)。

[static] bool QObject::disconnect(const QObject *sender, const char *signal, const QObject *receiver, const char *method)

断开对象sender 中signal 与对象receiver 中method 之间的连接。如果连接成功断开，则返回true ；否则返回false 。

当涉及的任一对象被销毁时，信号-槽连接即被解除。

如下例所示，disconnect() 通常有三种用法。

1. 断开与对象信号关联的所有连接：

       QObject::disconnect(myObject, nullptr, nullptr, nullptr);

   等同于非静态重载函数

       myObject->disconnect();

2. 断开与特定信号相关的所有连接：

       QObject::disconnect(myObject, SIGNAL(mySignal()), nullptr, nullptr);

   等同于非静态重载函数

       myObject->disconnect(SIGNAL(mySignal()));

3. 断开特定接收器的连接：

       QObject::disconnect(myObject, nullptr, myReceiver, nullptr);

   等同于非静态重载函数

       myObject->disconnect(myReceiver);

为避免不匹配，请保存connect() 返回的连接句柄，并在调用disconnect() 时使用该句柄。

nullptr 可作为通配符使用，分别表示“任何信号”、“任何接收对象”或“接收对象中的任何槽”。

sender 绝不能是nullptr 。（您无法在单次调用中断开多个对象的信号连接。）

如果 `signal ` 为 `nullptr`，则会将 `receiver ` 和 `method ` 从所有信号中断开连接。否则，仅指定信号会被断开。

如果receiver 为nullptr ，则会断开与signal 连接的所有内容。否则，除receiver 以外的其他对象中的槽将不会被断开。

若method 为nullptr ，则会断开所有连接到receiver 的信号。否则，仅会断开名为method 的槽，其他所有槽均保持不变。若省略receiver ，则method 必须为nullptr ，因此无法断开所有对象上特定名称的槽。

注意：此函数是线程安全的。

另请参阅 connect()。

bool QObject::disconnect(const QObject *receiver, const char *method = nullptr) const

将该对象中的所有信号与receiver 的method 断开连接。

为避免不匹配，请保存connect() 返回的连接句柄，并在调用disconnect() 时使用该句柄。

当涉及的任一对象被销毁时，信号-插槽连接将被删除。

bool QObject::disconnect(const char *signal = nullptr, const QObject *receiver = nullptr, const char *method = nullptr) const

将signal 从receiver 中的method 移除。

为避免不匹配，请保存connect() 返回的连接句柄，并在调用disconnect() 时使用该句柄。

当涉及的任一对象被销毁时，信号-插槽连接将被移除。

注意：此函数是线程安全的。

[static] template <typename PointerToMemberFunction> bool QObject::disconnect(const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)

断开对象sender 中signal 与对象receiver 中method 之间的连接。若连接成功断开，则返回true ；否则返回false 。

当参与信号-插槽连接的任一对象被销毁时，该连接即被解除。

如下例所示，disconnect() 通常有三种用法。

1. 断开与对象信号相关联的所有连接：

       QObject::disconnect(myObject, nullptr, nullptr, nullptr);

2. 断开与特定信号关联的所有连接：

       QObject::disconnect(myObject, &MyObject::mySignal, nullptr, nullptr);

3. 断开与特定接收器的连接：

       QObject::disconnect(myObject, nullptr, myReceiver, nullptr);

4. 断开某个特定信号与某个特定插槽之间的连接：

       QObject::disconnect(lineEdit, &QLineEdit::textChanged,
                       label,  &QLabel::setText);

nullptr 可作为通配符使用，分别表示“任何信号”、“任何接收对象”或“接收对象中的任何插槽”。

sender 绝不能是nullptr 。（您无法在单次调用中将信号从多个对象上断开。）

如果signal 为nullptr ，则会将receiver 和method 从所有信号中断开。否则，仅断开指定的信号。

如果receiver 是nullptr ，则会断开与signal 连接的所有内容。否则，仅断开指定接收器中的槽。当disconnect()的receiver 不为空时，也会断开那些以receiver 作为上下文对象连接的槽函数。

如果method 为nullptr ，则会断开所有连接到receiver 的内容。否则，仅会断开名为method 的槽，其余所有槽均保持不变。若省略receiver ，则method 必须为nullptr ，因此无法对所有对象上的特定名称槽进行断开操作。

注意：此函数是线程安全的。

另请参阅 connect()。

[virtual protected] void QObject::disconnectNotify(const QMetaMethod &signal)

当该对象中的signal 发生断开连接时，会调用此虚拟函数。

有关如何将signal 与特定信号进行比较的示例，请参阅connectNotify()。

如果所有信号都已从该对象断开连接（例如，disconnect() 的 signal 参数为nullptr ），则 disconnectNotify() 仅被调用一次，且signal 将是一个无效的QMetaMethod （QMetaMethod::isValid() 返回false ）。

另请参阅 disconnect() 和connectNotify()。

void QObject::dumpObjectInfo() const

将该对象的信号连接等相关信息输出到调试日志中。

另请参阅 dumpObjectTree()。

void QObject::dumpObjectTree() const

将子节点树输出到调试日志中。

另请参阅 dumpObjectInfo()。

QList<QByteArray> QObject::dynamicPropertyNames() const

返回使用 `setProperty()` 动态添加到对象中的所有属性的名称。

[virtual] bool QObject::event(QEvent *e)

此虚拟函数用于接收发送到对象的事件，如果识别并处理了e 事件，则应返回true。

可以重写 event() 函数来定制对象的行为。

请确保对于所有未处理的事件，都要调用父事件类的实现。

示例：

class MyClass : public QWidget
{
    Q_OBJECT

public:
    MyClass(QWidget *parent = nullptr);
    ~MyClass();

    bool event(QEvent* ev) override
    {
        if (ev->type() == QEvent::PolishRequest) {
            // overwrite handling of PolishRequest if any
            doThings();
            return true;
        } else  if (ev->type() == QEvent::Show) {
            // complement handling of Show if any
            doThings2();
            QWidget::event(ev);
            return true;
        }
        // Make sure the rest of events are handled
        return QWidget::event(ev);
    }
};

另请参阅 installEventFilter()、timerEvent()、QCoreApplication::sendEvent() 和QCoreApplication::postEvent()。

[virtual] bool QObject::eventFilter(QObject *watched, QEvent *event)

如果该对象已被安装为watched 对象的事件过滤器，则对事件进行过滤。

在您对该函数的重写中，若要过滤掉event 事件（即停止对其进行进一步处理），请返回true；否则返回false。

示例：

classMainWindow :publicQMainWindow
{
public:
    MainWindow();

protected:
    booleventFilter(QObject*obj,QEvent*ev) override;

private:
    QTextEdit*textEdit;
};

MainWindow::MainWindow()
{
    textEdit= newQTextEdit;
    setCentralWidget(textEdit);

    textEdit->installEventFilter(this);
}

boolMainWindow::eventFilter(QObject*obj,QEvent*event)
{
    if(obj==textEdit) {
        if(event->type()==QEvent::KeyPress) {
            QKeyEvent*keyEvent = static_cast<QKeyEvent*>(event);
            qDebug() << "Ate key press" << keyEvent->key();
           return true;
        }else{
            return false;
        }
    }else{
        // 将事件传递给父类
        returnQMainWindow::eventFilter(obj,event);
    }
}

请注意，在上面的示例中，未处理的事件会被传递给基类的 eventFilter() 函数，因为基类可能出于其自身的内部目的而重新实现了 eventFilter() 函数。

某些事件（例如QEvent::ShortcutOverride ）必须通过显式调用accept()来接受，以防止其传播。

另请参阅 installEventFilter()。

template <typename T> T QObject::findChild(QAnyStringView name, Qt::FindChildOptions options = Qt::FindChildrenRecursively) const

返回该对象的子对象，该子对象可被转换为类型 T，且名称为name ；若不存在此类对象，则返回nullptr 。当name 参数为空时，将匹配所有对象。当name 为空且不为空时，仅匹配objectName 为空的对象。搜索以递归方式进行，除非options 指定了 FindDirectChildrenOnly 选项。

如果有多个子节点符合搜索条件，则返回最直接的祖先。如果有多个最直接的祖先，则返回children()中的第一个子节点。在这种情况下，最好使用findChildren()来获取所有子节点的完整列表。

此示例返回parentWidget 的一个子元素QPushButton ，其名称为"button1" ，即使该按钮并非父元素的直接子元素：

QPushButton *button = parentWidget->findChild<QPushButton *>("button1");

此示例返回parentWidget 的子元素QListWidget ：

QListWidget *list = parentWidget->findChild<QListWidget *>();

此示例返回parentWidget （其直接父元素）的子元素QPushButton ，名称为"button1" ：

QPushButton *button = parentWidget->findChild<QPushButton *>("button1", Qt::FindDirectChildrenOnly);

此示例返回parentWidget （其直接父对象）的一个QListWidget 子对象：

QListWidget *list = parentWidget->findChild<QListWidget *>(Qt::FindDirectChildrenOnly);

另请参阅 findChildren()。

[since 6.7] template <typename T> T QObject::findChild(Qt::FindChildOptions options = Qt::FindChildrenRecursively) const

返回该对象中可转换为类型 T 的子对象；若不存在此类对象，则返回nullptr 。搜索过程采用递归方式进行，除非options 指定了 FindDirectChildrenOnly 选项。

如果有多个子对象符合搜索条件，则返回最直接的祖先。如果有多个最直接的祖先，则返回children()中的第一个子对象。在这种情况下，最好使用findChildren()来获取所有子对象的完整列表。

该函数在 Qt 6.7 中引入。

另请参阅 findChildren()。

template <typename T> QList<T> QObject::findChildren(QAnyStringView name, Qt::FindChildOptions options = Qt::FindChildrenRecursively) const

返回该对象下所有具有给定name 且可转换为类型T的子对象，若不存在此类对象，则返回空列表。若name 参数为null，则匹配所有对象；若为空，则仅匹配objectName 为空的对象。搜索过程采用递归方式进行，除非options 指定了FindDirectChildrenOnly选项。

以下示例演示了如何查找指定parentWidget （名为widgetname ）的所有子QWidget：

QList<QWidget *> widgets = parentWidget->findChildren<QWidget *>("widgetname");

此示例返回所有作为parentWidget 子节点的QPushButton：

QList<QPushButton *> allPButtons = parentWidget->findChildren<QPushButton *>();

此示例返回所有作为parentWidget 的直接子元素的QPushButton：

QList<QPushButton *> childButtons = parentWidget.findChildren<QPushButton *>(Qt::FindDirectChildrenOnly);

另请参阅 findChild()。

[since 6.3] template <typename T> QList<T> QObject::findChildren(Qt::FindChildOptions options = Qt::FindChildrenRecursively) const

返回该对象的所有子对象，这些子对象均可转换为类型 T；如果不存在此类对象，则返回空列表。搜索过程采用递归方式进行，除非在 `options ` 中指定了 `FindDirectChildrenOnly` 选项。

该函数在 Qt 6.3 中引入。

另请参阅 findChild()。

template <typename T> QList<T> QObject::findChildren(const QRegularExpression &re, Qt::FindChildOptions options = Qt::FindChildrenRecursively) const

返回该对象的子对象中，既可转换为类型 T，且名称与正则表达式re 匹配的那些；如果不存在此类对象，则返回空列表。搜索操作将递归进行，除非在options 中指定了 FindDirectChildrenOnly 选项。

bool QObject::inherits(const char *className) const

如果该对象是继承了className 的类的实例，或者是一个继承了className 的QObject 子类的实例，则返回true ；否则返回false 。

一个类被视为继承自身。

示例：

QTimer *timer = new QTimer;         // QTimer inherits QObject
timer->inherits("QTimer");          // returns true
timer->inherits("QObject");         // returns true
timer->inherits("QAbstractButton"); // returns false

// QVBoxLayout inherits QObject and QLayoutItem
QVBoxLayout *layout = new QVBoxLayout;
layout->inherits("QObject");        // returns true
layout->inherits("QLayoutItem");    // returns true (even though QLayoutItem is not a QObject)

若需判断某个对象是否为特定类的实例（以便进行类型转换），建议改用qobject_cast<Type *>(object) 方法。

另请参阅 metaObject() 和qobject_cast()。

void QObject::installEventFilter(QObject *filterObj)

在此对象上安装一个名为filterObj 的事件过滤器。例如：

monitoredObj->installEventFilter(filterObj);

事件过滤器是一个会接收发送到该对象的所有事件的对象。该过滤器既可以阻止事件，也可以将其转发给该对象。事件过滤器filterObj 通过其eventFilter()函数接收事件。如果需要过滤（即阻止）该事件，eventFilter()函数必须返回true；否则必须返回false。

如果单个对象上安装了多个事件过滤器，则最后安装的过滤器将首先被激活。

如果该对象上已安装了filterObj ，则此函数会将其移至最后，使其行为如同最后安装的一样。

以下是一个KeyPressEater 类，它会捕获其监视对象的按键操作：

classKeyPressEater :publicQObject
{
    Q_OBJECT
public:
    KeyPressEater(QObject*parent =nullptr) : QObject(parent) {}
//...

protected:
    booleventFilter(QObject*obj,QEvent*event) override;
};

boolKeyPressEater::eventFilter(QObject*obj,QEvent*event)
{
    if(event->type()==QEvent::KeyPress) {
        QKeyEvent*keyEvent = static_cast<QKeyEvent*>(event);
        qDebug("Ate key press %d", keyEvent->key());
       return true;
    }else{
        // 标准事件处理
        returnQObject::eventFilter(obj,event);
    }
}

以下是在两个小部件上安装它的方法：

KeyPressEater *keyPressEater = new KeyPressEater(this);
QPushButton *pushButton = new QPushButton(this);
QListView *listView = new QListView(this);

pushButton->installEventFilter(keyPressEater);
listView->installEventFilter(keyPressEater);

例如，QShortcut 类就使用了这种技术来拦截快捷键的按下操作。

请注意，过滤对象必须与该对象位于同一线程中。如果 `filterObj ` 位于不同线程中，则该函数不会执行任何操作。如果在调用此函数后，`filterObj ` 或该对象被移至不同线程，则事件过滤器将不会被调用，直到两个对象再次具有相同的线程亲和性（且该亲和性未被移除）。

另请参阅 removeEventFilter()、eventFilter() 和event()。

[noexcept, since 6.11] bool QObject::isQmlExposed() const

返回该对象是由 QML 引擎创建的，还是通过 `QJSEngine::setObjectOwnership()` 显式设置了所有权。

该函数在 Qt 6.11 中引入。

[since 6.4] bool QObject::isQuickItemType() const

如果该对象是QQuickItem ，则返回true ；否则返回false 。

调用此函数等同于调用inherits("QQuickItem") ，但速度要快得多。

该函数在 Qt 6.4 中引入。

[protected] bool QObject::isSignalConnected(const QMetaMethod &signal) const

如果signal 连接到至少一个接收器，则返回true ；否则返回false 。

signal 必须是该对象的信号成员，否则行为未定义。

    static const QMetaMethod valueChangedSignal = QMetaMethod::fromSignal(&MyObject::valueChanged);
    if (QObject::isSignalConnected(valueChangedSignal)) {
        QByteArray data;
        data = get_the_value();       // expensive operation
        emit valueChanged(data);
    }

如上面的代码片段所示，您可以使用此函数来避免耗时的操作或发出无人监听的信号。

另请参阅 receivers()。

bool QObject::isWidgetType() const

如果该对象是一个控件，则返回true ；否则返回false 。

调用此函数等同于调用inherits("QWidget") ，但速度要快得多。

bool QObject::isWindowType() const

如果该对象是一个窗口，则返回 `true `；否则返回 `false`。

调用此函数等同于调用inherits("QWindow") ，但速度要快得多。

void QObject::killTimer(int id)

终止具有定时器标识符id 的定时器。

该定时器标识符由startTimer() 在启动定时器事件时返回。

另请参阅 timerEvent() 和startTimer()。

[since 6.8] void QObject::killTimer(Qt::TimerId id)

该函数在 Qt 6.8 中引入。

[virtual] const QMetaObject *QObject::metaObject() const

返回指向该对象元对象的指针。

元对象包含继承了QObject 的类的相关信息，例如类名、超类名、属性、信号和插槽。每个包含Q_OBJECT 宏的QObject 子类都将拥有一个元对象。

信号/插槽连接机制和属性系统都需要元对象信息。inherits() 函数也会使用元对象。

如果您没有指向实际对象实例的指针，但仍希望访问某个类的元对象，可以使用staticMetaObject 。

示例：

QObject *obj = new QPushButton;
obj->metaObject()->className();             // returns "QPushButton"

QPushButton::staticMetaObject.className();  // returns "QPushButton"

另请参阅 staticMetaObject 。

bool QObject::moveToThread(QThread *targetThread)

更改此对象及其子对象的线程亲和性，并在成功时返回true 。如果该对象有父对象，则无法将其移动。事件处理将在targetThread 中继续进行。

若要将对象移动到主线程，请使用QApplication::instance()获取当前应用程序的指针，然后使用QApplication::thread()获取该应用程序所在的线程。例如：

myObject->moveToThread(QApplication::instance()->thread());

如果 `targetThread ` 返回 `nullptr`，则该对象及其子对象的所有事件处理都将停止，因为它们不再与任何线程相关联。

请注意，该对象的所有活动定时器都将被重置。定时器首先会在当前线程中停止，然后在targetThread 中（以相同的间隔）重新启动。因此，不断在不同线程之间移动对象可能会无限期推迟定时器事件。

在线程亲和性（thread affinity）发生变更之前，会向该对象发送一个QEvent::ThreadChange 事件。您可以处理此事件以执行任何特殊处理。请注意，只要该对象的在线程亲和性未被设置为nullptr ，所有新发布的事件都将在targetThread 中处理；当在线程亲和性被设置为nullptr 时，该对象及其子对象将无法进行任何事件处理，因为它们已不再与任何线程相关联。

在 Qt 6.7 之前的版本中，该函数没有返回值（void ）。

另请参阅 thread()。

[private signal] void QObject::objectNameChanged(const QString &objectName)

在对象名称被更改后，会发出此信号。新对象名称作为objectName 参数传递。

另请参阅 QObject::objectName 。

QObject *QObject::parent() const

返回指向父对象的指针。

另请参阅 setParent() 和children()。

QVariant QObject::property(const char *name) const

返回对象的name 属性的值。

如果不存在此属性，则返回的变体无效。

有关所有可用属性的信息可通过metaObject() 和dynamicPropertyNames() 获取。

另请参阅 setProperty()、QVariant::isValid()、metaObject() 和dynamicPropertyNames()。

[protected] int QObject::receivers(const char *signal) const

返回连接到signal 的接收器数量。

由于插槽和信号均可作为信号的接收器，且同一连接可以建立多次，因此接收器的数量即等于该信号建立的连接数量。

调用此函数时，可以使用SIGNAL() 宏来传递一个特定的信号：

if (receivers(SIGNAL(valueChanged(QByteArray))) > 0) {
    QByteArray data;
    get_the_value(&data);       // expensive operation
    emit valueChanged(data);
}

如上面的代码片段所示，您可以使用此函数来避免耗时的操作，或避免发出无人监听的信号。

另请参阅 isSignalConnected()。

void QObject::removeEventFilter(QObject *obj)

从该对象中移除事件过滤器对象obj 。如果尚未安装该事件过滤器，则忽略此请求。

当该对象被销毁时，其所有事件过滤器都会被自动移除。

移除事件过滤器始终是安全的，即使在事件过滤器激活期间（即从eventFilter() 函数中调用）也是如此。

另请参阅 installEventFilter()、eventFilter() 和event()。

[protected] QObject *QObject::sender() const

如果在由信号激活的插槽中调用此函数，则返回发送该信号的对象的指针；否则返回nullptr 。该指针仅在从该对象的线程上下文中调用此函数的插槽执行期间有效。

如果发送者被销毁，或者该槽与发送者的信号断开连接，则该函数返回的指针将失效。

另请参阅 senderSignalIndex()。

[protected] int QObject::senderSignalIndex() const

返回调用当前正在执行的槽的信号的元方法索引，该槽是sender()返回的类的成员。如果是在非由信号激活的槽之外调用此函数，则返回-1。

对于具有默认参数的信号，无论在connect() 中使用了哪个参数，该函数始终返回包含所有参数的索引。例如，信号destroyed(QObject *obj = \nullptr) 将有两个不同的索引（带参数和不带参数），但该函数始终返回带参数的索引。当使用不同参数重载信号时，此规则不适用。

另请参见 sender()、QMetaObject::indexOfSignal() 和QMetaObject::method()。

void QObject::setObjectName(const QString &name)

将对象的名称设置为name 。

另请参阅 objectName()。

[since 6.4] void QObject::setObjectName(QAnyStringView name)

该函数在 Qt 6.4 中引入。

void QObject::setParent(QObject *parent)

将该对象设为parent 的子对象。

另请参阅 parent() 和children()。

bool QObject::setProperty(const char *name, const QVariant &value)

将对象的name 属性的值设置为value 。

如果该属性是在类中通过Q_PROPERTY 定义的，则成功时返回 true，否则返回 false。如果该属性未通过Q_PROPERTY 定义，因此未在元对象中列出，则将其作为动态属性添加，并返回 false。

有关所有可用属性的信息可通过metaObject() 和dynamicPropertyNames() 获取。

动态属性可通过property() 再次查询，并通过将属性值设置为无效的QVariant 来移除。更改动态属性的值会导致向对象发送QDynamicPropertyChangeEvent 。

注意：以“_q_”开头的动态属性保留用于内部用途。

另请参阅 property()、metaObject()、dynamicPropertyNames() 和QMetaProperty::write()。

[since 6.6] bool QObject::setProperty(const char *name, QVariant &&value)

该函数在 Qt 6.6 中引入。

[noexcept] bool QObject::signalsBlocked() const

如果信号被阻塞，则返回true ；否则返回false 。

默认情况下，信号不会被阻塞。

另请参阅 blockSignals() 和QSignalBlocker 。

int QObject::startTimer(int interval, Qt::TimerType timerType = Qt::CoarseTimer)

这是一个重载函数，它将启动一个类型为timerType 的定时器，并设置超时时间为interval 毫秒。这相当于调用：

startTimer(std::chrono::milliseconds{interval}, timerType);

从 Qt 6.10 开始，设置负间隔将导致运行时警告，且该值会被重置为 1 毫秒。 在 Qt 6.10 之前，Qt Timer 虽然允许设置负间隔，但行为可能出人意料（例如，如果计时器正在运行则会停止，或者根本不启动）。

另请参阅 timerEvent(),killTimer(),QChronoTimer 以及QBasicTimer 。

int QObject::startTimer(std::chrono::nanoseconds interval, Qt::TimerType timerType = Qt::CoarseTimer)

启动一个计时器并返回计时器标识符；如果无法启动计时器，则返回零。

在调用killTimer()之前，定时器事件将每interval 触发一次。如果interval 等于std::chrono::duration::zero() ，则定时器事件在控制权每次返回事件循环时触发一次，即当没有更多原生窗口系统事件需要处理时。

从 Qt 6.10 开始，设置负间隔会引发运行时警告，且该值将被重置为 1 毫秒。 在 Qt 6.10 之前，虽然可以为 Qt Timer 设置负间隔，但其行为可能出人意料（例如，如果计时器正在运行则会停止，或者根本不会启动）。

当定时器事件发生时，会通过QTimerEvent 事件参数类调用虚拟函数timerEvent()。请重写此函数以获取定时器事件。

如果有多个计时器正在运行，可以使用QTimerEvent::id()方法来确定是哪一个计时器被触发的。

示例：

classMyObject :publicQObject
{
    Q_OBJECT

public:
    MyObject(QObject*parent =nullptr);

Q_SIGNALS:
    voidvalueChanged();

protected:
    voidtimerEvent(QTimerEvent*event) override;
};

MyObject::MyObject(QObject*parent)
    : QObject(parent)
{
    using namespacestd::chrono_literals;

    startTimer(50ms);
    startTimer(5s);
    startTimer(10min);
    startTimer(1h);
}

voidMyObject::timerEvent(QTimerEvent*event)
{
    qDebug() << "Timer ID:" << event->id();
}

请注意，计时器的精度取决于底层操作系统和硬件。

通过timerType 参数，您可以自定义定时器的精度。有关不同定时器类型的信息，请参阅Qt::TimerType 。大多数平台支持 20 毫秒的精度；部分平台支持更高的精度。如果 Qt 无法提供请求数量的定时器事件，它将静默丢弃其中一部分。

QTimer 和QChronoTimer 类提供了一个高级编程接口，使用单次触发定时器和定时器信号代替事件。此外还有QBasicTimer 类，它比QChronoTimer 更轻量，但比直接使用定时器 ID 更便捷。

    QObject *obj;
    //...
    const auto id = Qt::TimerId {obj->startTimer(100ms)};
    if (id != Qt::TimerId::Invalid)
    {
        // The timer has been started successfully
    }

另请参阅 timerEvent()、killTimer()、QChronoTimer 以及QBasicTimer 。

QThread *QObject::thread() const

返回包含该对象的线程。

另请参阅 ` moveToThread()`。

[virtual protected] void QObject::timerEvent(QTimerEvent *event)

可以在子类中重写此事件处理程序，以接收该对象的定时器事件。

QChronoTimer 该接口为定时器功能提供了更高层次的接口，同时也提供了关于定时器的更通用信息。定时器事件通过event 参数传递进来。

另请参阅 startTimer()、killTimer() 和event()。

[static] QString QObject::tr(const char *sourceText, const char *disambiguation = nullptr, int n = -1)

返回sourceText 的翻译版本，可选地基于disambiguation 字符串以及n 的值（适用于包含复数形式的字符串）；否则，若无合适的翻译字符串，则返回QString::fromUtf8 （sourceText ）。

示例：

void SpreadSheet::setupMenuBar()
{
    QMenu *fileMenu = menuBar()->addMenu(tr("&File"));
    ...

如果在同一上下文中，同一sourceText 在不同角色中被使用，则可在disambiguation 中传递一个额外的标识字符串（默认值为nullptr ）。

示例：

MyWindow::MyWindow()
{
    QLabel *senderLabel = new QLabel(tr("Name:"));
    QLabel *recipientLabel = new QLabel(tr("Name:", "recipient"));
    ...

有关 Qt 翻译机制的详细说明，请参阅《编写待翻译源代码》；有关消除歧义的信息，请参阅“消除相同文本的歧义”一节。

另请参阅 ` QCoreApplication::translate()` 以及《使用 Qt 进行国际化》。