Marble/OnlineServices

Creating your first Marble Online Services Plugin

Tutorial Series	Marble Tutorial
Previous	C++, Qt, KDE4 development environment
What's Next
Further Reading	CMake

This Tutorial is unfinished, I'll finish it in a few days.

Abstract

You will here learn to create your own online service plugins. If you don't know what is meant by online service, you will see these in the Marble menu at "View"->"Online Services". You'll need KDE 4.3 to build this tutorial. If you want to write plugins for Marble, it could be useful to do this in KDE's subversion. Please contact the Marble developers for this (IRC, E-Mail).

Structure

An online services plugin or data plugin consist of three classes at least. The class to display the information is the Data Item (the base class is AbstractDataPluginItem). It stores the information for single places on the map and displays them.

The Model (base class AbstractDataPluginModel) stores all items. Storing the items will be done by AbstractDataPluginModel itself. Your only job is to get information for new items when the displayed part of the earth changes. This can include downloading so called "Description files" from the servers of an online service and parsing them. These "Description files" contain lists of items in a specific part of the earth (specified by a LatLonAltBox).

The class based on AbstractDataPlugin is the representation class of our plugin. It provides the name and the idea of the plugin. You also have to set your model there.

Model

We will start developing the core component, the model. Let's first look at the header file: TutorialModel.h // This prevents from including the header multiple times

1. ifndef TUTORIALMODEL_H
2. define TUTORIALMODEL_H

1. include "AbstractDataPluginModel.h"

1. include <QtGui/QIcon>
2. include <QtGui/QPixmap>

namespace Marble {

class MarbleDataFacade;

// The maximum number of items we want to show on the screen. const quint32 numberOfItemsOnScreen = 20;

class TutorialModel : public AbstractDataPluginModel {

   Q_OBJECT
   
public:
   TutorialModel( QObject *parent = 0 );
   ~TutorialModel();

protected:
   /**
    * Generates the download url for the description file from the web service depending on
    * the @p box surrounding the view and the @p number of files to show.
    **/
   void getAdditionalItems( const GeoDataLatLonAltBox& box,
                            MarbleDataFacade *facade,
                            qint32 number = 10 );
      
   /**
    * The reimplementation has to parse the @p file and should generate widgets. This widgets
    * have to be scheduled to downloadItemData or could be directly added to the list,
    * depending on if they have to download information to be shown.
    **/
   void parseFile( const QByteArray& file );

};

}

1. endif // TUTORIALMODEL_H

You see that we have to implement the functions parseFile() and getAdditionalItems(). getAdditionalItems() is called when the viewport has been changed significantly, so new items have to be generated. parseFile() is called when a description file has been downloaded which probably needs parsing.

Let's continue with the interesting part, the implementation:

// Self

1. include "TutorialModel.h"

// Marble

1. include "global.h"

// Qt

1. include <QtCore/QString>

using namespace Marble;

TutorialModel::TutorialModel( QObject *parent )

   : AbstractDataPluginModel( "tutorial", parent ) 

{ }

TutorialModel::~TutorialModel() { }

void TutorialModel::getAdditionalItems( const GeoDataLatLonAltBox& box,

                                        MarbleDataFacade *facade,
                                        qint32 number )

{

   // This plugin only supports Tutorial items for earth
   if( facade->target() != "earth" ) {
       return;
   }
   
   // Generate your items here

}

void TutorialModel::parseFile( const QByteArray& file ) { }

1. include "TutorialModel.moc"