Warning, /education/marble/docs/Programmers-manual.txt is written in an unsupported language. File is not indexed.

0001 
0002 <<< WARNING: MOST OF THIS CONTENT IS NOT UP-TO-DATE >>>
0003 
0004                       Marble Programmer's Manual
0005                       ==========================
0006 
0007 
0008 This file describes how you can use parts of Marble in your own
0009 program, and how you can enhance Marble in various ways.  We will only
0010 give an overview; the full API must be discovered through the API
0011 documentation.
0012 
0013 
0014 I. The Marble Architecture
0015 --------------------------
0016 
0017 Marble is both an application and a set of classes that will easily
0018 let you visualize geodata in your own application.  In addition to
0019 that, Marble supports plugins that will let you add data to the map. 
0020 
0021 TODO: classes and their relationships
0022 
0023 TODO: Data (files, network)
0024 
0025 
0026 II. Using Marble in your own program
0027 ------------------------------------
0028 
0029 
0030 As described above, the Marble package contains classes that let you
0031 use show geodata in your own application.
0032 
0033 
0034 II.1 Embedding the MarbleWidget in Your Application
0035 
0036 Embedding the MarbleWidget is by far the easiest way to use Marble in
0037 your own application.  You can use the MarbleWidget just like any
0038 other QWidget.  If you have installed the Qt Designer plugins, you can
0039 even use the Designer to insert the MarbleWidget into any .ui file.
0040 
0041 To let the user control the MarbleWidget, you need one of either
0042 MarbleControlBox or MarbleNavigator, both QWidgets.  The
0043 MarbleControlBox is a full-blown control widget that will let the user
0044 control all aspects of the MarbleWidget: map theme, projection,
0045 position, zoom. It also provides a search function for placemarks.
0046 
0047 The MarbleNavigator is a simpler control widget that only lets the
0048 user navigate (pan, zoom and home position). The other aspects of the
0049 widget will have to be controlled in some other way through the API.
0050 
0051 In addition to the control widgets, the user can also control the
0052 MarbleWidgets through keyboard or mouse events.  This is done through
0053 a class called MarbleWidgetInputHandler.  There is a default
0054 implementation of the base class called
0055 MarbleWidgetDefaultInputHandler, which provides the default
0056 behaviour.  However, the application programmer can define any
0057 MarbleWidgetInputHandler and register that in the widget through the
0058 setInputHandler() function.
0059 
0060 
0061 II.2 Using the MarbleMap class
0062 
0063 Programmers who cannot use a MarbleWidget can still use Marble. The
0064 way to do it is to use the more abstract class MarbleMap.  It
0065 represents the contents of the MarbleWidget, but without the widget
0066 part.  A MarbleMap can be manipulated in almost the same way as the
0067 MarbleWidget. In fact, a MarbleWidget can almost be seen as just a
0068 container around the MarbleMap.
0069 
0070 The most important function of the MarbleMap is paint() function.  It
0071 uses the GeoPainter to paint the map on any QPaintDevice, and a QRect
0072 which indicates the part of the image to paint.  This can be useful in
0073 situations where only part of the image has to be redrawn.
0074 
0075 The GeoPainter is a class derived from QPainter with some additional
0076 features: 
0077 
0078  - It can be used to paint on the map using geo coordinates (lat,
0079    lon).  The features that are drawn on the map will be painted in
0080    any supported projection can map painted either geo projected or
0081    not geo projected.  The former means that e.g. a rectangle that is
0082    geo projected may be drawn with non-straight edges according to the
0083    chosen projection.
0084 
0085  - It can paint with different qualities (see class MapQuality), which
0086    is used to speed things up e.g. during panning or zooming.
0087 
0088  - It has some optimizations that are relevant when very large objects
0089    are painted, which is not uncommon at high zoom levels.  These
0090    optimizations are especially important when the objects in question
0091    are outside the visible area or only partly visible. 
0092 
0093 For more uses of the GeoPainter class, see the chapter below on
0094 writing Marble plugins.
0095 
0096 
0097 III. Enhancing Marble's Functionality
0098 -------------------------------------
0099 
0100 
0101 III.1 Adding New Maps 
0102 
0103 III.1.1 Marble Path
0104 
0105 III.1.2 DGML
0106 
0107 
0108 
0109 III.2 Writing Marble Plugins
0110 
0111 TODO: Layers
0112 
0113 TODO: GeoPainter
0114 
0115 TODO: