Contents

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.

Item

We will write our item first as it depends on nothing else. As you should already know the item stores the data and paints it on the screen. One item has an exact position on the globe as longitude, latitude and altitude.
The item we will write shows a text at the specific position.

We will now look at the header file to see what functions we have to implement.
TutorialItem.h
// This is to prevent this header to be included multiple times

// On a text change our size may also change, so we have to set the new
// item size. Marble needs to know how large an item is to find the correct
// bounding rect. The given position will always be in the middle of the
// item for now.
QFontMetrics metrics( s_font );
setSize( metrics.size( 0, text ) );
m_text = text;

You see that we have to implement the function getAdditionalItems(). getAdditionalItems() is called when the viewport has been changed significantly, so new items have to be generated.
For getAdditionalItems() we will go the easy way for now. We will simply add one item with a static position. That's a very simple method to test your painting code.

// This plugin only supports Tutorial items for earth
if( facade->target() != "earth" ) {
return;
}
// We will only create one item in our first tutorial.
// Every item has to get an id. We have to check if the item already exists.
if ( !itemExists( "tutorial1" ) ) {
// If it does not exists, create it
GeoDataCoordinates coor( 10.22 * DEG2RAD, 54.4 * DEG2RAD );
// The parent of the new item is this object
TutorialItem *item = new TutorialItem( this );
item->setCoordinate( coor );
item->setTarget( "earth" );
item->setId( "tutorial1" );
// The text we want to show, of course "Hello World!"
item->setText( "Hello World!" );
// Add the item to the list of items, so it will be displayed.
addItemToList( item );
}

}

include "TutorialModel.moc"

If you want to download files from a web server to get lists of items, you will want to use void downloadDescriptionFile( const QUrl& url ) and you have to reimplement void parseFile( const QByteArray& file ), which parses the downloaded description file and adds new items to the list.

If you want to download files per item (for example if you want to display images), you can use void downloadItemData( const QUrl& url, const QString& type, AbstractDataPluginItem *item ). This will also add the items to the list of items. The type is something you have to invent yourself. It has to be unique in your plugin. The function void addDownloadedFile( const QString& url, const QString& type ) of our item is called when the download has been finished. This is what you need to implement.

To see examples of the usage of these functions, look at wikipedia-plugin and photo-plugin.

This will need the line
add_subdirectory( tutorialPlugin )
in marble/src/plugins/render.

Now you can recompile and reinstall marble, so the plugin will be installed at the correct place. Starting Marble will result in an additional menu entry in "View"->"Online Services". If selected, you will see the string "Hello World!" displayed near Kiel, Germany.