qobjecttreemodel.cpp

#include "qobjecttreemodel.h"

#include <algorithm>
#include <memory>
#include <ranges>

#include <QtCore/QCoreApplication>
#include <QtCore/QDebug>
#include <QtCore/QEvent>
#include <QtCore/QThread>
#include <QtCore/private/qabstractitemmodel_p.h>
#include <QtCore/private/qobject_p.h>
#include <QtCore/qnamespace.h>

#ifdef QT_WIDGETS_LIB
#include <QtWidgets/QWidget>
#endif

using namespace Qt::Literals::StringLiterals;

namespace {
void InsertUniqueEventFilter(QObject *object, QObject *filter)
{
#if defined(QT_DEBUG)
    Q_ASSERT(object);
    Q_ASSERT(filter);

    auto *objectPriv = QObjectPrivate::get(object);
    if (auto *extraData = objectPriv->extraData) {
        Q_ASSERT(!extraData->eventFilters.contains(filter));
    }
#endif
    object->installEventFilter(filter);
}

void CheckRemoveEventFilter(QObject *object, QObject *filter)
{
#if defined(QT_DEBUG)
    Q_ASSERT(object);
    Q_ASSERT(filter);

    auto *objectPriv = QObjectPrivate::get(object);
    auto *extraData = objectPriv->extraData;
    Q_ASSERT(extraData);
    Q_ASSERT(extraData->eventFilters.contains(filter));
#endif
    object->removeEventFilter(filter);
}

bool IsValid(const QObject *obj)
{
    const auto *objPriv = QObjectPrivate::get(obj);
    return !(objPriv->deleteLaterCalled || objPriv->wasDeleted);
}

// Returns true if object1 is a descendant of object2.
bool IsDescendantOf(QObject *object1, QObject *object2)
{
    QObject *obj{object1};
    while (obj) {
        if (obj == object2) {
            return true;
        }
        obj = obj->parent();
    }
    return false;
}

// Clamp the requested index into the valid range for the parent's children
// list. Negative values index from the end (-1 = last, -2 = second-to-last).
// Values beyond the end are clamped.
qsizetype BoundIndex(QObject *object, QObject *parent, int index)
{
    qsizetype siblingCount{parent->children().count()};
    if (object->parent() == parent)
        siblingCount -= 1; // The object itself doesn't count.

    qsizetype b{std::min(static_cast<qsizetype>(index), siblingCount)};
    if (b < 0) {
        b = siblingCount + 1 + index;
        b = std::max(b, qsizetype{0});
    }
    return b;
}

// Minimal event filter that suppresses ChildRemoved / ChildAdded events for a
// specific target object and records which events were sent. Used by SetParent
// to defer events until after the children list has been reordered so that the
// model can detect move operations.
struct EventDeferrer final : QObject
{
    QObject *target;
    bool removedSeen = false;
    bool addedSeen = false;

    explicit EventDeferrer(QObject *t)
        : target(t)
    {}

    bool eventFilter(QObject *, QEvent *event) override
    {
        if (event->type() == QEvent::ChildRemoved) {
            if (static_cast<QChildEvent *>(event)->child() == target) {
                removedSeen = true;
                return true; // suppress
            }
        } else if (event->type() == QEvent::ChildAdded) {
            if (static_cast<QChildEvent *>(event)->child() == target) {
                addedSeen = true;
                return true; // suppress
            }
        }
        return false;
    }
};

// Cross-parent reparent for plain QObjects (non-widgets).
//
// Installs a temporary event filter to defer the ChildRemoved / ChildAdded
// events that |setParent_helper| sends inline, calls |QObject::setParent|,
// reorders the children list to honour the requested index, then replays the
// deferred events. By replay time child->parent() already points to the new
// parent so |handleChildRemovedEvent| can detect the move.
void SetQObjectParent(QObject *object, QObject *parent, qsizetype boundedIndex)
{
    auto *oldParent = object->parent();

    EventDeferrer deferrer(object);
    if (oldParent)
        oldParent->installEventFilter(&deferrer);
    parent->installEventFilter(&deferrer);

    object->setParent(parent);

    // Move the child from the append position to the requested index.
    auto &newSiblings = QObjectPrivate::get(parent)->children;
    const qsizetype currentIndex = newSiblings.indexOf(object);
    if (currentIndex >= 0 && currentIndex != boundedIndex)
        newSiblings.move(currentIndex, boundedIndex);

    // Remove the deferrer before replaying so the events reach the real
    // event filters (including the model's).
    if (oldParent)
        oldParent->removeEventFilter(&deferrer);
    parent->removeEventFilter(&deferrer);

    // Replay in the original order: ChildRemoved first, then ChildAdded.
    if (deferrer.removedSeen) {
        QChildEvent e(QEvent::ChildRemoved, object);
        QCoreApplication::sendEvent(oldParent, &e);
    }

    if (deferrer.addedSeen) {
        QChildEvent e(QEvent::ChildAdded, object);
        QCoreApplication::sendEvent(parent, &e);
    }
}

#ifdef QT_WIDGETS_LIB
// Cross-parent reparent for QWidgets.
//
// Delegates to |QWidget::setParent| to ensure proper window-system setup,
// visibility propagation, style inheritance, etc.
//
// |QWidget::setParent| may or may not send ChildRemoved / ChildAdded through
// platform-specific code paths (|setParent_sys|). Rather than assuming which
// events fire, we install the deferrer on BOTH old and new parents to catch
// whatever is sent, then replay after the children list is reordered. If
// ChildRemoved was not sent during |QWidget::setParent| (as is expected from
// |setParent_helper|'s suppression for widgets), we send it manually so the
// model can detect the move.
void SetQWidgetParent(QObject *object, QObject *parent, qsizetype boundedIndex)
{
    auto *widget = static_cast<QWidget *>(object);
    auto *widgetParent = static_cast<QWidget *>(parent);
    auto *oldParent = object->parent();

    // Install on both parents. Event filters are LIFO so the deferrer
    // (installed last) runs before the model's own filter.
    EventDeferrer deferrer(object);
    if (oldParent)
        oldParent->installEventFilter(&deferrer);
    parent->installEventFilter(&deferrer);

    widget->setParent(widgetParent);

    // Move the child from the append position to the requested index.
    auto &newSiblings = QObjectPrivate::get(parent)->children;
    const qsizetype currentIndex = newSiblings.indexOf(object);
    if (currentIndex >= 0 && currentIndex != boundedIndex)
        newSiblings.move(currentIndex, boundedIndex);

    // Remove the deferrer before replaying so the events reach the real
    // event filters (including the model's).
    if (oldParent)
        oldParent->removeEventFilter(&deferrer);
    parent->removeEventFilter(&deferrer);

    // Ensure ChildRemoved reaches the old parent. If QWidget::setParent
    // already sent it (caught by the deferrer), we replay. If it was
    // suppressed (the typical case for widgets in setParent_helper), we
    // send it manually. Either way the model needs to see it for move
    // detection — child->parent() already points to the new parent.
    if (oldParent) {
        auto *pObject = QObjectPrivate::get(object);
        auto *pOldParent = QObjectPrivate::get(oldParent);
        if (pObject->sendChildEvents && pOldParent->receiveChildEvents) {
            QChildEvent e(QEvent::ChildRemoved, object);
            QCoreApplication::sendEvent(oldParent, &e);
        }
    }

    // Replay or send ChildAdded. The deferrer may or may not have seen it
    // depending on the platform; the model's handleChildAddedEvent is
    // idempotent (no-op if already tracked after the move above).
    if (deferrer.addedSeen) {
        QChildEvent e(QEvent::ChildAdded, object);
        QCoreApplication::sendEvent(parent, &e);
    }
}
#endif

} // namespace

QObject *QObjectTreeModel::GetParent(QObject *object)
{
    if (!object) {
        return nullptr;
    }
    return object->parent();
}

bool QObjectTreeModel::IsAncestorOf(QObject *ancestor, QObject *descendant)
{
    if (!ancestor || !descendant)
        return false;
    return IsDescendantOf(descendant, ancestor);
}

// Reparents |object| under |parent| at a specific child index.
//
// Supports both QObject and QWidget children. For QWidgets, delegates to
// |QWidget::setParent| to ensure proper window-system setup; for plain
// QObjects, delegates to |QObject::setParent|. In both cases a temporary event
// filter defers ChildRemoved / ChildAdded events until after the children list
// has been reordered so that the model can detect move operations.
//
// A QWidget can only be a child of another QWidget. A plain QObject can be a
// child of either a QObject or a QWidget.
//
// For same-parent reorders both |QObject::setParent| and |QWidget::setParent|
// are no-ops (they return early when the parent hasn't changed) so the children
// list is reordered directly and a ChildRemoved event is sent manually so the
// model can detect the in-place move.
bool QObjectTreeModel::SetParent(QObject *object, QObject *parent, const int index)
{
    Q_ASSERT(object);
    if (!object) {
        return false;
    }

    // Validate the QWidget parentage rule: a QWidget can only be a child of
    // another QWidget. A plain QObject can be a child of anything.
    if (object->isWidgetType() && parent && !parent->isWidgetType()) {
        Q_ASSERT_X(false, "SetParent", "A QWidget can only be parented to a QWidget.");
        return false;
    }

    // Delegate unparenting directly — no reordering needed, and the model's
    // existing event filter on the old parent will handle ChildRemoved.
    if (!parent) {
#ifdef QT_WIDGETS_LIB
        if (object->isWidgetType()) {
            static_cast<QWidget *>(object)->setParent(static_cast<QWidget *>(nullptr));
            return true;
        }
#endif
        object->setParent(nullptr);
        return true;
    }

    const bool isDescendantOf = IsDescendantOf(parent, object);
    if (isDescendantOf) {
        const auto error = "Cannot set parent: would create a circular hierarchy.";
        Q_ASSERT_X(!isDescendantOf, "SetParent", error);
        qWarning() << error;
        return false;
    }

    const bool isOnSameThread = object->thread() == parent->thread();
    if (!isOnSameThread) {
        const auto error = "Cannot set parent, new parent is in a different thread.";
        Q_ASSERT_X(isOnSameThread, "SetParent", error);
        qWarning() << error;
        return false;
    }

    const bool isOnCurrentThread = object->thread() == QThread::currentThread();
    if (!isOnCurrentThread) {
        const auto error = "Cannot call SetParent from different thread to object thread.";
        Q_ASSERT_X(isOnCurrentThread, "SetParent", error);
        qWarning() << error;
        return false;
    }

    const qsizetype boundedIndex = BoundIndex(object, parent, index);

    auto *oldParent = object->parent();

    // -----------------------------------------------------------------------
    // Same-parent reorder
    // -----------------------------------------------------------------------
    // Both |QObject::setParent| and |QWidget::setParent| are no-ops when the
    // parent hasn't changed, so we reorder |QObjectPrivate::children| directly
    // and send a |ChildRemoved| event manually so that the model's
    // |handleChildRemovedEvent| can detect the in-place move.
    if (oldParent == parent) {
        auto &siblings = QObjectPrivate::get(parent)->children;
        const qsizetype oldIndex = siblings.indexOf(object);
        if (oldIndex == boundedIndex)
            return true;

        siblings.move(oldIndex, boundedIndex);

        auto *pObject = QObjectPrivate::get(object);
        if (pObject->sendChildEvents && QObjectPrivate::get(parent)->receiveChildEvents) {
            QChildEvent e(QEvent::ChildRemoved, object);
            QCoreApplication::sendEvent(parent, &e);
        }
        return true;
    }

    // -----------------------------------------------------------------------
    // Cross-parent move / fresh insertion (oldParent may be nullptr)
    // -----------------------------------------------------------------------
    // Dispatch to the appropriate implementation based on whether the object
    // is a QWidget. The QWidget path uses QWidget::setParent for proper
    // window-system setup; the QObject path uses QObject::setParent.
    if (object->isWidgetType() && parent->isWidgetType()) {
#ifdef QT_WIDGETS_LIB
        SetQWidgetParent(object, parent, boundedIndex);
        return true;
#else
        qWarning() << "Cannot set QWidget parent without linking to Qt::Widgets.";
        return false;
#endif
    }
    SetQObjectParent(object, parent, boundedIndex);
    return true;
}

bool QObjectTreeModel::SetParent(QObject *object, QObject *parent)
{
    int index = 0;
    if (parent) {
        index = static_cast<int>(parent->children().size());
    }
    return SetParent(object, parent, index);
}

QObjectTreeModel::QObjectTreeModel(QObject *parent)
    : QAbstractItemModel(parent)
{
    setRoot(nullptr);
}

std::unique_ptr<QObjectTreeModel> QObjectTreeModel::CreateWithRoot(QObject *root, QObject *parent)
{
    std::unique_ptr<QObjectTreeModel> model(new QObjectTreeModel(parent));
    if (root)
        model->setRoot(root);
    return model;
}
QObjectTreeModel::~QObjectTreeModel()
{
    // Remove event filters and signal connections from every tracked
    // object. For an external root whose subtree outlives the model.
    for (const auto &[child, parent] : m_childParentMap) {
        disconnectObject(child);
    }
}

// Q_INVOKABLE
QObject *QObjectTreeModel::objectFromIndex(const QModelIndex &index) const
{
    if (!index.isValid())
        return nullptr;

    if (index.model() != this)
        return nullptr;

    auto *object = static_cast<QObject *>(index.internalPointer());
    return object;
}

QVariant QObjectTreeModel::data(const QModelIndex &index, int role) const
{
    if (!index.isValid())
        return {};

    if (index.model() != this)
        return {};

    auto *object = static_cast<QObject *>(index.internalPointer());

    if (role == Qt::DisplayRole)
        return object->objectName();
    if (role == static_cast<int>(QObjectTreeModel::Roles::ObjectName))
        return object->objectName();
    if (role == static_cast<int>(QObjectTreeModel::Roles::MetaTypeName))
        return QString::fromUtf8(object->metaObject()->className());

    return {};
}

int QObjectTreeModel::rowCount(const QModelIndex &parent) const
{
    if (parent.isValid() && parent.model() != this)
        return 0;

    auto *parentObject = static_cast<QObject *>(parent.internalPointer());
    if (!parent.isValid()) {
        // Only the root object (i.e. invalid parent QModelIndex) can be
        // accessed via nullptr from the |m_parentChildMap|.
        Q_ASSERT(parentObject == nullptr);
        // During setRoot() the maps are transiently empty between clear() and
        // populateFromObjectRecursive(). Views may query during
        // beginResetModel/endResetModel, so only assert the invariant when
        // the map is populated.
        if (m_parentChildMap.contains(nullptr)) {
            Q_ASSERT(m_parentChildMap.at(nullptr).size() == 1);
            Q_ASSERT(m_parentChildMap.at(nullptr)[0] == m_root);
        }
    }

    const auto it = m_parentChildMap.find(parentObject);
    if (it == m_parentChildMap.end()) {
        return 0;
    }

    return static_cast<int>(it->second.size());
}

int QObjectTreeModel::columnCount(const QModelIndex &parent) const
{
    if (parent.isValid() && parent.model() != this)
        return 0;

    // We only have one data column (i.e. the Object*).
    return 1;
}

bool QObjectTreeModel::hasChildren(const QModelIndex &parent) const
{
    if (parent.isValid() && parent.model() != this)
        return false;

    auto *parentObject = static_cast<QObject *>(parent.internalPointer());
    const auto it = m_parentChildMap.find(parentObject);
    return it != m_parentChildMap.end() && !it->second.empty();
}

QModelIndex QObjectTreeModel::parent(const QModelIndex &child) const
{
    if (!child.isValid()) {
        return QModelIndex();
    }

    if (child.model() != this)
        return QModelIndex();

    // From docs:
    // > If the model index specified corresponds to a top-level item in the
    // > model, or if there is no valid parent item in the model, the function
    // > must return an invalid model index, created with the empty QModelIndex()
    // > constructor.
    // https://doc.qt.io/qt-6/model-view-programming.html#navigation-and-model-index-creation
    //
    // The below will meet the above requirement as if internalPointer() returns
    // |m_root| then |m_childParentMap| will give |nullptr| as the
    // parent causing |indexOf| to return an invalid model index.
    auto *childObject = static_cast<QObject *>(child.internalPointer());

    // Use find() rather than at() so that a stale QModelIndex (one whose
    // internal pointer is no longer tracked by the model) does not throw
    // std::out_of_range.
    auto it = m_childParentMap.find(childObject);
    if (it == m_childParentMap.end())
        return QModelIndex();

    auto *parentObject = it->second;
    if (childObject == m_root) {
        Q_ASSERT(parentObject == nullptr);
    }
    return indexOf(parentObject);
}

QModelIndex QObjectTreeModel::index(int row, int column, const QModelIndex &parent) const
{
    if (parent.isValid() && parent.model() != this)
        return {};

    auto *parentObject = static_cast<QObject *>(parent.internalPointer());
    if (!parent.isValid()) {
        // Only the root object (i.e. invalid parent QModelIndex) can be
        // accessed via nullptr from the |m_parentChildMap|.
        Q_ASSERT(parentObject == nullptr);
        // During setRoot() the maps are transiently empty between clear() and
        // populateFromObjectRecursive(). Views may query during
        // beginResetModel/endResetModel, so only assert the invariant when
        // the map is populated.
        if (m_parentChildMap.contains(nullptr)) {
            Q_ASSERT(m_parentChildMap.at(nullptr).size() == 1);
            Q_ASSERT(m_parentChildMap.at(nullptr)[0] == m_root);
        }
    }

    auto it = m_parentChildMap.find(parentObject);
    if (it == m_parentChildMap.end()) {
        return {};
    }

    const QObjectList &children{it->second};
    if (row < 0 || column < 0 || row >= static_cast<int>(children.size())
        || column >= columnCount()) {
        return {};
    }
    return createIndex(row, column, children[row]);
}

QModelIndex QObjectTreeModel::sibling(int row, int column, const QModelIndex &index) const
{
    if (!index.isValid())
        return {};

    if (index.model() != this)
        return {};

    if (row < 0 || column < 0 || column >= columnCount())
        return {};

    // Look up the parent of the object at |idx|.
    auto *object = static_cast<QObject *>(index.internalPointer());
    auto childIt = m_childParentMap.find(object);
    if (childIt == m_childParentMap.end())
        return {};

    // Look up the sibling list from the parent.
    auto *parentObject = childIt->second;
    auto parentIt = m_parentChildMap.find(parentObject);
    if (parentIt == m_parentChildMap.end())
        return {};

    const QObjectList &siblings{parentIt->second};
    if (row >= static_cast<int>(siblings.size()))
        return {};

    return createIndex(row, column, siblings[row]);
}

QMap<int, QVariant> QObjectTreeModel::itemData(const QModelIndex &index) const
{
    if (index.isValid() && index.model() != this)
        return {};

    // Start with the standard roles provided by the base class.
    QMap<int, QVariant> result = QAbstractItemModel::itemData(index);

    // The base implementation only queries the standard Qt roles.  Append our
    // custom roles so that callers (and QAbstractItemModelTester) see a
    // complete picture.
    static constexpr int customRoles[] = {
        static_cast<int>(Roles::ObjectName),
        static_cast<int>(Roles::MetaTypeName),
    };
    for (int role : customRoles) {
        const QVariant value = data(index, role);
        if (value.isValid())
            result.insert(role, value);
    }

    return result;
}

QHash<int, QByteArray> QObjectTreeModel::roleNames() const
{
    static QHash<int, QByteArray> s_roleNames = []() {
        auto roleNames = QAbstractItemModelPrivate::defaultRoleNames();
        roleNames[static_cast<int>(QObjectTreeModel::Roles::ObjectName)] = "objectName";
        roleNames[static_cast<int>(QObjectTreeModel::Roles::MetaTypeName)] = "metaTypeName";
        return roleNames;
    }();
    return s_roleNames;
}

bool QObjectTreeModel::moveRows(const QModelIndex &sourceParent,
                                int sourceRow,
                                int count,
                                const QModelIndex &destinationParent,
                                int destinationRow)
{
    if ((sourceParent.isValid() && sourceParent.model() != this)
        || (destinationParent.isValid() && destinationParent.model() != this))
        return false;

    if (count != 1) {
        qWarning() << u"QObjectTreeModel::moveRows only supports a count of 1 (count = %0)"_s.arg(
            count);
        return false;
    }
    if (!sourceParent.isValid()) {
        qWarning() << "QObjectTreeModel::moveRows does not support an invalid "
                      "sourceParent index. Use indexOf(root()) to move objects "
                      "under the root.";
        return false;
    }
    if (!destinationParent.isValid()) {
        qWarning() << "QObjectTreeModel::moveRows does not support an invalid "
                      "destinationParent index. Use indexOf(root()) to move "
                      "objects under the root.";
        return false;
    }
    if (sourceRow < 0) {
        qWarning() << u"QObjectTreeModel::moveRows does not support negative sourceRow values (sourceRow = %0)"_s
                          .arg(sourceRow);
        return false;
    }
    if (destinationRow < 0) {
        qWarning() << u"QObjectTreeModel::moveRows does not support negative destinationRow values (destinationRow = %0)"_s
                          .arg(destinationRow);
        return false;
    }
    if (sourceRow >= rowCount(sourceParent)) {
        qWarning() << u"QObjectTreeModel::moveRows: sourceRow (%0) is out of range (rowCount = %1)"_s
                          .arg(sourceRow)
                          .arg(rowCount(sourceParent));
        return false;
    }
    if (destinationRow > rowCount(destinationParent)) {
        qWarning() << u"QObjectTreeModel::moveRows: destinationRow (%0) exceeds row count (%1)"_s
                          .arg(destinationRow)
                          .arg(rowCount(destinationParent));
        return false;
    }

    auto *destParent = static_cast<QObject *>(destinationParent.internalPointer());

    // Get the child that is being moved.
    auto modelIndex = index(sourceRow, 0, sourceParent);
    if (!modelIndex.isValid())
        return false;

    QObject *child = static_cast<QObject *>(modelIndex.internalPointer());

    int index{destinationRow};

    // If moving within the same parent then we need to modify index to take into
    // account no-ops.
    QObject *currentParent{static_cast<QObject *>(sourceParent.internalPointer())};
    if (currentParent == destParent) {
        if (destinationRow > sourceRow) {
            index--;
        }

        // Skip no-op moves.
        if (currentParent->children().indexOf(child) == static_cast<qsizetype>(index)) {
            return false;
        }
    }

    return QObjectTreeModel::SetParent(child, destParent, index);
}

QModelIndex QObjectTreeModel::indexOf(QObject *object) const
{
    if (!object)
        return {};

    // Get the parent for the Object.
    QObject *parent{nullptr};
    if (auto it = m_childParentMap.find(object); it != m_childParentMap.end())
        parent = it->second;

    // Only the root object can have nullptr for the parent.
    if (!parent && object != m_root) {
        return {};
    }

    // Get the objects known siblings. Use find() rather than at() to avoid
    // throwing if the parent is not (or no longer) tracked.
    auto it = m_parentChildMap.find(parent);
    if (it == m_parentChildMap.end())
        return {};

    const QObjectList &siblings{it->second};

    // If the object does not exist among the parents known children then return
    // an invalid model index.
    qsizetype index{siblings.indexOf(object)};
    if (index < 0)
        return {};

    return createIndex(static_cast<int>(index), 0, object);
}

QObject *QObjectTreeModel::root() const
{
    return m_root;
}
void QObjectTreeModel::setRoot(QObject *root)
{
    if (m_root && m_root == root) {
        return;
    }

    if (root && root->thread() != this->thread()) {
        // Qt guarantees that all children share their parent's thread affinity,
        // so asserting the root alone is sufficient to guarantee the entire
        // subtree is on the model's thread.
        Q_ASSERT_X(false,
                   "QObjectTreeModel::setRoot",
                   "The root QObject must have the same thread affinity as the model. "
                   "All tracked objects rely on DirectConnection signals and event "
                   "filters which require same-thread affinity.");
        return;
    }

    beginResetModel();

    // Clean up old state: disconnect event filters and signal connections from
    // all objects currently tracked by the model.
    for (const auto &[object, parent] : m_childParentMap) {
        disconnectObject(object);
    }
    m_childParentMap.clear();
    m_parentChildMap.clear();

    // If the previous root was internally created (parented to this model),
    // delete it to avoid a memory leak.
    QObject *oldRoot = m_root;

    // If root is null then create and manage an internal root object that
    // children can be parented to.
    if (!root) {
        m_root = new QObject(this);
        m_root->setObjectName("Root");
    } else {
        m_root = root;
    }

    // Delete the old internal root after setting m_root so that any events
    // triggered by the deletion don't reference stale state.
    if (oldRoot && oldRoot->parent() == this) {
        // If the new root is a descendant of the old internal root, reparent it
        // first so that deleteLater() on the old root doesn't destroy the new
        // root along with the rest of its subtree.
        for (QObject *ancestor = m_root->parent(); ancestor; ancestor = ancestor->parent()) {
            if (ancestor == oldRoot) {
                m_root->setParent(this);
                break;
            }
        }
        oldRoot->deleteLater();
    }

    populateFromObjectRecursive(m_root);

    endResetModel();

    Q_EMIT rootChanged();
}

bool QObjectTreeModel::insertRows(int, int, const QModelIndex & /*index*/)
{
    constexpr auto error = "QObjectTreeModel::insertRows Not implemented";
    Q_ASSERT_X(false, "QObjectTreeModel::insertRows", error);
    qWarning() << error;
    return false;
}
bool QObjectTreeModel::insertColumns(int, int, const QModelIndex & /*index*/)
{
    constexpr auto error = "QObjectTreeModel::insertColumns Not implemented";
    Q_ASSERT_X(false, "QObjectTreeModel::insertColumns", error);
    qWarning() << error;
    return false;
}

bool QObjectTreeModel::removeRows(int row, int count, const QModelIndex &parent)
{
    if (parent.isValid() && parent.model() != this)
        return false;

    if (count < 0) {
        qWarning() << u"QObjectTreeModel::removeRows does not support negative counts (count = %0)"_s
                          .arg(count);
        return false;
    }
    if (row < 0) {
        qWarning() << u"QObjectTreeModel::removeRows does not support negative row values (row = %0)"_s
                          .arg(row);
        return false;
    }
    if (count == 0)
        return true;

    // An invalid parent means the caller is potentially trying to remove the
    // root, which is not supported.
    if (!parent.isValid()) {
        qWarning() << "QObjectTreeModel::removeRows does not support an invalid "
                      "parent index. Removing the root object is prohibited.";
        return false;
    }

    auto *parentObject = static_cast<QObject *>(parent.internalPointer());
    auto siblingIt = m_parentChildMap.find(parentObject);
    Q_ASSERT(siblingIt != m_parentChildMap.end());
    if (siblingIt == m_parentChildMap.end())
        return false;
    QObjectList &siblings{siblingIt->second};

    if (row + count > static_cast<int>(siblings.size())) {
        qWarning() << u"QObjectTreeModel::removeRows: row (%0) + count (%1) exceeds row count (%2)"_s
                          .arg(row)
                          .arg(count)
                          .arg(static_cast<int>(siblings.size()));
        return false;
    }

    // Collect the children to be removed, disconnect them from the model, and
    // unparent them in a single begin/endRemoveRows block so that views only
    // receive one notification.
    QObjectList toDelete;
    toDelete.reserve(count);

    beginRemoveRows(parent, row, row + count - 1);
    for (int i = 0; i < count; i++) {
        QObject *child{siblings[row]};

        siblings.removeAt(row);
        removeAndDisconnectSubtree(child);

        // Unparent the child. This will trigger a ChildRemoved event on the
        // parent but since we have already removed the child from the maps,
        // handleChildRemovedEvent will find nothing and return immediately.
        Q_ASSERT(!m_childParentMap.contains(child));
        child->setParent(nullptr);

        toDelete.push_back(child);
    }
    endRemoveRows();

    // Schedule deletion after the model has finished updating so that
    // delegates and views have a chance to clean up before the objects
    // are destroyed.
    for (QObject *child : toDelete)
        child->deleteLater();

    return true;
}

QObjectList QObjectTreeModel::takeRows(int row, int count, const QModelIndex &parent)
{
    auto result = QObjectList{};

    if (parent.isValid() && parent.model() != this)
        return result;

    if (count < 0) {
        qWarning() << u"TakeRows does not support negative counts (count = %0)"_s.arg(count);
        return result;
    }
    if (row < 0) {
        qWarning() << u"QObjectTreeModel::TakeRows does not support negative row values (row = %0)"_s
                          .arg(row);
        return result;
    }
    // If the count is zero then there is no work to do.
    if (count == 0) {
        return result;
    }

    // An invalid parent means that the caller is potentially trying to remove
    // |m_root| which is not supported.
    if (!parent.isValid()) {
        qWarning() << "QObjectTreeModel::TakeRows does not support an invalid "
                      "parent index. Removing "
                      "the root object is prohibited.";
        return result;
    }

    auto *parentObject = static_cast<QObject *>(parent.internalPointer());
    auto siblingIt = m_parentChildMap.find(parentObject);
    Q_ASSERT(siblingIt != m_parentChildMap.end());
    if (siblingIt == m_parentChildMap.end())
        return result;
    QObjectList &siblings{siblingIt->second};

    if (row + count > static_cast<int>(siblings.size())) {
        qWarning() << u"QObjectTreeModel::takeRows: row (%0) + count (%1) exceeds row count (%2)"_s
                          .arg(row)
                          .arg(count)
                          .arg(static_cast<int>(siblings.size()));
        return result;
    }

    result.reserve(count);

    beginRemoveRows(parent, row, row + count - 1);
    for (int i = 0; i < count; i++) {
        QObject *child{siblings[row]};

        // Remove the child from the model.
        siblings.removeAt(row);            // Removes it from the parents child map
        removeAndDisconnectSubtree(child); // Removes it as a key value in all maps

        // Set the parent to nullptr, this will cause a child removed event for the
        // parent but given we have already removed the object sub-tree from the
        // model |handleChildRemovedEvent| will do nothing.
        Q_ASSERT(!m_childParentMap.contains(child));
        child->setParent(nullptr);

        // We now take ownership of the |child| object and delete it after calling
        // |endRemoveRows| so that delegates have a chance to be deleted before the
        // model objects.
        result.push_back(child);
    }
    endRemoveRows();

    return result;
}

QObjectList QObjectTreeModel::takeAllRows(const QModelIndex &parent)
{
    if (parent.isValid() && parent.model() != this)
        return {};

    // If called with empty args (default index constructor) then take all rows
    // from the root.
    auto adjustedParent = parent.isValid() ? parent : indexOf(m_root);
    return takeRows(0, rowCount(adjustedParent), adjustedParent);
}

bool QObjectTreeModel::eventFilter(QObject *object, QEvent *event)
{
    if (event->type() == QEvent::ChildAdded) {
        auto *childEvent = static_cast<QChildEvent *>(event);
        auto *child = childEvent->child();
        Q_ASSERT(child);

        // If the added child has already had deleteLater called on it then don't
        // add it to the model to avoid churn.
        if (!IsValid(child)) {
            return QObject::eventFilter(object, event);
        }

        // Check Qt has setup the parent relationship correctly.
        Q_ASSERT_X(object == child->parent(),
                   "QObjectTreeModel::eventFilter",
                   "Added child has the wrong parent.");

        handleChildAddedEvent(child);
    } else if (event->type() == QEvent::ChildRemoved) {
        auto *childEvent = static_cast<QChildEvent *>(event);
        auto *child = childEvent->child();
        handleChildRemovedEvent(child, object);
    } else if (event->type() == QEvent::DeferredDelete) {
        Q_ASSERT(object);
        if (object != m_root) {
            // Verify that Qt has not removed the object from the parent's "children"
            // list by this point.
            Q_ASSERT_X(object->parent(),
                       "QObjectTreeModel::eventFilter",
                       (QDebug::toString(object) + " has no parent.").toStdString().c_str());
            Q_ASSERT(object->parent()->children().contains(object));
        }

        // Remove the child from the model.
        handleDeferredDeleteEvent(object);
    } else if (event->type() == QEvent::ThreadChange) {
        // If an object is moving thread then it must have started on the
        // QObjectTreeModels thread for it to be in the model and have an event
        // filter installed..
        //
        // This should never happen for any child objects in the tree as the
        // docs state that:
        //
        // > "The object cannot be moved if it has a parent."
        //
        // and also:
        //
        // > "This is the last event sent to the object in the previous thread."
        //
        // So the only object valid for moving would be an external root object
        // with no parent. That is the case handled here.
        Q_ASSERT(object == m_root);
        setRoot(nullptr);
    } else if (event->type() == QEvent::ParentChange) {
        // QWidget::setParent sends ParentChange to the reparented widget after
        // the parent has been updated. Qt suppresses the ChildAdded/ChildRemoved
        // events for QWidgets in QObjectPrivate::setParent_helper, so this event
        // is the only reliable notification for QWidget reparents performed via
        // the normal QWidget::setParent(QWidget*) API.
        //
        // Note: QObject::setParent() does NOT send ParentChange (only the
        // QWidget override does), so calling QObject::setParent() directly on a
        // QWidget remains undetectable — but that's a programming error in Qt.
        handleParentChangeEvent(object);
    }

    return QObject::eventFilter(object, event);
}

void QObjectTreeModel::populateFromObjectRecursive(QObject *object)
{
    // The root object is a special case as it should have a nullptr to indicate
    // that it is a root node in the QAbstractItemModel.
    QObject *parentObject = nullptr;
    if (object != m_root) {
        // All other objects must have a parent chain that stems from the root
        // object.
        parentObject = object->parent();
        Q_ASSERT(parentObject);
    }

    connectObject(object);

    Q_ASSERT(!m_childParentMap.contains(object));
    m_childParentMap[object] = parentObject;
    m_parentChildMap[parentObject].push_back(object);
    m_parentChildMap[object] = {};

    std::ranges::for_each(object->children(),
                          [&](QObject *child) { populateFromObjectRecursive(child); });
}

void QObjectTreeModel::connectObject(QObject *object)
{
    // The root's thread affinity is checked in |setRoot| and Qt enforces
    // same-thread for parent/child, so this should never fire
    // unless an object has been moved to a different thread after being
    // parented (which would be a Qt misuse by the application).
    if (object->thread() != this->thread()) {
        Q_ASSERT_X(false,
                   "QObjectTreeModel::connectObject",
                   "Tracked QObject has a different thread affinity than the model.");
        return;
    }

    InsertUniqueEventFilter(object, this);

    // DirectConnection is safe here because we assert same-thread affinity
    // above. It is also *required* for the destroyed signal: it must fire
    // synchronously during ~QObject so we can remove the still-intact subtree
    // before deleteChildren() frees the descendants.
    connect(object,
            &QObject::destroyed,
            this,
            &QObjectTreeModel::handleObjectDestroyed,
            Qt::DirectConnection);
    connect(
        object,
        &QObject::objectNameChanged,
        this,
        [this, object]() { handleObjectNameChanged(object); },
        Qt::DirectConnection);
}

void QObjectTreeModel::disconnectObject(QObject *object)
{
    Q_ASSERT(object);
    CheckRemoveEventFilter(object, this);
    object->disconnect(this);
}

void QObjectTreeModel::handleChildAddedEvent(QObject *child)
{
    Q_ASSERT(child);
    // The child may already be tracked if:
    //   - A ChildRemoved event was converted to a move operation, or
    //   - For QWidgets, handleParentChangeEvent already processed the
    //     reparent before this ChildAdded arrived.
    // In either case there is nothing more to do. If the recorded parent
    // differs from the actual parent (i.e. ParentChange hasn't run yet),
    // the upcoming ParentChange or ChildRemoved event will reconcile.
    if (m_childParentMap.contains(child)) {
        return;
    }

    if (child == child->parent()->children().last()) {
        appendChildObjects({child});
    } else {
        qsizetype insertIndex{child->parent()->children().indexOf(child)};
        Q_ASSERT(insertIndex >= 0);

        // Insert the newly added child plus any of its children recursively.
        insertChildObjects({child}, insertIndex);
    }
}

void QObjectTreeModel::handleChildRemovedEvent(QObject *child, QObject *eventParent)
{
    // The child may have already been removed from the model if:
    //   - It was sent a DeferredDelete event (deleteLater path), or
    //   - It was raw-deleted and handleObjectDestroyed already cleaned it up.
    auto it = m_childParentMap.find(child);
    if (it == m_childParentMap.end())
        return;

    // Get the parent the child was parented to.
    QObject *oldParent{it->second};

    // If the model's recorded parent doesn't match the parent that sent this
    // ChildRemoved, the event is stale — a ParentChange handler (or another
    // path) already moved the child to its new parent. Nothing to do.
    if (oldParent != eventParent)
        return;

    const QModelIndex oldParentIndex{indexOf(oldParent)};

    // Check that Qt hasn't updated the child's parent by this point.
    if (child == m_root) {
        Q_ASSERT(oldParent == nullptr);
        Q_ASSERT_X(false,
                   "QObjectTreeModel::handleChildRemovedEvent",
                   "It should not be possible to remove the root node");
        return;
    }

    auto oldSiblingIt = m_parentChildMap.find(oldParent);
    Q_ASSERT(oldSiblingIt != m_parentChildMap.end());
    if (oldSiblingIt == m_parentChildMap.end())
        return;
    QObjectList &oldSiblings{oldSiblingIt->second};
    const int oldIndex = static_cast<int>(oldSiblings.indexOf(child));

    // Check if this can be treated as a move operation.
    QObject *newParent{child->parent()};
    if (oldParent != newParent && m_childParentMap.contains(newParent)) {
        // Case 1: the parent has changed and the new parent is known to the model.
        //
        // This can be reached by a QObject::setParent call.
        const QModelIndex newParentIndex{indexOf(newParent)};
        const int newIndex = static_cast<int>(child->parent()->children().indexOf(child));
        auto newSiblingIt = m_parentChildMap.find(newParent);
        Q_ASSERT(newSiblingIt != m_parentChildMap.end());
        if (newSiblingIt == m_parentChildMap.end())
            return;
        QObjectList &newSiblings{newSiblingIt->second};
        Q_ASSERT(newSiblings.size() == newParent->children().size() - 1);

        beginMoveRows(oldParentIndex, oldIndex, oldIndex, newParentIndex, newIndex);

        // Remove the child from the old list.
        bool removed = oldSiblings.removeOne(child);
        Q_ASSERT(removed);

        // Insert into the child list of the new parent.
        newSiblings.insert(newIndex, child);
        m_childParentMap[child] = newParent;
        endMoveRows();
        return;
    } else if (oldParent == newParent) {
        // Case 2: The parent hasn't changed and the child is still found in the
        // parent's children list.
        //
        // This cannot be reached by a QObject::setParent call as setting a QObject
        // to its current parent does nothing. Only QObjectTreeModel::moveRows
        // should ever result in an event of this type.
        const int newIndex = static_cast<int>(child->parent()->children().indexOf(child));
        if (newIndex >= 0) {
            const int destinationRow = newIndex > oldIndex ? newIndex + 1 : newIndex;

            beginMoveRows(oldParentIndex, oldIndex, oldIndex, oldParentIndex, destinationRow);
            oldSiblings.move(oldIndex, newIndex);
            endMoveRows();
            return;
        }
        // Child is no longer in the parent's children list — fall through
        // to the removal path below.
    }

    Q_ASSERT(oldIndex >= 0);
    beginRemoveRows(oldParentIndex, oldIndex, oldIndex);
    oldSiblings.removeAt(oldIndex); // Remove the actual child.

    // Remove all of the child's children recursively.
    removeAndDisconnectSubtree(child);
    endRemoveRows();
}

void QObjectTreeModel::handleDeferredDeleteEvent(QObject *object)
{
    // Check that the object is currently in the model.
    auto it = m_childParentMap.find(object);
    if (it == m_childParentMap.end()) {
        Q_ASSERT(false);
        return;
    }

    // If the root itself is being deleted via deleteLater, reset the model.
    if (object == m_root) {
        handleRootDestroyed();
        return;
    }

    // Get the parent the child was parented to.
    QObject *oldParent{it->second};
    const QModelIndex oldParentIndex{indexOf(oldParent)};

    // Check that Qt hasn't updated the child's parent by this point.
    Q_ASSERT(oldParent == object->parent());

    // Get the index that the child currently occupies
    auto siblingIt = m_parentChildMap.find(oldParent);
    Q_ASSERT(siblingIt != m_parentChildMap.end());
    if (siblingIt == m_parentChildMap.end())
        return;
    QObjectList &siblings{siblingIt->second};
    const int oldChildRow = static_cast<int>(siblings.indexOf(object));
    Q_ASSERT(oldChildRow >= 0);

#ifdef QT_DEBUG
    int rowCount_ = this->rowCount(oldParentIndex);
#endif

    beginRemoveRows(oldParentIndex, oldChildRow, oldChildRow);
    siblings.removeAt(oldChildRow); // Remove the actual child.

    // Remove all of the child's children recursively.
    removeAndDisconnectSubtree(object);
    endRemoveRows();

#ifdef QT_DEBUG
    Q_ASSERT(rowCount_ - 1 == this->rowCount(oldParentIndex));
#endif
}

// ParentChange is sent by QWidget::setParent(QWidget*) to the reparented
// widget *after* setParent_helper has updated the QObject children lists.
// At this point:
//   - object->parent() returns the NEW parent.
//   - QObjectPrivate::children of the old parent no longer contains the
//     object.
//   - QObjectPrivate::children of the new parent already contains the object.
//   - The model's maps may still reference the OLD parent if
//     ChildRemoved/ChildAdded were suppressed (the typical QWidget case).
//
// This handler reconciles the model to match the real QObject tree. It is
// designed to be idempotent: if the reparent was already processed via the
// ChildRemoved/ChildAdded path, the recorded parent will already match and
// the handler returns immediately.
void QObjectTreeModel::handleParentChangeEvent(QObject *object)
{
    Q_ASSERT(object);

    QObject *newParent = object->parent();
    auto it = m_childParentMap.find(object);

    if (it == m_childParentMap.end()) {
        // The object is not tracked. If its new parent IS tracked, add the
        // object (and its subtree) to the model. This catches the case where
        // an untracked QWidget is grafted into a tracked tree via
        // QWidget::setParent.
        if (newParent && m_childParentMap.contains(newParent)) {
            if (!IsValid(object))
                return;
            handleChildAddedEvent(object);
        }
        return;
    }

    QObject *recordedParent = it->second;

    // If the model already has the correct parent, there is nothing to do.
    // The reparent was already handled via ChildRemoved/ChildAdded.
    if (recordedParent == newParent)
        return;

    // The root is never reparented through this path.
    if (object == m_root)
        return;

    // --- The object is tracked and the parent has changed but the model ---
    // --- was NOT updated. Reconcile.                                     ---

    const QModelIndex oldParentIndex = indexOf(recordedParent);

    auto oldSiblingIt = m_parentChildMap.find(recordedParent);
    Q_ASSERT(oldSiblingIt != m_parentChildMap.end());
    if (oldSiblingIt == m_parentChildMap.end())
        return;
    QObjectList &oldSiblings = oldSiblingIt->second;
    const int oldRow = static_cast<int>(oldSiblings.indexOf(object));
    Q_ASSERT(oldRow >= 0);
    if (oldRow < 0)
        return;

    if (newParent && m_childParentMap.contains(newParent)) {
        // New parent is tracked — emit a move.
        const QModelIndex newParentIndex = indexOf(newParent);
        const int newRow = static_cast<int>(newParent->children().indexOf(object));
        Q_ASSERT(newRow >= 0);

        auto newSiblingIt = m_parentChildMap.find(newParent);
        Q_ASSERT(newSiblingIt != m_parentChildMap.end());
        if (newSiblingIt == m_parentChildMap.end())
            return;
        QObjectList &newSiblings = newSiblingIt->second;

        beginMoveRows(oldParentIndex, oldRow, oldRow, newParentIndex, newRow);
        oldSiblings.removeAt(oldRow);
        newSiblings.insert(newRow, object);
        m_childParentMap[object] = newParent;
        endMoveRows();
    } else {
        // New parent is not tracked or is nullptr — remove the object
        // and its entire subtree from the model.
        beginRemoveRows(oldParentIndex, oldRow, oldRow);
        oldSiblings.removeAt(oldRow);
        removeAndDisconnectSubtree(object);
        endRemoveRows();
    }
}

void QObjectTreeModel::handleObjectDestroyed(QObject *object)
{
    // The QObject::destroyed signal is emitted at the very start of ~QObject,
    // *before* deleteChildren() and setParent_helper(nullptr) run. At this
    // point the object and all of its descendants are still fully intact.
    //
    // We must remove the entire subtree from the model NOW, because once
    // ~QObject proceeds past this signal:
    //
    //   1. It clears the object's event filters and signal connections.
    //   2. It calls deleteChildren(), which destroys each child recursively.
    //   3. It calls setParent_helper(nullptr), which sends a ChildRemoved
    //      event to the parent.
    //
    // If we deferred removal to the ChildRemoved event in step 3, the model
    // would call removeAndDisconnectSubtree on the object, which iterates the
    // model's map of descendants and calls disconnectObject on each one. But
    // by step 3 those descendants have already been freed in step 2, causing a
    // use-after-free crash.
    //
    // By handling removal here, all descendants are disconnected while still
    // alive. The subsequent ChildRemoved event in step 3 finds the object
    // already gone from m_childParentMap and returns early (a no-op).
    //
    // For the deleteLater path the object will have already been removed by
    // handleDeferredDeleteEvent before ~QObject runs, so the early-return
    // below is hit.

    auto it = m_childParentMap.find(object);
    if (it == m_childParentMap.end())
        return;

    // If the root itself is being destroyed, reset the entire model rather
    // than leaving it in a broken state with a dangling m_root pointer and
    // an empty m_parentChildMap[nullptr] list.
    if (object == m_root) {
        handleRootDestroyed();
        return;
    }

    QObject *oldParent{it->second};
    const QModelIndex oldParentIndex{indexOf(oldParent)};

    auto siblingIt = m_parentChildMap.find(oldParent);
    Q_ASSERT(siblingIt != m_parentChildMap.end());
    if (siblingIt == m_parentChildMap.end())
        return;
    QObjectList &siblings{siblingIt->second};
    const int oldChildRow = static_cast<int>(siblings.indexOf(object));
    Q_ASSERT(oldChildRow >= 0);

    beginRemoveRows(oldParentIndex, oldChildRow, oldChildRow);
    siblings.removeAt(oldChildRow);
    removeAndDisconnectSubtree(object);
    endRemoveRows();
}

void QObjectTreeModel::handleObjectNameChanged(QObject *object)
{
    Q_ASSERT(object);
    if (!object)
        return;

    QModelIndex objectIndex{indexOf(object)};
    Q_ASSERT(objectIndex.isValid());
    if (objectIndex.isValid()) {
        dataChanged(objectIndex,
                    objectIndex,
                    {Qt::DisplayRole, static_cast<int>(Roles::ObjectName)});
    }
}

void QObjectTreeModel::handleRootDestroyed()
{
    beginResetModel();

    // Disconnect event filters and signal connections from every tracked
    // object.  The root itself is mid-destruction but still valid at this
    // point — QObject::destroyed is emitted before ~QObject tears down
    // children or clears connections.
    for (const auto &[tracked, parent] : m_childParentMap) {
        disconnectObject(tracked);
    }
    m_childParentMap.clear();
    m_parentChildMap.clear();

    // Replace with a new internal root, consistent with setRoot(nullptr).
    m_root = new QObject(this);
    m_root->setObjectName(u"Root"_s);
    populateFromObjectRecursive(m_root);

    endResetModel();

    Q_EMIT rootChanged();
}

void QObjectTreeModel::appendChildObjects(const QObjectList &children)
{
    if (children.empty())
        return;

    QObject *parent{children.first()->parent()};
    Q_ASSERT(parent);

    // check that we are aware of the parent.
    const QModelIndex parentIndex = indexOf(parent);
    Q_ASSERT(parentIndex.isValid());

    appendChildObjects(children, parentIndex);
}

void QObjectTreeModel::appendChildObjects(const QObjectList &children,
                                          const QModelIndex &parentIndex)
{
    if (children.empty())
        return;

    QObject *parent{children.first()->parent()};
    Q_ASSERT(parent);

    // Verify all children have the same parent and are not already in the model.
    for (const auto &child : children) {
        if (!child) {
            Q_ASSERT_X(false, Q_FUNC_INFO, "list contains nullptr child");
            qWarning() << "Cannot append child objects, list contains nullptr child.";
            return;
        }
        if (child->parent() != parent) {
            Q_ASSERT_X(false, Q_FUNC_INFO, "parent inconsistent");
            qWarning() << "Cannot append child objects, parent inconsistent.";
            return;
        }
        if (indexOf(child).isValid()) {
            Q_ASSERT_X(false, Q_FUNC_INFO, "child already in model");
            qWarning() << "Cannot append child objects, child already in model.";
            return;
        }
    }

    QObjectList &existingChildren = m_parentChildMap[parent];

    // get the index to insert the new child into.
    const int firstInsertIndex = static_cast<int>(existingChildren.count());

    beginInsertRows(parentIndex,
                    firstInsertIndex,
                    firstInsertIndex + static_cast<int>(children.count()) - 1);
    for (const auto &child : children) {
        connectObject(child);
        existingChildren.append(child);
        m_childParentMap[child] = parent;

        // Insert the child as a key into the |m_parentChildMap| with an empty child
        // list. We don't add the child's children yet as these will be added by the
        // separate recursive call to |appendChildObjects| below.
        m_parentChildMap[child] = QObjectList();
    }
    endInsertRows();

    // Finally add all of the children's children to the model recursively.
    // Pass the pre-computed child index down to avoid redundant indexOf lookups.
    for (int i = 0; i < children.count(); ++i) {
        QObject *child = children.at(i);
        const QModelIndex childIndex = createIndex(firstInsertIndex + i, 0, child);
        appendChildObjects(child->children(), childIndex);
    }
}

void QObjectTreeModel::insertChildObjects(const QObjectList &children, qsizetype insertIndex)
{
    if (children.empty())
        return;

    QObject *parent{children.first()->parent()};

    // check that we are aware of the parent.
    const QModelIndex parentIndex = indexOf(parent);
    Q_ASSERT(parentIndex.isValid());

    insertChildObjects(children, insertIndex, parentIndex);
}

void QObjectTreeModel::insertChildObjects(const QObjectList &children,
                                          qsizetype insertIndex,
                                          const QModelIndex &parentIndex)
{
    if (children.empty())
        return;

    QObject *parent{children.first()->parent()};

    // Verify all children have the same parent and are not already in the model.
    for (const auto &child : children) {
        Q_ASSERT(child);
        Q_ASSERT(child->parent() == parent);
        Q_ASSERT(!indexOf(child).isValid());
    }

    QObjectList &existingChildren = m_parentChildMap[parent];

    beginInsertRows(parentIndex,
                    static_cast<int>(insertIndex),
                    static_cast<int>(insertIndex + children.count() - 1));
    for (const auto &child : children | std::views::reverse) {
        connectObject(child);
        existingChildren.insert(insertIndex, child);
        m_childParentMap[child] = parent;

        // Insert the child as a key into the |m_parentChildMap| with an empty child
        // list. We don't add the child's children yet as these will be added by the
        // separate recursive call to |appendChildObjects| below.
        m_parentChildMap[child] = QObjectList();
    }
    endInsertRows();

    // Finally add all of the children's children to the model recursively.
    // Pass the pre-computed child index down to avoid redundant indexOf lookups.
    for (int i = 0; i < children.count(); ++i) {
        QObject *child = children.at(i);
        const QModelIndex childIndex = createIndex(static_cast<int>(insertIndex) + i, 0, child);
        appendChildObjects(child->children(), childIndex);
    }
}

void QObjectTreeModel::removeAndDisconnectSubtree(QObject *object)
{
    disconnectObject(object);

    if (auto it = m_parentChildMap.find(object); it != m_parentChildMap.end()) {
        std::ranges::for_each(it->second,
                              [&](QObject *child) { removeAndDisconnectSubtree(child); });
    }

    m_childParentMap.erase(object);
    m_parentChildMap.erase(object);
}

void QObjectTreeModel::dumpObjectInfo(QObject *object)
{
    if (object) {
        object->dumpObjectInfo();
    }
}

void QObjectTreeModel::dumpObjectTree(QObject *object)
{
    if (object) {
        object->dumpObjectTree();
    }
}

#include "moc_qobjecttreemodel.cpp"