Marble/RunnerHOWTO

The basic idea of the Marble Runners is borrowed from KRunner. A user search could represent a bunch of different things: a geographical coordinate, an address, a wikipedia article, directions, etc...

Because each of these searches is different in type as well as speed (e.g. a OSM Namefinder search takes much longer than parsing coordinates) each type of search is done in its own runner which is a seperate thread.

The piece that manages all the runners is the MarbleRunnerManager. It receives search text from the MarbleControlBox (where the lineedit is) and then gives it to all of the runners.

1. User presses return in the line edit
2. The current text is sent to the MarbleRunnerManager
3. The MarbleRunnerManager gives the text to all of the runners
4. The runners emit the runnerStarted() signal. The MarbleRunnerManager uses this to count how many runners are still active.
5. The runners finish by emitting the runnerFinished(QVector<GeoDataPlacemark*>) signal. Note that if the runner fails to produce results for some reason, this signal should be emitted with an empty QVector, as it's needed to keep track of which runners are still working.
6. The MarbleRunnerManager gives results back to the MarbleControlBox.

The main work of the runner is done in the parse(const QString &input) slot; it should emit runnerStarted() at the beginning and runnerFinished() at any exit point.

ExampleRunner.h

1. ifndef EXAMPLERUNNER_H
2. define EXAMPLERUNNER_H

1. include "MarbleAbstractRunner.h"

namespace Marble {

class ExampleRunner : public MarbleAbstractRunner {

   Q_OBJECT

public:

   ExampleRunner(QObject *parent = 0);
   ~ExampleRunner();
   GeoDataFeature::GeoDataVisualCategory category() const;

public slots:

   void parse(const QString &input);

};

}

1. endif

This basically just defines the class; it doesn't do anything else.

ExampleRunner.cpp

1. include "ExampleRunner.h"

1. include "MarbleAbstractRunner.h"
2. include "GeoDataFeature.h"
3. include "GeoDataPlacemark.h"
4. include "GeoDataCoordinates.h"

1. include <QtCore/QDebug>
2. include <QtCore/QString>
3. include <QtCore/QStringList>
4. include <QtCore/QVector>

namespace Marble {

ExampleRunner::ExampleRunner(QObject *parent) : MarbleAbstractRunner(parent) { }

GeoDataFeature::GeoDataVisualCategory ExampleRunner::category() const {

   return GeoDataFeature::Default;

}

ExampleRunner::~ExampleRunner() { }

void ExampleRunner::parse(const QString &input) {

   emit runnerStarted();
   QVector<GeoDataPlacemark*> vector;
   if(input.toLower() == tr("middle of nowhere")) {
       GeoDataPlacemark *placemark = new GeoDataPlacemark();
       placemark->setCoordinate( -90.1833 *DEG2RAD, 51.4666 *DEG2RAD);
       placemark->setName( input );
       placemark->setVisualCategory( category() );
       placemark->setPopularity( 1000000000 );
       placemark->setPopularityIndex( 18 );
       vector.append( placemark );
   }
   emit runnerFinished(vector);

}

}

1. include "ExampleRunner.moc"

ExampleRunner::category() returns the visual category of the results produced by this runner; in this case we use Default because there isn't an existing category for Techbase examples.

runnerStarted() gets emitted at the beginning to notify the runner manager that we've started parsing; then we do a very simple case-insensitive check to see if it matches.

Results are GeoDataPlacemarks, and it's useful to set various parameters for them: set the category to the runner's category, set the name, set the popularity / popularity index (see the documentation for GeoDataPlacemark for details), etc...

Then the pointer to the placemark is put into the results vector and the runner emits runnerFinished(), returning it to the runner manager. If it didn't match, it returns an empty vector.

To add the runner to Marble, you would have to put the source files into the src/lib/runners directory, and add them to CMakeLists.txt, then add a part in src/lib/MarbleRunnerManager.cpp that creates the object and connects it exactly the same way as the other two.