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 为 true，该对象发出的信号将被阻塞（即发出的信号不会调用与之相连的任何内容）。如果block 为 false，则不会发生这种阻塞。

返回值是signalsBlocked() 之前的值。

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

被阻塞时发出的信号不会被缓冲。

另请参见 signalsBlocked() 和QSignalBlocker 。

[virtual protected] 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

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

typedef QList<QObject*> QObjectList;

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

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

另请参阅 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 的连接。返回一个连接句柄，用于稍后断开连接。

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

该函数的工作方式与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 到receiver 对象中的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 无法验证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)

此函数重载 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");
    });

如果发送方被销毁，连接将自动断开。但是，在信号发出时，必须确保函数中使用的任何对象仍然有效。

因此，建议使用 connect() 的重载，它也将QObject 作为接收器/上下文。通过定义QT_NO_CONTEXTLESS_CONNECT 宏，可以禁用无上下文重载。

重载函数可通过qOverload 解决。

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

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

此函数重载 connect()。

将signal 从sender 对象连接到此对象的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)

此函数重载 connect()。

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

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

举例说明

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);

如果发送方或上下文被破坏，连接将自动断开。不过，在信号发出时，必须确保函数中使用的对象仍然有效。

重载函数可通过qOverload 解决。

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

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

此函数重载 connect()。

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

信号必须是在标头中声明为信号的函数。槽函数可以是任何可以连接到信号的成员函数。如果信号的参数数至少与槽的参数数相同，且信号和槽中相应参数的类型之间存在隐式转换，则槽可以连接到给定的信号。

举例说明

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

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

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

如果一个信号与多个插槽相连，当信号发出时，这些插槽将按照连接的顺序被激活。

如果函数成功地将信号连接到槽，则返回一个连接句柄。如果无法创建连接，例如QObject 无法验证signal 的存在（如果它未被声明为信号），则连接句柄将无效。您可以通过将QMetaObject::Connection 转换为 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().)

请确保使用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()，对象将在线程结束时被销毁。

需要注意的是，进入和离开一个新的事件循环（例如打开一个模态对话框）不会执行延迟删除；要删除对象，控件必须返回到调用 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)

该信号会在QPointer 的任何实例被通知后，立即在对象obj 销毁前发出，且不能被阻止。

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

另请参见 deleteLater() 和QPointer 。

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

断开连接。

如果connection 无效或已断开连接，则什么也不做并返回 false。

另请参阅 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 实例表示的不是信号。

为避免不匹配，请存储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. 断开与对象信号相连的所有连接：

   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);

为避免不匹配，请存储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

该函数重载了 disconnect()。

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

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

当涉及的任何一个对象被销毁时，信号槽连接就会被移除。

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

该函数重载了 disconnect()。

断开signal 与receiver 的method 的连接。

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

当涉及的任何一个对象被销毁时，信号槽连接就会被移除。

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

[static] template <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 与任何信号的连接。如果不是，则只断开指定信号的连接。

如果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() 的信号参数是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 = newQTextEditsetCentralWidget(textEdit); textEdit->installEventFilter(this); }boolMainWindow::eventFilter(QObject*obj、 QEvent*event) {if(obj==textEdit) {if(event->type()==QEvent按键） { 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);

此示例返回QListWidget 的子代parentWidget ，它的直接父代：

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 参数为空，则匹配所有对象；如果参数为空，则只匹配objectName 为空的对象。除非options 指定了 FindDirectChildrenOnly 选项，否则搜索将递归进行。

下面的示例显示了如何查找指定parentWidget 的子QWidget的列表，该列表名为widgetname ：

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

此示例将返回作为parentWidget 子目录的所有QPushButtons：

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

此示例将返回作为parentWidget 直接子代的所有QPushButtons：

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

此函数重载 findChildren()。

返回该对象的子对象（可被转换为 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 ...protected:booleventFilter(QObject*obj、 QEvent*event) override; };boolKeyPressEater::eventFilter(QObject*obj、 QEvent*event) {if(event->type()==QEvent按键） { 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()。

[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 (isSignalConnected(valueChangedSignal)) {
    QByteArray data;
    data = get_the_value();       // expensive operation
    emit valueChanged(data);
}

正如上面的代码片段所示，使用该函数可以避免昂贵的操作或发出无人监听的信号。

另请参见 receivers()。

bool QObject::isWidgetType() const

如果对象是一个 widget，则返回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 中重新启动（间隔相同）。因此，在线程间不断移动对象可能会无限期推迟定时器事件。

在改变线程亲和性之前，会向该对象发送QEvent::ThreadChange 事件。您可以通过处理该事件来执行任何特殊处理。需要注意的是，发布到此对象的任何新事件都将在targetThread 中处理，前提是它不是nullptr ：当它是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()。

[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)

该函数重载了 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(),QChronoTimer, 和QBasicTimer 。

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

这是一个重载函数。

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

在调用killTimer() 之前，每隔interval 就会发生一次定时器事件。如果interval 等于std::chrono::duration::zero() ，则每当没有窗口系统事件需要处理时，定时器事件就会发生一次。

当定时器事件发生时，将调用带有QTimerEvent 事件参数类的虚拟timerEvent() 函数。重新实现该函数可获取定时器事件。

如果有多个定时器在运行，可使用QTimerEvent::id() 方法找出哪个定时器被激活。

示例

classMyObject :publicQObject
{ Q_OBJECTpublic: MyObject(QObject*parent =nullptr);protected:voidtimerEvent(QTimerEvent*event) override; }; MyObject::MyObject(QObject*父对象）： 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 的国际化。