QObject 类

成员函数文档

[显式可调用] QObject::QObject(QObject *parent = nullptr)

使用父对象parent构造一个对象。

对象父可以被看作是该对象的拥有者。例如，一个对话框是其中OK和Cancel按钮的父。

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

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

另请参阅：parent()，findChild()，和findChildren。

[虚拟 nothrow] QObject::~QObject()

销毁对象，删除所有子对象。

自动断开对象的所有信号，并从事件队列中移除对该对象的任何挂起的已发布事件。然而，通常使用deleteLater()比直接删除QObject子类更安全。

另请参阅：deleteLater。

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

如果block为true，此对象的信号发射会被阻塞（即，发射信号将不会调用连接到它的任何内容）。如果block为false，则不会发生此阻塞。

返回值是signalsBlocked的先前值。

即使在信号被阻塞的情况下，也会发射destroyed信号。

被阻塞时发射的信号不会缓存在。

另请参阅：signalsBlocked()和QSignalBlocker。

[虚拟受保护] void QObject::childEvent(QChildEvent *event)

这个事件处理可以在子类中重写以接收子事件。事件通过event参数传递。

QEvent::ChildAdded 和 QEvent::ChildRemoved 事件在添加或删除子对象时发送给对象。在这两种情况下，您只能依赖于该子对象是一个 QObject，或者如果 isWidgetType() 返回 true，那么是一个 QWidget。 (这是因为在 ChildAdded 的情况下，子对象尚未完全构建，在 ChildRemoved 的情况下，它可能已经被销毁)。

QEvent::ChildPolished 事件在子对象被打磨或添加打磨子对象时发送给小部件。如果您收到一个打磨子对象事件，则子对象的构建通常已完成。但是，这并不保证，当一个小部件的构造函数执行时，可能会发送多个打磨事件。

对于每个子小部件，您将接收一个 ChildAdded 事件，零个或多个 ChildPolished 事件，以及一个 ChildRemoved 事件。

如果一个子对象在添加后立即被删除，则省略 ChildPolished 事件。如果在构建和销毁过程中子对象被打磨多次，您可能会收到针对同一子对象的多个子打磨事件，每次事件都带有不同的虚表。

另请参阅 event()。

const QObjectList &QObject::children() const

返回子对象列表。在 <QObject> 头文件中定义了 QObjectList 类，如下所示

typedef QList<QObject*> QObjectList;

添加的第一个子对象是列表中的第一个对象，最后添加的子对象是列表中的最后一个对象，即新子对象被附加到末尾。

请注意，当 QWidget 子对象 升起 或 降低 时，列表顺序会改变。升起的小部件变为列表中的最后一个对象，降低的小部件变为列表中的第一个对象。

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

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

从发送器的 signal 到接收器的 method 创建给定 type 的连接。返回一个可以用于稍后断开连接的连接句柄。

当指定 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无法验证信号或方法的存在，或者它们的签名不兼容），则连接句柄将无效。您可以通过将其转换为bool来检查句柄是否有效。

默认情况下，每创建一个连接就会发出一个信号；重复连接会发出两个信号。您可以通过单个disconnect()调用来断开所有这些连接。如果您传递Qt::UniqueConnection 类型，则仅在它不是重复的时才会建立连接。如果已经存在重复（即在对同一对象的同一信号和槽的精确相同的连接），则连接将失败，connect将返回一个无效的QMetaObject::Connection。

可选的类型参数描述要建立的连接类型。特别是，它确定是否将特定信号立即传递给槽，还是将其排队，稍后再传递。如果信号排队，则参数类型必须是Qt元对象系统所知的类型，因为Qt需要复制参数以在幕后存储在事件中。如果您尝试使用排队连接并收到错误消息

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

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

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

另请参阅disconnect（断开连接），sender（发送者），qRegisterMetaType（注册元类型），Q_DECLARE_METATYPE（声明元类型），以及字符串连接和函数式连接之间的差异。

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

从发送器的 signal 到接收器的 method 创建给定 type 的连接。返回一个可以用于稍后断开连接的连接句柄。

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

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

另请参阅connect（连接）。

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

此函数是 connect() 的重载。

将 sender 对象的 signal 连接到此对象的 method。

相当于 connect(sender, signal, this, method, type)。

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

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

另请参阅 disconnect().

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

此函数是 connect() 的重载。

从发送器的 signal 到接收器的 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 类型，则仅在它不是重复的时才会建立连接。如果已经存在重复（即在对同一对象的同一信号和槽的精确相同的连接），则连接将失败，connect将返回一个无效的QMetaObject::Connection。

可选的类型参数描述要建立的连接类型。特别是，它确定是否将特定信号立即传递给槽，还是将其排队，稍后再传递。如果信号排队，则参数类型必须是Qt元对象系统所知的类型，因为Qt需要复制参数以在幕后存储在事件中。如果您尝试使用排队连接并收到错误消息

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

请确保使用 Q_DECLARE_METATYPE 声明参数类型。

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

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

另请参阅 基于字符串和基于函数指针的连接的区别.

[静态] 模板 <typename PointerToMemberFunction, typename Functor> QMetaObject::Connection QObject::connect(const QObject *sender, PointerToMemberFunction signal, Functor functor)

此函数是 connect() 的重载。

从 sender 对象中的 signal 创建到 functor 的连接，并返回连接句柄。

该信号必须在头文件中声明为一个信号。槽函数可以是任何可以连接到信号的函数或函数对象。如果信号参数和槽参数之间存在隐式转换，则槽函数可以连接到给定信号。信号参数的数量必须不少于槽函数参数的数量。

示例

void someFunction();
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");
    });

如果发送者被销毁，连接将自动断开。但是，你应该注意，在信号发出时，用于 funtor 内部的任何对象都应该仍然处于活动状态。

因此，建议使用同时接收QObject实例作为接收器/上下文的connect()重载版本。可以通过定义宏QT_NO_CONTEXTLESS_CONNECT来禁用不带上下文的重载版本的使用。

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

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

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

此函数是 connect() 的重载。

从发送者对象中的信号创建指定类型的连接到functor，放置在上下文的特定事件循环中，并返回连接句柄。

该信号必须在头文件中声明为一个信号。槽函数可以是任何可以连接到信号的函数或函数对象。如果信号参数和槽参数之间存在隐式转换，则槽函数可以连接到给定信号。信号参数的数量必须不少于槽函数参数的数量。

示例

void someFunction();
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);

如果发送者或上下文被销毁，连接将自动断开。但是，请注意，在信号被发出时，用于functor中的任何对象都必须仍然存活。

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

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

[虚受保护] void QObject::connectNotify(const QMetaMethod &signal)

当本对象中的信号被连接到某个东西时，会调用此虚函数。

如果您想将信号与特定信号进行比较，可以使用QMetaMethod::fromSignal()如下所示

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

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

[虚受保护] void QObject::customEvent(QEvent *event)

此事件处理器可以在子类中重新实现以接收自定义事件。自定义事件是用户定义的事件，其类型值至少与枚举QEvent::Type中的QEvent::User项一样大，通常是QEvent的子类。事件通过{i translate="no">event参数传入。

另请参阅 event() 和 QEvent。

[槽] void QObject::deleteLater()

安排此对象进行删除。

对象将在控制返回事件循环时被删除。如果在调用此函数时事件循环尚未运行（例如，在调用QCoreApplication::exec之前调用deleteLater()或在对象存活的线程中没有运行的事件循环上调用deleteLater()），一旦事件循环启动，对象将被删除。如果在主事件循环停止后调用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。

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

此信号在对象obj被销毁之前立即发出，在所有QPointer实例被通知后，且无法被阻塞。

在此信号发出后，该对象的全部子对象都将被立即销毁。

另请参阅deleteLater和QPointer。

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

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

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

disconnect()通常以以下三种方式使用，以下示例将演示这些用法。

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

   disconnect(myObject, nullptr, nullptr, nullptr);

   与以下非静态重载函数等价

   myObject->disconnect();

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

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

   与以下非静态重载函数等价

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

3. 断开特定的接收者

   disconnect(myObject, nullptr, myReceiver, nullptr);

   与以下非静态重载函数等价

   myObject->disconnect(myReceiver);

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

sender永远不能为nullptr。（您不能在单个调用中从多个对象中断开信号。）

如果signal为nullptr，它将断开receiver和method与任何信号的连接。如果不为nullptr，则只断开指定的信号。

如果receiver为nullptr，则断开与signal相关的所有连接。如果不为nullptr，则除了receiver以外的对象中的槽不将被断开。

如果method为nullptr，则断开与receiver相关的所有连接。如果不为nullptr，则只有名为method的槽将被断开，其他槽保持不变。如果省略receiver，则method必须为nullptr，因此您不能断开所有对象上特定命名的槽。

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

另请参阅connect。

[静态] 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 实例不表示信号。

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

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

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

此函数是 disconnect() 的重载。

从接收者 receiver 的 method 中断开 signal。

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

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

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

此函数是 disconnect() 的重载。

从此对象的所有信号中断开接收者 receiver 的 method。

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

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

断开一个连接。

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

另请参阅connect。

[静态] 模板 <typename PointerToMemberFunction> bool QObject::disconnect(const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)

此函数是 disconnect() 的重载。

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

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

disconnect()通常以以下三种方式使用，以下示例将演示这些用法。

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

   disconnect(myObject, nullptr, nullptr, nullptr);

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

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

3. 断开特定的接收者

   disconnect(myObject, nullptr, myReceiver, nullptr);

4. 断开从特定信号到特定槽的连接

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

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

sender永远不能为nullptr。（您不能在单个调用中从多个对象中断开信号。）

如果signal为nullptr，它将断开receiver和method与任何信号的连接。如果不为nullptr，则只断开指定的信号。

如果 receiver 是 nullptr，则断开与 signal 相连的任何内容。如果不是，则只断开指定接收者中的槽。使用非空 receiver 的 disconnect() 还会断开使用 receiver 作为其上下文对象的连接。

如果method为nullptr，则断开与receiver相关的所有连接。如果不为nullptr，则只有名为method的槽将被断开，其他槽保持不变。如果省略receiver，则method必须为nullptr，因此您不能断开所有对象上特定命名的槽。

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

另请参阅connect。

[虚，保护] void QObject::disconnectNotify(const QMetaMethod &signal)

当此对象中的 signal 被断开连接时，将调用此虚拟函数。

查看 connectNotify() 了解如何比较 signal 与特定信号。

如果所有信号都已从该对象断开连接（例如，disconnect() 的信号参数为 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()动态添加到对象的属性名称。

[虚拟] 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()。

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

如果此对象被安装为监视对象的过滤器，则过滤事件。

在您对此函数的重实现中，如果想要过滤掉事件，即停止事件被进一步处理，则返回 true；否则返回 false。

示例

class MainWindow : public QMainWindow
{
public:
    MainWindow();

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

private:
    QTextEdit *textEdit;
};

MainWindow::MainWindow()
{
    textEdit = new QTextEdit;
    setCentralWidget(textEdit);

    textEdit->installEventFilter(this);
}

bool MainWindow::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 {
        // pass the event on to the parent class
        return QMainWindow::eventFilter(obj, event);
    }
}

注意上述示例中将未处理的事件传递到基类的 eventFilter() 函数，因为基类可能已经为自身内部目的重写了 eventFilter()。

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

另请参阅 installEventFilter。

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

返回此对象的子对象，该子对象可以转换为类型 T，并且名称为 name，如果没有此类对象，则返回 nullptr。如果 name 参数为 null，则匹配所有对象。一个空且非 null 的 name 只匹配 objectName 为空的那些对象。搜索是递归的，除非 options 指定了选项 FindDirectChildrenOnly。

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

此示例返回名为 "button1" 的 QPushButton 子对象，即使该按钮不是父对象的直接子对象

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

此示例返回 QListWidget 子对象，该子对象属于 parentWidget

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

此示例返回名为 "button1" 的 QPushButton 子对象（其直接父对象）

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

此示例返回属于 parentWidget 的 QListWidget 子对象，其直接父对象

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

另请参阅 findChildren。

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

这是一个重载函数。

返回可以转换为类型 T 的子对象，如果没有此类对象，则返回 nullptr。除非 options 指定了选项 FindDirectChildrenOnly，否则搜索是递归的。

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

此函数是在 Qt 6.7 中引入的。

另请参阅 findChildren。

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

返回具有给定 name 且可转换为类型 T 的所有子对象，如果没有此类对象，则返回空列表。如果 name 参数为 null，则匹配所有对象，如果为空则仅匹配 objectName 为空的那些对象。除非 options 指定了选项 FindDirectChildrenOnly，否则搜索是递归的。

以下示例展示了如何找到名为widgetname的指定parentWidget的所有子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

[自6.3以来] 模板 <typename T> QList<T> QObject::findChildrenQt::FindChildOptions options = Qt::FindChildrenRecursively) const

这是一个重载函数。

返回所有可以转换为类型T的对象的子对象，如果没有此类对象则返回空列表。除非options指定了FindDirectChildrenOnly选项，否则搜索是递归的。

此函数自Qt 6.3开始引入。

另请参阅 findChild

模板 <typename T> QList<T> QObject::findChildrenQRegularExpression &re, Qt::FindChildOptions options = Qt::FindChildrenRecursively) const

此函数重载了findChildren。

返回可以转换为类型T且名称匹配正则表达式re的所有子对象，如果没有此类对象则返回空列表。除非options指定了FindDirectChildrenOnly选项，否则搜索是递归的。

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

如果此对象是继承自className的类的实例，或者继承自QObject子类并且继承自className，则返回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类，它吞噬它监视的对象的按键

class KeyPressEater : public QObject
{
    Q_OBJECT
    ...

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

bool KeyPressEater::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 {
        // standard event processing
        return QObject::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()。

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

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

调用此函数相当于调用 inherits("QQuickItem")，但速度更快。

此函数是在 Qt 6.4 中引入的。

[受保护] bool QObject::isSignalConnected(const QMetaMethod &signal) const

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

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

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

如上述代码片段所示，您可以使用此函数来避免昂贵的初始化或发出没有人监听的事件。然而，在多线程应用程序中，连接可能会在此函数返回之后和信号发出之前更改。

bool QObject::isWidgetType() const

如果对象是窗口；否则返回 false。

调用此函数相当于调用 inherits("QWidget")，但速度更快。

bool QObject::isWindowType() const

如果对象是窗口；否则返回 false。

调用此函数相当于调用 inherits("QWindow")，但速度更快。

void QObject::killTimer(int id)

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

当定时器事件开始时，由 startTimer() 返回定时器标识符。

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

[纯虚函数] 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中重新启动（具有相同的间隔）。因此，不断在线程之间移动对象可以将计时器事件无限期推迟。

在更改线程亲和力之前，向此对象发送QEvent::ThreadChange事件。您可以通过处理此事件来完成任何特殊处理。注意，如果targetThread不是nullptr，则将在此对象上处理任何新发布的事件，并且在targetThread中处理，如果它是nullptr，则不对此对象或其子对象进行任何事件处理，因为它们不再与任何线程相关联。

另请参阅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()。

[保护] 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()。

[保护] QObject *QObject::sender() const

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

如果发送器被销毁，或从发送者的信号中断开槽，则此函数返回的指针变为无效。

另请参阅 senderSignalIndex()。

[保护] int QObject::senderSignalIndex() const

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

对于具有默认参数的信号，此函数将始终返回具有所有参数的索引，而不管使用connect()使用了哪个参数。例如，信号destroyed(QObject *obj = nullptr)将有两个不同的索引（带有参数和不带参数），但此函数始终返回带有参数的索引。这当用于过载具有不同参数的信号时不适用。

另请参阅：sender()，QMetaObject::indexOfSignal()和QMetaObject::method()。

void QObject::setObjectName(const QString &name)

将对象的名字设置为name。

另请参阅：objectName()。

[自 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()。

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

这个函数是对setProperty的重载。

此函数自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);

另请参阅：timerEvent()，killTimer()和QTimer::singleShot()。

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

这是一个重载函数。

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

在调用 killTimer() 之前，每当没有更多窗口系统事件处理时，计数器事件将每 interval 次出现一次。如果 interval 等于 std::chrono::duration::zero()，则每次没有更多窗口系统事件处理时计时器事件发生一次。

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

如果正在运行多个计时器，则可以使用 QTimerEvent::timerId() 来找出哪个计时器被激活。

示例

class MyObject : public QObject
{
    Q_OBJECT

public:
    MyObject(QObject *parent = nullptr);

protected:
    void timerEvent(QTimerEvent *event) override;
};

MyObject::MyObject(QObject *parent)
    : QObject(parent)
{
    startTimer(50);     // 50-millisecond timer
    startTimer(1000);   // 1-second timer
    startTimer(60000);  // 1-minute timer

    using namespace std::chrono;
    startTimer(milliseconds(50));
    startTimer(seconds(1));
    startTimer(minutes(1));

    // since C++14 we can use std::chrono::duration literals, e.g.:
    startTimer(100ms);
    startTimer(5s);
    startTimer(2min);
    startTimer(1h);
}

void MyObject::timerEvent(QTimerEvent *event)
{
    qDebug() << "Timer ID:" << event->timerId();
}

请注意，QTimer 的精度取决于底层操作系统和硬件。《i translate="no">timerType》参数允许您自定义计时器的精度。有关不同计时器类型的信息，请参阅Qt::TimerType。大多数平台支持20毫秒的精度；有些提供更高的精度。如果 Qt 无法传递请求的计时器事件数量，它将以静默方式丢弃一些。

QTimer 类提供了一种高级编程接口，其中使用了单次计时的计时器和计时器信号，而不是事件。还有一个更轻量级的 QBasicTimer 类，它比 QTimer 更轻量级，比直接使用计时器 ID 更易于使用。

另请参阅：timerEvent()，killTimer()和QTimer::singleShot()。

QThread *QObject::thread() const

返回对象所生活的线程。

另请参阅 moveToThread（）。

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

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

QTimer 提供了一个更高级别的计时器功能接口，以及有关计时器的更一般信息。计时器事件通过 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 的翻译机制的一般描述，以及有关 Disambiguate Identical Text 部分以获取歧义解决信息。

另请参阅QCoreApplication::translate() 和 Qt 国际化.