Examples

The demo program shipped with the QxRunner library can be used as the starting point for developping a QxRunner based program. It subclasses RunnerModel and RunnerItem and uses a Runner instance in the main program to launch the GUI. The model constructs a tree structure of runner items which randomly generate a result of type QxRunner::RunnerResult. An item also reports the location of where in the code the result was created and supplies a related result message.

See also:

For a deeper insight into the details of the model/view framework and how to create a basic model to use with Qt's standard view classes see the Simple Tree Model Example provided with the Qt installation. And, yes, much of this example documentation uses slightly modified text from that Qt example.

The Demo Model

Demo Model Header File

The constructor takes an argument containing the data that the model will share with views. The name() method returns the model name used by QxRunner for display in the about box and as the identifier for the settings file. The model's internal data structure is populated with DemoItem instances by the setupModelData() helper method. The model isn't designed to add data to the model after it is constructed and set up.

#ifndef DEMOMODEL_H
#define DEMOMODEL_H

#include <qxrunner/runnermodel.h>
#include <QStringList>

using namespace QxRunner;

class DemoModel : public RunnerModel
{
    Q_OBJECT

public:  // Operations

    DemoModel(const QStringList& data, QObject* parent = 0);

    ~DemoModel();

    QString name() const;
    
private:  // Operations

    void setupModelData(const QStringList& itemList, RunnerItem* parent);
};

#endif // DEMOMODEL_H

Demo Model Implementation File

The constructor creates the root item for the model. This item only contains horizontal header data. It is also used to reference the internal data structure that contains the model data, and it is used to represent an imaginary parent of top-level items in the model. The model's internal data structure is populated with items by the setupModelData() function. The destructor does nothing, it relies on the parent RunnerModel destructor who deletes the root item and all of its descendants when the model is destroyed.

The setupModelData() method sets up the initial data in the model. It iterates over a list of 'keywords' which define the position of an item in the tree strucuture and the related item name. Of course this is a very simple model and is only intended for demonstrational purposes.

The keyword meanings are:

• L0 defines a top level item.
• L1 defines an item which is a child of a L0 item and itself has child items, thus starts a new branch.
• L2 defines an item which is a child of a L1 item and itself has child items, thus starts a new branch.
• L3 defines an item which is a child of a L2 item and itself has child items, thus starts a new branch.
• CH defines a child item which has no child items of itws own (a leaf). It is appended as a child to the last parent item encountered in the list.

#include "demomodel.h"
#include "demoitem.h"

DemoModel::DemoModel(const QStringList& data, QObject* parent)
         : RunnerModel(parent)
{
    // Data for column headers is stored in the root item.
    QList<QVariant> rootData;
    rootData << tr("Item Name") << tr("Result") << tr("Message")
             << tr("File Name") << tr("Line Number");

    setRootItem(new DemoItem(rootData));

    // Fill the model items.
    setupModelData(data, rootItem());
}

DemoModel::~DemoModel()
{
    // Remove destructor if it doesn't class specific cleanup.
}

QString DemoModel::name() const
{
    return tr("Demo");
}

void DemoModel::setupModelData(const QStringList& itemList, RunnerItem* parent)
{
    QList<DemoItem*> parents;

    DemoItem* item;
    QString token;
    QList<QVariant> columnData;

    QList<QString>::const_iterator it = itemList.constBegin();

    for (; it != itemList.constEnd(); ++it)
    {
        token = *it;

        // First column has the item name, remaining columns are empty.
        it++;
        columnData.clear();
        columnData << *it;

        // Note: Appending empty columns is not needed since the runner
        // item constructor takes care of it.
        // -> columnData << "" << "" << "" << "";       

        if (token == "L0")
        {
            item = new DemoItem(columnData, parent);
            parent->appendChild(item);

            parents.clear();
            parents << item;
        }
        else if (token == "CH")
        {
            parents.last()->appendChild(new DemoItem(columnData, parents.last()));
        }
        else if (token == "L1")
        {
            item = parents.first();
            parents.clear();
            parents << item;

            item = new DemoItem(columnData, parents.last());
            parents.last()->appendChild(item);

            parents << item;
        }
        else
        {
            item = new DemoItem(columnData, parents.last());
            parents.last()->appendChild(item);

            parents << item;
        }
    }
}

The Demo Item

Demo Item Header File

The constructor is used to record the item's parent and the data associated with each column. The abstract run() method from the parent RunnerItem class must be reimplemented and contains the custom code that gets executed when the items are run by QxRunner.

#ifndef DEMOITEM_H
#define DEMOITEM_H

#include <qxrunner/runneritem.h>

using namespace QxRunner;

class DemoItem : public RunnerItem
{
public: // Operations

    DemoItem(const QList<QVariant>& data, RunnerItem* parent = 0);
    
    ~DemoItem();

    int run();
};

#endif // DEMOITEM_H

Demo Item Implementation File

The constructor simply calls the parent RunnerItem constructor. The destructor does nothing, it relies on the parent RunnerItem destructor who ensures that all child items get deleted.

The run() method first checks whether it is a parent item or not (see The Runner Model). Only leafs have custom logic for execution. If it is a child the method randomly creates a result type and fills related data into the item columns. A special case is the unhandled exception which gets caught by the model. The commented out code at the beginning was used during development to slow down item execution.

#include "demoitem.h"

#include <QCoreApplication>
#include <stdlib.h>

DemoItem::DemoItem(const QList<QVariant>& data, RunnerItem* parent)
        : RunnerItem(data, parent)
{

}

DemoItem::~DemoItem()
{
    // Remove destructor if it doesn't class specific cleanup.
}

int DemoItem::run()
{
    if (child(0))
    {
        return QxRunner::NoResult;  // Have nothing to do as a parent
    }

    //Mimick some processing.
    //for (int i = 0; i < 30000; i++)
    //{
    //  QCoreApplication::processEvents();
    //}

    QString msg;
    QString line;

    // Randomly generated result.
    switch (rand() % 6)
    {
        case 0:
            msg = "Run completed successfully.";
            line.setNum(__LINE__);
            setResult(QxRunner::RunSuccess);
            break;

        case 1:
            msg = "Run completed with an information.";
            line.setNum(__LINE__);
            setResult(QxRunner::RunInfo);
            break;

        case 2:
            msg = "Run completed with a warning.";
            line.setNum(__LINE__);
            setResult(QxRunner::RunWarning);
            break;

        case 3:
            msg = "Run completed with an error.";
            line.setNum(__LINE__);
            setResult(QxRunner::RunError);
            break;

        case 4:
            msg = "Run completed with a fatal error.";
            line.setNum(__LINE__);
            setResult(QxRunner::RunFatal);
            break;

        case 5:
            // This gets caught by the caller as a fallback, but actually
            // all exceptions should get handled in the run() method.
            throw 0;
            break;
    }

    // Fill item with resulting data.
    setData(2, msg);
    setData(3, __FILE__);
    setData(4, line);

    return result();
}

The Demo Main Program

The main program is straightforward:

#include "demomodel.h"

#include <QApplication>
#include <qxrunner/runner.h>

QStringList demoItems();            // Helper function

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    DemoModel model(demoItems());   // Setup the data

    QxRunner::Runner runner(&model);
    runner.run();

    return 0;
}

// Creates a list of items for the model.
QStringList demoItems()
{
    QStringList itemList;

    itemList << "L0" << "Group 1";
    itemList << "CH" << "Demo item 1a";
    itemList << "CH" << "Demo item 1b";
    itemList << "CH" << "Demo item 1c";
    itemList << "CH" << "Demo item 1d";

    itemList << "L0" << "Group 2";
    itemList << "CH" << "Demo item 2a";
    itemList << "CH" << "Demo item 2b";
    itemList << "CH" << "Demo item 2c";
    itemList << "CH" << "Demo item 2d";

    itemList << "L0" << "Group 3";
    itemList << "CH" << "Demo item 3a";
    itemList << "CH" << "Demo item 3b";
    itemList << "CH" << "Demo item 3c";
    itemList << "CH" << "Demo item 3d";

    itemList << "L1" << "Group 3.1";
    itemList << "CH" << "Demo item 3.1a";
    itemList << "CH" << "Demo item 3.1b";
    itemList << "CH" << "Demo item 3.1c";
    itemList << "CH" << "Demo item 3.1d";

    itemList << "L2" << "Group 3.1.1";
    itemList << "CH" << "Demo item 3.1.1a";
    itemList << "CH" << "Demo item 3.1.1b";
    itemList << "CH" << "Demo item 3.1.1c";
    itemList << "CH" << "Demo item 3.1.1d";

    itemList << "L2" << "Group 3.2";
    itemList << "CH" << "Demo item 3.2a";
    itemList << "CH" << "Demo item 3.2b";
    itemList << "CH" << "Demo item 3.2c";
    itemList << "CH" << "Demo item 3.2d";

    itemList << "L3" << "Group 3.2.1";
    itemList << "CH" << "Demo item 3.2.1a";
    itemList << "CH" << "Demo item 3.2.1b";
    itemList << "CH" << "Demo item 3.2.1c";
    itemList << "CH" << "Demo item 3.2.1d";

    itemList << "L0" << "Demo item 4";

    itemList << "L0" << "Group 5";
    itemList << "CH" << "Demo item 5a";
    itemList << "CH" << "Demo item 5b";
    itemList << "CH" << "Demo item 5c";
    itemList << "CH" << "Demo item 5d";

    itemList << "L0" << "Demo item 6";
    itemList << "L0" << "Demo item 7";

    return itemList;
}