/*  This file is part of the KDE project.

Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

This library is free software: you can redistribute it and/or modify

it under the terms of the GNU Lesser General Public License as published by

the Free Software Foundation, either version 2.1 or 3 of the License.

This library is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License

along with this library.  If not, see <http://www.gnu.org/licenses/>.

*/

#ifndef OBJECTDUMP_H

#define OBJECTDUMP_H

#include "objectdump_global.h"

#include <QObject>

#include <QList>

#include <QByteArray>

#include <QScopedPointer>

QT_BEGIN_NAMESPACE

namespace ObjectDump

{

/**

 * Abstract base for annotator classes invoked by QVisitor.

 */

class OBJECTDUMP_EXPORT QAnnotator : public QObject

{

    Q_OBJECT

public:

    virtual ~QAnnotator();

    virtual QList<QByteArray> annotation(const QObject& object) = 0;

};

/**

 * Annotator which replicates QObject::dumpObjectTree functionality.

 */

class OBJECTDUMP_EXPORT QAnnotatorBasic : public QAnnotator

{

    Q_OBJECT

public:

    QList<QByteArray> annotation(const QObject& object);

};

/**

 * Annotator which returns widget information.

 */

class OBJECTDUMP_EXPORT QAnnotatorWidget : public QAnnotator

{

    Q_OBJECT

public:

    QList<QByteArray> annotation(const QObject& object);

};

class QDumperPrivate;

/**

 * Class used to dump information about individual QObjects.

 */

class OBJECTDUMP_EXPORT QDumper : public QObject

{

    Q_OBJECT

    Q_DECLARE_PRIVATE(QDumper)

public:

    QDumper();

    ~QDumper();

    /**

     * Specify a prefix, to be printed on each line of output.

     */

    void setPrefix(const QString& prefix);

    /**

     * Takes ownership of annotator.

     */

    void addAnnotator(QAnnotator* annotator);

    /**

     * Invoke each annotator on the object and write to debug output.

     */

    void dumpObject(const QObject& object);

private:

    QScopedPointer<QDumperPrivate> d_ptr;

};

class QVisitorPrivate;

/**

 * Visitor class which dumps information about nodes in the object tree.

 */

class OBJECTDUMP_EXPORT QVisitor : public QObject

{

    Q_OBJECT

    Q_DECLARE_PRIVATE(QVisitor)

public:

    QVisitor();

    ~QVisitor();

    /**

     * Specify a prefix, to be printed on each line of output.

     */

    void setPrefix(const QString& prefix);

    /**

     * Set number of spaces by which each level of the tree is indented.

     */

    void setIndent(unsigned indent);

    /**

     * Called by the visitor algorithm before starting the visit.

     */

    void visitPrepare();

    /**

     * Called by the visitor algorithm as each node is visited.

     */

    void visitNode(const QObject& object);

    /**

     * Called by the visitor algorithm when the visit is complete.

     */

    void visitComplete();

    /**

     * Takes ownership of annotator.

     */

    void addAnnotator(QAnnotator* annotator);

private:

    QScopedPointer<QVisitorPrivate> d_ptr;

};

//-----------------------------------------------------------------------------

// Utility functions

//-----------------------------------------------------------------------------

void OBJECTDUMP_EXPORT addDefaultAnnotators(QDumper& dumper);

void OBJECTDUMP_EXPORT addDefaultAnnotators(QVisitor& visitor);

void OBJECTDUMP_EXPORT dumpTreeFromRoot(const QObject& root, QVisitor& visitor);

void OBJECTDUMP_EXPORT dumpTreeFromLeaf(const QObject& leaf, QVisitor& visitor);

void OBJECTDUMP_EXPORT dumpAncestors(const QObject& leaf, QVisitor& visitor);

} // namespace ObjectDump

QT_END_NAMESPACE

#endif