Marble/RunnerHOWTO: Difference between revisions

    From KDE TechBase
    (Reflect code state in trunk)
    m (Text replace - "<code>" to "<syntaxhighlight lang="text">")
    (2 intermediate revisions by the same user not shown)
    Line 15: Line 15:


    '''ExampleRunner.h'''
    '''ExampleRunner.h'''
    <code cppqt>
    <syntaxhighlight lang="cpp-qt">


    #ifndef EXAMPLERUNNER_H
    #ifndef EXAMPLERUNNER_H
    Line 39: Line 39:
    #endif
    #endif


    </code>
    </syntaxhighlight>


    This basically just defines the class; it doesn't do anything else.
    This basically just defines the class; it doesn't do anything else.
    Line 45: Line 45:
    '''ExampleRunner.cpp'''
    '''ExampleRunner.cpp'''


    <code cppqt>
    <syntaxhighlight lang="cpp-qt">
    #include "ExampleRunner.h"
    #include "ExampleRunner.h"


    Line 94: Line 94:
    #include "ExampleRunner.moc"
    #include "ExampleRunner.moc"


    </code>
    </syntaxhighlight>


    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.
    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.
    Line 104: Line 104:
    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, like so:
    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, like so:


    <code>
    <syntaxhighlight lang="text">
    Index: src/lib/MarbleRunnerManager.h                         
    Index: src/lib/MarbleRunnerManager.h                         
    ===================================================================
    ===================================================================
    Line 166: Line 166:


      set (marblewidget_UI
      set (marblewidget_UI
    </code>
    </syntaxhighlight>


    The result of this is that when you search for "Middle of Nowhere", you get:
    The result of this is that when you search for "Middle of Nowhere", you get:
    [[Image:MiddleOfNowhere.png]]
    [[Image:MiddleOfNowhere.png]]

    Revision as of 20:49, 29 June 2011

    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 MarbleRunnerManager starts each runner thread and registers it as 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 must 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 thread's run() method. It should emit runnerFinished() at any exit point. The input is provided to the base class via the parse() method which stores the input.

    ExampleRunner.h

    #ifndef EXAMPLERUNNER_H
    #define EXAMPLERUNNER_H
    
    #include "MarbleAbstractRunner.h"
    
    namespace Marble
    {
    
    class ExampleRunner : public MarbleAbstractRunner
    {
        Q_OBJECT
    public:
        ExampleRunner(QObject *parent = 0);
        ~ExampleRunner();
        GeoDataFeature::GeoDataVisualCategory category() const;
        virtual void run();
    };
    
    }
    
    #endif
    

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

    ExampleRunner.cpp

    #include "ExampleRunner.h"
    
    #include "MarbleAbstractRunner.h"
    #include "GeoDataFeature.h"
    #include "GeoDataPlacemark.h"
    #include "GeoDataCoordinates.h"
    
    #include <QtCore/QDebug>
    #include <QtCore/QString>
    #include <QtCore/QStringList>
    #include <QtCore/QVector>
    
    namespace Marble
    {
    
    ExampleRunner::ExampleRunner(QObject *parent) : MarbleAbstractRunner(parent)
    {
    }
    
    
    GeoDataFeature::GeoDataVisualCategory ExampleRunner::category() const
    {
        return GeoDataFeature::Default;
    }
    
    ExampleRunner::~ExampleRunner()
    {
    }
    
    void ExampleRunner::run()
    {
        QVector<GeoDataPlacemark*> vector;
        if(input.toLower() == tr("middle of nowhere")) {
            GeoDataPlacemark *placemark = new GeoDataPlacemark();
            placemark->setCoordinate( -90.1833 *DEG2RAD, 51.4666 *DEG2RAD);
            placemark->setName( m_input );
            placemark->setVisualCategory( category() );
            placemark->setPopularity( 1000000000 );
            placemark->setPopularityIndex( 18 );
            vector.append( placemark );
        }
        emit runnerFinished(vector);
    }
    
    }
    
    #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.

    The input is taken doing 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, like so:

    Index: src/lib/MarbleRunnerManager.h                         
    ===================================================================
    --- src/lib/MarbleRunnerManager.h       (revision 886350)          
    +++ src/lib/MarbleRunnerManager.h       (working copy)             
    @@ -33,6 +33,7 @@                                                  
                                                                       
     class LatLonRunner;                                               
     class OnfRunner;                                                  
    +class ExampleRunner;                                              
                                                                       
     class MarbleRunnerManager : public QObject                        
     {                                                                 
    @@ -60,6 +61,7 @@                                                  
                                                                       
         LatLonRunner *m_latlonRunner;                                 
         OnfRunner *m_onfRunner;                                       
    +    ExampleRunner *m_exampleRunner;                               
     };                                                                
                                                                       
     }                                                                 
    Index: src/lib/MarbleRunnerManager.cpp                             
    ===================================================================
    --- src/lib/MarbleRunnerManager.cpp     (revision 886350)          
    +++ src/lib/MarbleRunnerManager.cpp     (working copy)             
    @@ -27,6 +27,7 @@                                                  
                                                                       
     #include "LatLonRunner.h"                                         
     #include "OnfRunner.h"                                            
    +#include "ExampleRunner.h"                                        
                                                                       
     #include <QtCore/QObject>                                         
     #include <QtCore/QString>                                         
    @@ -66,6 +67,16 @@                                                 
                  this,        SLOT( slotRunnerFinished( QVector<GeoDataPlacemark*> ) ));
         connect( this,        SIGNAL( engage(QString) ),                                
                  m_onfRunner, SLOT( parse(QString) ));                                  
    +                                                                                    
    +    m_exampleRunner = new ExampleRunner(0);                                         
    +    m_exampleRunner->start();                                                       
    +    m_exampleRunner->moveToThread(m_exampleRunner);                                 
    +    connect( m_exampleRunner, SIGNAL( runnerStarted() ),                            
    +             this,        SLOT( slotRunnerStarted() ));                             
    +    connect( m_exampleRunner, SIGNAL( runnerFinished( QVector<GeoDataPlacemark*> ) ),
    +             this,        SLOT( slotRunnerFinished( QVector<GeoDataPlacemark*> ) )); 
    +    connect( this,        SIGNAL( engage(QString) ),                                 
    +             m_exampleRunner, SLOT( parse(QString) ));                               
     }                                                                                    
    
     MarbleRunnerManager::~MarbleRunnerManager()
    Index: src/lib/CMakeLists.txt
    ===================================================================
    --- src/lib/CMakeLists.txt      (revision 886350)
    +++ src/lib/CMakeLists.txt      (working copy)
    @@ -161,6 +161,7 @@
         runners/MarbleAbstractRunner.cpp
         runners/LatLonRunner.cpp
         runners/OnfRunner.cpp
    +    runners/ExampleRunner.cpp
     )
    
     set (marblewidget_UI
    

    The result of this is that when you search for "Middle of Nowhere", you get: