Marble Programmer's Manual
		      ==========================


This file describes how you can use parts of Marble in your own
program, and how you can enhance Marble in various ways.  We will only
give an overview; the full API must be discovered through the API
documentation.


I. The Marble Architecture
--------------------------

Marble is both an application and a set of classes that will easily
let you visualize geodata in your own application.  In addition to
that, Marble supports plugins that will let you add data to the map. 

TODO: classes and their relationships

TODO: Data (files, network)


II. Using Marble in your own program
------------------------------------


As described above, the Marble package contains classes that let you
use show geodata in your own application.


II.1 Embedding the MarbleWidget in Your Application

Embedding the MarbleWidget is by far the easiest way to use Marble in
your own application.  You can use the MarbleWidget just like any
other QWidget.  If you have installed the Qt Designer plugins, you can
even use the Designer to insert the MarbleWidget into any .ui file.

To let the user control the MarbleWidget, you need one of either
MarbleControlBox or MarbleNavigator, both QWidgets.  The
MarbleControlBox is a full-blown control widget that will let the user
control all aspects of the MarbleWidget: map theme, projection,
position, zoom. It also provides a search function for placemarks.

The MarbleNavigator is a simpler control widget that only lets the
user navigate (pan, zoom and home position). The other aspects of the
widget will have to be controlled in some other way through the API.

In addition to the control widgets, the user can also control the
MarbleWidgets through keyboard or mouse events.  This is done through
a class called MarbleWidgetInputHandler.  There is a default
implementation of the base class called
MarbleWidgetDefaultInputHandler, which provides the default
behaviour.  However, the application programmer can define any
MarbleWidgetInputHandler and register that in the widget through the
setInputHandler() function.


II.2 Using the MarbleMap class

Programmers who cannot use a MarbleWidget can still use Marble. The
way to do it is to use the more abstract class MarbleMap.  It
represents the contents of the MarbleWidget, but without the widget
part.  A MarbleMap can be manipulated in almost the same way as the
MarbleWidget. In fact, a MarbleWidget can almost be seen as just a
container around the MarbleMap.

The most important function of the MarbleMap is paint() function.  It
uses the GeoPainter to paint the map on any QPaintDevice, and a QRect
which indicates the part of the image to paint.  This can be useful in
situations where only part of the image has to be redrawn.

The GeoPainter is a class derived from QPainter with some additional
features: 

 - It can be used to paint on the map using geo coordinates (lat,
   lon).  The features that are drawn on the map will be painted in
   any supported projection can map painted either geo projected or
   not geo projected.  The former means that e.g. a rectangle that is
   geo projected may be drawn with non-straight edges according to the
   chosen projection.

 - It can paint with different qualities (see class MapQuality), which
   is used to speed things up e.g. during panning or zooming.

 - It has some optimizations that are relevant when very large objects
   are painted, which is not uncommon at high zoom levels.  These
   optimizations are especially important when the objects in question
   are outside the visible area or only partly visible. 

For more uses of the GeoPainter class, see the chapter below on
writing Marble plugins.


III. Enhancing Marble's Functionality
-------------------------------------


III.1 Adding New Maps 

III.1.1 Marble Path

III.1.2 DGML



III.2 Writing Marble Plugins

TODO: Layers

TODO: GeoPainter

TODO: