Marble C++ Tutorial Part 1

Tuesday, 3 August 2010  |  Torsten Rahn

In a few hours KDE 4.5 will be released. And together with it the new version of our Virtual Globe and Map Widget Marble. The new release Marble 0.10.0 will bring lots of additional features (Routing, Tile-Bulk-Download, Multiple Layers, initial WMS support and a lot more) - many of them related to OpenStreetMap.

Of course development on the next release has started already: Dennis Nienhüser and Niko Sams have added Worldwide and Offline Routing support to Marble using Gosmore and Routino.

In other news the spanish Linux Magazine has published a really nice article by Tim Schürmann about Marble the application: "¡MARBILLOSO! Marble se ha convertido en una alternativa interesante a Google Earth, y funciona sin conexión a Internet. Marble Facebook Group!

But Marble is more than an application: You can use the MarbleWidget and its framework in your own application to display map data! There are many applications which are doing this already. See our success story page for more information. And today we start to show how to do it. All you need for our Tutorial is a little bit of C++ and basic Qt knowledge:

Hello Marble!


The API of the Marble library allows for a very easy integration of a map widget into your application.

Let's prove that with a tiny Hello world-like example: Qt beginners might want to have a look at the Qt Widgets Tutorial to learn more about the details of the code. But this is probably not necessary. For a start we just create a QApplication object and a MarbleWidget object which serves as a window.

By default the MarbleWidget uses the ''Atlas'' map theme. However for our first example we choose to display streets. So we set the maptheme id to OpenStreetMap. Then we call QWidget::show() to show the map widget and we call QApplication::exec() to start the application's event loop. That's all!

#include <QtGui/QApplication> #include <marble/MarbleWidget.h>

using namespace Marble;

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

// Create a Marble QWidget without a parent
MarbleWidget *mapWidget = new MarbleWidget();

// Load the OpenStreetMap map
mapWidget->setMapThemeId("earth/openstreetmap/openstreetmap.dgml");

mapWidget->show();

return app.exec();

}

Copy and paste the code above into a text editor. Then save it as my_marble.cpp and compile it by entering the folling command on the command line:

g++ -I /usr/include/qt4/ -o my_marble my_marble.cpp -lmarblewidget -lQtGui

If things go fine, execute ./my_marble and you end up with a fully usable OpenStreetMap application:


That's all for today. In our next chapter we'll show how to create a basic weather map with Marble. We'll also show how to change basic properties of the map widget. So stay tuned. If you need help join us on our mailing list marble-devel@kde.org or on #marble (IRC on Freenode).

Tip


Here's a little checklist to tackle some problems that might arise when compiling the code above:

  • You need Qt and Marble development packages (or comparable SVN installations)
  • If ''Qt headers'' are not installed in /usr/include/qt4 on your system, change the path in the g++ call above accordingly.
  • Likewise, add -I /path/to/marble/headers if they're not to be found in /usr/include

Note


If you provide maps in your application please check the Terms of Use of the map material. The map material that is shipped with Marble is licensed in the spirit of Free Software. This usually means at least that the authors should be credited and that the license is mentioned.

E.g. for OpenStreetMap the license is CC-BY-SA. Other map data shipped with Marble is either public domain or licensed in the spirit of the BSD license.