qobjecttreemodel.h

#pragma once

#include <memory>
#include <unordered_map>

#include <QtCore/QAbstractItemModel>

#ifdef QT_QML_LIB
#include <QtQml/qqmlregistration.h>
#endif

class QObjectTreeModelTest;

/**
 * @class QObjectTreeModel
 * @brief A QAbstractItemModel that reactively mirrors a QObject parent–child
 *        hierarchy as a tree model for Qt Views and QML.
 *
 * The QObjectTreeModel monitors a QObject parent/child tree reactively via
 * event filters on every object in the tree. This way it can be attached to
 * existing QObjects to expose their child hierarchy for view for debugging.
 * Reparenting or deleting a QObject automatically causes the model to update so
 * no manual insert/remove calls required.
 *
 * @par Object deletion
 * Both @c deleteLater and raw @c delete are supported for tracked objects.
 * The @c DeferredDelete event can remove the object cleanly before destruction
 * and raw @c delete is handled via the @c QObject::destroyed signal.
 *
 * @par Thread affinity
 * The root QObject must have the same thread affinity as the model. Because
 * Qt enforces that all children live in the same thread as their parent
 * (checked at construction and in @c setParent), this single check is
 * sufficient to guarantee the entire tracked subtree is on the model's thread.
 * If an external root object is moved off the models thread then the model will
 * detect the QEvent::ThreadChange event and unset the root object.
 */
class QObjectTreeModel : public QAbstractItemModel
{
    Q_OBJECT
#ifdef QT_QML_LIB
    QML_ELEMENT
#endif
    Q_CLASSINFO("RegisterEnumClassesUnscoped", "false")
    Q_DISABLE_COPY_MOVE(QObjectTreeModel);

    Q_PROPERTY(QObject *root READ root WRITE setRoot NOTIFY rootChanged FINAL)

public:
    /**
     * @brief Construct a new QObjectTreeModel with an internally managed root,
     * optionally parented to @p parent.
     *
     * An internal root QObject is created and owned by the model. Children can
     * be added by reparenting QObjects to the internal root (see root()).
     *
     * To create a model with an external root, use CreateWithRoot().
     **/
    explicit QObjectTreeModel(QObject *parent = nullptr);

    /**
     * @brief Factory method that creates a QObjectTreeModel whose root is the
     * externally-owned @p root, optionally parented to @p parent.
     *
     * The model does not take ownership of @p root, it is the caller's
     * responsibility to ensure @p root outlives the model. If @p root is
     * nullptr an internal root is created (equivalent to the constructor).
     *
     * @pre @p root must have the same thread affinity as @p parent (or the
     * calling thread if @p parent is nullptr).
     **/
    [[nodiscard]] static std::unique_ptr<QObjectTreeModel> CreateWithRoot(QObject *root,
                                                                          QObject *parent = nullptr);

    ~QObjectTreeModel() override;

    enum class Roles : int {
        ObjectName = Qt::UserRole,
        MetaTypeName,
    };
    Q_ENUM(Roles)

    /**
     * @brief Returns data for the given @p index and @p role.
     *
     * Supported roles:
     * - Qt::DisplayRole — the objectName of the QObject at the index.
     * - Roles::ObjectName — the objectName of the QObject at the index.
     * - Roles::MetaTypeName — the QMetaObject::className of the QObject at
     *   the index (e.g. "QObject", "QWidget", "MyCustomClass").
     *
     * Returns an invalid QVariant if the index is out of range.
     **/
    QVariant data(const QModelIndex &index, int role) const override;

    /**
     * @brief Returns the number of children under @p parent.
     *
     * If @p parent is an invalid index the children of the root object are
     * counted. Returns 0 if the parent index refers to an object not tracked
     * by the model.
     **/
    int rowCount(const QModelIndex &parent = QModelIndex()) const override;

    /**
     * @brief Returns the number of columns for the given @p parent. Always
     * returns 1.
     **/
    int columnCount(const QModelIndex &parent = QModelIndex()) const override;

    /**
     * @brief Returns whether the item at @p parent has any children.
     **/
    bool hasChildren(const QModelIndex &parent = QModelIndex()) const override;

    /**
     * @brief Returns the parent index of the given @p child index.
     *
     * If @p child is the root or is invalid, an invalid QModelIndex is
     * returned.
     **/
    QModelIndex parent(const QModelIndex &child) const override;

    /**
     * @brief Returns the model index for the item at (@p row, @p column) under
     * @p parent.
     *
     * Returns an invalid index if the row or column is out of range, or if
     * the parent is not tracked by the model.
     **/
    QModelIndex index(int row, int column, const QModelIndex &parent = QModelIndex()) const override;

    /**
     * @brief Returns the sibling at @p row and @p column for the item at @p idx.
     *
     * Overridden for performance: the default implementation calls
     * @c index(row, column, parent(idx)), which requires redundant map lookups
     * and a linear scan. This implementation resolves the sibling in two hash
     * lookups with no linear search.
     **/
    QModelIndex sibling(int row, int column, const QModelIndex &idx) const override;

    /**
     * @brief Returns a map of all data roles and their values for the item at
     * @p index.
     *
     * This is a convenience override that populates the map with every role
     * returned by roleNames().
     **/
    QMap<int, QVariant> itemData(const QModelIndex &index) const override;

    /**
     * @brief Returns the model's role names.
     *
     * Extends the default role names with Roles::ObjectName mapped to
     * @c "objectName" and Roles::MetaTypeName mapped to @c "metaTypeName".
     **/
    QHash<int, QByteArray> roleNames() const override;

    /**
     * @brief Removes @p count rows starting at @p row under the given @p parent
     * from the model.
     *
     * @warning This is a **destructive** operation. Every QObject removed
     * (including the entire subtree rooted at each removed child) is scheduled
     * for deletion via QObject::deleteLater(). If you need to remove objects
     * from the model without destroying them, use takeRows() instead.
     *
     * Returns true on success. Returns false if the parent index is invalid
     * (removing the root is not supported), if row or count are negative, or if
     * the range exceeds the number of children.
     *
     * @sa takeRows(), takeAllRows()
     **/
    bool removeRows(int row, int count, const QModelIndex &parent = QModelIndex()) override;

    /**
     * @brief Moves a single row from @p sourceRow under @p sourceParent to
     * @p destinationRow under @p destinationParent.
     *
     * Only a @p count of 1 is supported; any other value will emit a warning
     * and return false.
     *
     * The move is performed by reparenting the underlying QObject. Returns
     * true on success. Returns false if either parent index is invalid, if
     * the source or destination row is out of bounds, if @p count is not 1,
     * or if the move would be a no-op.
     **/
    bool moveRows(const QModelIndex &sourceParent,
                  int sourceRow,
                  int count,
                  const QModelIndex &destinationParent,
                  int destinationRow) override;

    /**
     * @brief Removes @p count rows starting at @p row under @p parent and
     * returns the taken QObjects.
     *
     * The taken objects are unparented (parent set to nullptr) and removed
     * from the model. Ownership is transferred to the caller. Returns an
     * empty QObjectList if the arguments are out of range or the parent index
     * is invalid.
     *
     * Unlike removeRows(), this does @b not destroy the removed objects.
     *
     * @sa removeRows(), takeAllRows()
     **/
    [[nodiscard]] QObjectList takeRows(int row,
                                       int count,
                                       const QModelIndex &parent = QModelIndex());

    /**
     * @brief Removes all child rows under @p parent and returns the taken
     * QObjects.
     *
     * Equivalent to calling takeRows(0, rowCount(parent), parent). Ownership
     * of the returned objects is transferred to the caller.
     **/
    [[nodiscard]] QObjectList takeAllRows(const QModelIndex &parent = QModelIndex());

    /**
     * @brief Returns the model index corresponding to the given @p object.
     *
     * If @p object is the root, or is not tracked by the model, an invalid
     * QModelIndex is returned.
     **/
    Q_INVOKABLE QModelIndex indexOf(QObject *object) const;

    /**
     * @brief Returns the current root QObject of the model.
     **/
    QObject *root() const;

    /**
     * @brief Sets the root QObject of the model. If @p root is nullptr, an
     * internal root QObject will be created and managed by the model (parented
     * to the model itself).
     *
     * If the previous root was internally created (i.e. from a prior call with
     * nullptr), it will be scheduled for deletion via deleteLater(). Any
     * QObjects that have been inserted into the model at this point will be
     * destroyed with the internal parent.
     *
     * The model does not take ownership of an externally provided root. It is
     * the caller's responsibility to ensure the root QObject outlives the
     * model.
     *
     * @pre If @p root is non-null it must have the same thread affinity as the
     * model.
     *
     * Setting the root to its current value is a no-op.
     **/
    void setRoot(QObject *root);

    Q_SIGNAL void rootChanged();

    /**
     * @brief Returns the current QObject associated with the provided @p index.
     **/
    Q_INVOKABLE QObject *objectFromIndex(const QModelIndex &index) const;

    /**
     * @brief Prints diagnostic information about @p object's signal
     * connections and event filters to the debug output.
     *
     * Convenience wrapper that exposes QObject::dumpObjectInfo to QML.
     **/
    Q_INVOKABLE static void dumpObjectInfo(QObject *object);

    /**
     * @brief Recursively prints @p object and its children as an indented tree
     * to the debug output.
     *
     * Convenience wrapper that exposes QObject::dumpObjectTree to QML.
     **/
    Q_INVOKABLE static void dumpObjectTree(QObject *object);

    /**
     * @brief Gets the parent of a QObject. Exposed to allow QML to access the
     * QObject::parent property of a QObject.
     **/
    Q_INVOKABLE static QObject *GetParent(QObject *object);

    /**
     * @brief Returns true if @p ancestor is an ancestor of @p descendant
     * (or is @p descendant itself).
     *
     * Walks up the QObject::parent() chain from @p descendant. Returns false
     * if either argument is nullptr.
     **/
    Q_INVOKABLE static bool IsAncestorOf(QObject *ancestor, QObject *descendant);

    /**
     * @brief Sets the parent of a QObject to a new parent at a specific index.
     *
     * Use this method when precise control over the child insertion index is
     * required or when you need the model to emit @c moveRows signals for both
     * same-parent reorders and cross-parent moves.
     *
     * For QWidget objects, the model also detects reparents performed via the
     * standard @c QWidget::setParent(QWidget*) API (through @c ParentChange
     * event handling), so using @c SetParent is not strictly required for
     * widgets. However, @c QWidget::setParent does not allow specifying the
     * child index and always appends.
     *
     * Both QObject and QWidget children are supported. For QWidgets the method
     * delegates to QWidget::setParent internally to ensure proper window-system
     * setup, visibility propagation, and style inheritance. A QWidget can only
     * be parented to another QWidget; passing a non-widget parent for a QWidget
     * child is a programming error (asserts in debug, returns in release).
     * A plain QObject can be a child of either a QObject or a QWidget.
     *
     * @param object The object to reparent.
     * @param parent The new parent (may be nullptr to unparent). Must be a
     *               QWidget if @p object is a QWidget.
     * @param index The position among the new parent's children. Negative values
     *              index from the end (-1 = last, -2 = second-to-last, etc.).
     *              Values beyond the end are clamped.
     * @return true if the reparent succeeded, false if the operation was
     *         rejected (e.g. circular hierarchy, thread mismatch, QWidget
     *         parented to a non-QWidget).
     */
    Q_INVOKABLE static bool SetParent(QObject *object, QObject *parent, int index);

    /**
     * @brief Same as above but will append rather than insert at a given index.
     */
    Q_INVOKABLE static bool SetParent(QObject *object, QObject *parent);

protected:
    /**
     * QAbstractItemModel::{insertRows/insertColumns} should never be called.
     * Item insertion is controlled by reparenting the QObjects in the model
     * either by |QObject::setParent| or |QObject::deleteLater|.
     * |QObjectTreeModel::SetParent| can also be used for more control over the
     * child order.
     **/
    bool insertRows(int, int, const QModelIndex &index = QModelIndex()) override;
    bool insertColumns(int, int, const QModelIndex &index = QModelIndex()) override;

    bool eventFilter(QObject *object, QEvent *event) override;

private:
    friend class ::QObjectTreeModelTest;

    // Used to setup the model during construction.
    void populateFromObjectRecursive(QObject *object);

    // Called after a QObject is added to the model to track state changed on the QObject.
    void connectObject(QObject *object);

    // Called when a QObject is removed from the model but not deleted.
    void disconnectObject(QObject *object);

    // Handles ChildAdded events for QObjects in the model.
    void handleChildAddedEvent(QObject *child);

    // Handles ChildRemoved events for QObjects in the model. Detects
    // reparenting (move) vs true removal. For raw-deleted objects this is a
    // no-op because handleObjectDestroyed already removed the subtree before
    // ~QObject sends the ChildRemoved event. |eventParent| is the QObject that
    // received the ChildRemoved event (i.e. the parent that lost the child).
    void handleChildRemovedEvent(QObject *child, QObject *eventParent);

    // Handles DeferredDelete events for QObjects in the model. This will remove
    // the object from the model before it is deleted.
    void handleDeferredDeleteEvent(QObject *object);

    // Handles ParentChange events for QWidgets in the model. ParentChange is
    // sent by QWidget::setParent after the reparent completes. This provides a
    // fallback for detecting reparents when QWidget::setParent() suppresses the
    // ChildAdded/ChildRemoved events that the model normally relies on. The
    // handler is idempotent: if the reparent was already processed via
    // ChildRemoved/ChildAdded, this is a no-op.
    void handleParentChangeEvent(QObject *object);

    // Slots that model QObjects are connected up to by connectObject.
    // Handles QObject::destroyed for raw delete. The destroyed signal fires at
    // the start of ~QObject while all descendants are still alive, allowing
    // safe removal of the entire subtree. For the deleteLater path the object
    // is already removed by handleDeferredDeleteEvent, so this is a no-op. See
    // the implementation comment for the full destruction sequence.
    Q_SLOT void handleObjectDestroyed(QObject *object);
    void handleObjectNameChanged(QObject *object);

    // Handles the special case where the root QObject is destroyed while the
    // model is still alive. Resets the model and creates a new internal root.
    void handleRootDestroyed();

    /**
     * @brief Appends the provided list of children into the model. All children
     * must have the same parent. The parent must already be known to the model.
     **/
    void appendChildObjects(const QObjectList &children);

    /**
     * @brief Inserts the provided list of children into the model. All children
     * must have the same parent. The parent must already be known to the model.
     * "insertIndex" specifies the index the first child in the list should be
     * inserted into, if the list contains more than one child then subsequent
     * children will be inserted after the first child maintaining the provided
     * list order.
     **/
    void insertChildObjects(const QObjectList &children, qsizetype insertIndex);

    // Overloads that accept a pre-computed parent index to avoid redundant
    // indexOf lookups during recursive tree insertion.
    void appendChildObjects(const QObjectList &children, const QModelIndex &parentIndex);
    void insertChildObjects(const QObjectList &children,
                            qsizetype insertIndex,
                            const QModelIndex &parentIndex);

    /**
     * @brief Removes the provided object and all of its children recursively
     * from the internal maps. |disconnectObject| will also be run on every
     * object in the tree.
     **/
    void removeAndDisconnectSubtree(QObject *object);

    QObject *m_root = nullptr;
    std::unordered_map<QObject *, QObject *> m_childParentMap;
    std::unordered_map<QObject *, QObjectList> m_parentChildMap;
};