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

0001 
0002 II. PAINTING THE MAP
0003 ====================
0004 
0005 The developer who wants to use Marble in his own application will 
0006 want to paint the map at some point.
0007 
0008 Generally Marble could be used in two different representations:
0009 
0010 1.) Using Marble as a Widget. This can be done by using the MarbleWidget
0011 class in your application.
0012 Alternatively you can use the Qt-Designer MarbleWidget-Plugin. .
0013 
0014 2.) Using the MarbleMap interface to create just the map on a
0015 QPaintDevice. This can be used for plasmoids, flake shapes or for
0016 exporting and printing a map at a higher resolution.
0017 
0018 Furthermore there are different things you might want to do with the
0019 map:
0020 
0021 A.) ViewParameter-based SIMPLE API
0022 
0023 For most cases simply painting the map with preset settings is enough.
0024 Loading a KML document to add  geographical features adds a powerful
0025 capability to customize the map.
0026 
0027 Painting the map can be done e.g. via source code like this (example:
0028 big weather map for printing):
0029 
0030     MarbleMap map;
0031 
0032     map.resize(5000, 2500);
0033     map.setRadius( 2000 );
0034     map.setMapTheme( earth/bluemarble/bluemarble.dgml );
0035     map.open( currentweather.kml );
0036 
0037     [...]
0038 
0039 So most of the Simple API deals with adjusting ViewParameters according
0040 to the needs. The actual "painting" gets triggered and done by a single
0041 paint call.
0042 
0043 
0044 If you want to apply custom modifications in geographic coordinates by
0045 creating source code then the SIMPLE API won't be enough: you'd
0046 otherwise have to deal yourself with very complex internal stuff ( like
0047 clipping, Node interpolation, OpenGL, etc. ) even for such "simple"
0048 tasks as drawing a single line between two geographical coordinates. 
0049 In this case you will want to make use of the Qt-Style Painter-API.
0050 
0051 B) Advanced QT-STYLE PAINTER-API
0052 
0053 In some cases you might want to add geographical features via source
0054 code changes. There are two different locations in which you might want
0055 to do this:
0056 
0057 - Externally from your application that uses the MarbleWidget (e.g. if
0058 you just want to add a few features where creating a whole backend
0059 plugin from scratch makes little sense).
0060 
0061 - Internally inside a custom backend plugin.
0062 
0063 Before adjusting the map using the Qt-Style Painter-API you usually have
0064 to "initialize" and prepare the map by using the Simple API.
0065 Creating new geographical features on the map should happen using a
0066 Qt-style Painter-API (which would include the QPainter/ClipPainter API
0067 to draw in screen coordinates):
0068 
0069   Code snippet:
0070 
0071     bool MarbleTestPlugin::render( GeoPainter *painter, ViewportParams *viewport, const QString& renderPos, GeoSceneLayer * layer )
0072     {
0073     painter->autoMapQuality();
0074     painter->setPen( Qt::red );
0075 
0076     GeoDataCoordinates flensburg( 9.4, 54.8, 0.0, GeoDataCoordinates::Degree );
0077     GeoDataCoordinates madrid( -3.7, 40.4, 0.0, GeoDataCoordinates::Degree );
0078 
0079     painter->drawLine( flensburg, madrid );
0080     painter->drawPlacemark( "Flensburg", flensburg ); // Yet to be implemented (doesn't work atm)
0081 
0082     // isGeoProjected = true paints a circle that might be 
0083     // "distorted" according to the geographical projection. 
0084     // The height and width would be 5 degrees
0085     painter->drawEllipse( flensburg, 5, 5, true ); 
0086 
0087     // isGeoProjected = true would paint a ("unprojected" circle that 
0088     // has got a width and height of 5 pixels. 
0089     painter->drawEllipse( flensburg, 5, 5, false ); 
0090 
0091 Using this API some backend plugins like the MeasureTool could get
0092 squeezed down to very little code.
0093 
0094 Internally these GeoPainter calls will get "translated" to the methods
0095 provided by the mandatory basic backend plugins. (like lines getting
0096 drawn via the vector backend plugin).
0097 
0098