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: