Difference between revisions of "LazMapViewer"
(→Properties: Add TMapView icon)
|Line 79:||Line 79:|
=== Properties ===
=== Properties ===
These are the main properties of the <tt>TMapView</tt> component:
These are the main properties of the <tt>TMapView</tt> component:
Revision as of 18:18, 2 January 2021
LazMapViewer is a component for embedding maps obtained from the internet, such as Google maps or OpenStreetView, into a Lazarus form.
The initial version of the package was written by Maciej Kaczkowski and later improved by members of the Lazarus forum.
Modified LGPL (with linking exception, like Lazarus LCL)
Download and Installation
Use an svn client to download the current trunk version from svn://svn.code.sf.net/p/lazarus-ccr/svn/components/lazmapviewer. Alternatively download the zipped snapshot from https://sourceforge.net/p/lazarus-ccr/svn/HEAD/tree/components/lazmapviewer/ and unzip it to some folder.
Occasionally, release versions are made available via the Online Package Manager for easy one-click-installation directly from Lazarus.
In Lazarus, go to "Package" > "Open Package File .lpk". Navigate to the folder with the LazMapViewer sources, and select lazmapviewerpkg.lkp. Click "Compile", then "Use" > "Install". This will rebuild the IDE (it may take some time). When the process is finished the IDE will restart, and you'll find the MapViewer in the palette Misc.
There are optional, supporting packages to extend the basic functionality. They must be installed in the same way, after lazmapviewerpkg.lpk.
|Package file name||contained components||purpose|
|lazmapviewerpkb.lpk||TMapView||main component to display maps|
|TMvGeoNames||access to geo coordinates of cities|
|TMvDEFpc||default download engine using the internal fpc routines|
|lazmapviewer_synapse.lpk||TMvDESynapse||alternative download engine based on the Synapse library|
|lazmapviewer_rgbgraphics.lpk||TMvRGBGraphicsDrawingEngine||Alternative drawing engine based on the RGBGraphics package|
|lazmapviewer_bgra.lpk||TMvBGRADrawingEngine||Alternative drawing engine based on the BGRABitmap package|
Here is a short tutorial to create your first map.
- Drop a TMapView component on the form and size it as needed. The component is on the Misc tab of the Lazarus component palette.
- Add this handler for the form's OnShow or OnActivate event and set the Active property of the MapView component to true; in principle, this should be possible also in the object inspectore, however, does not work at the time of this writing.
procedure TForm1.FormActivate(Sender: TObject); begin MapView1.Active := true; end;
- That's all. Compile, run and see your fist map!
- In the background the MapView component has established an internet connection to the default map provider and downloaded the default map. The maps are delivered as a series of tiled images at given size, usually 256x256 pixels, and usually in png format. They are stored in a cache directory (property CachePath) and used primarily to reduce internet traffic; only when an image is not found another download from the internet is triggered again.
- The map images are provided in different magnifications depending on the Zoom level of the MapView. Each step in Zoom level corresponds to doubling the magnification. The maximum Zoom level for most map providers is 18 -- this means that the most detailed maps cover a fraction of 1/2^18 of the earth circumference, about 150 m.
- So, if you want to see more details you must increase the Zoom value of the MapView. You can enter the requested value in the Object Inspector, or add a TScrollbar or TTrackbar to the form to change the magnfication interactively by using the following simple OnChange event handler (set the Max of the bar to, say, 18:
procedure TForm1.TrackBar1Change(Sender: TObject); begin MapView1.Zoom := TrackBar1.Position; end;
- Alternatively, zooming can also be achieved by rotating the mouse wheel.
- By default the center of the map is the intersection of the 0-degree meridian with the equator - which is a bit off of the coast of western Africa. In order to focus onto a different location you must specify its longitude and latitude in the Center property of the MapView. This is a TRealPoint record having the longitude and latitude in the Lon and Lat record elements.
- Suppose we want to zoom into Manhattan. Use your favorite search engine to determine the geo coordinates of Manhattan: Longitude = -73.985130°, Latitude = 40.758896°. Alternatively you can also use the TGeoNames component which comes with the LazMapViewer package and provides access to a database of the geo coordinates of a huge number of locations via internet.
procedure TForm1.FormActivate(Sender: TObject); var P: TRealPoint; begin MapView1.Active := true; P.Lon := -73.985130; P.Lat := 40.758896; MapView1.Center := P; end;
- In addition to specifying the location numerically the you can also change location by dragging the map with the mouse. Just press the left mouse button and slowly move the mouse in the direction where you want to see more - the map will follow. But you should be aware that usually neighboring maps will have to be loaded from the internet, and this makes the entire action a bit sluggish.
These are the main properties of the TMapView component:
- Active (boolean): must be set to true before the MapView component can display maps.
- CacheOnDisk (boolean): when set to true (default) dowloaded map tiles are stored in a directory to reduce internet traffic and for faster access. It is not recommended to turn this property off. The cache is not deleted automatically.
- CachePath (string): name of the directory in which downloaded map images are buffered.
- DownloadEngine (TMvCustomDownloadEngine): By default, the TFPHttpClient is employed to download the images from the map servers. If a different download engine is required the corresponding component can be hooked to this property. The standard installation of the LazMapViewer package contains the default TMvDEFPC downloader (based on FPC's TFPHttpClient) and the TMvDESynapse based on the Synapse library).
- DrawingEngine (TMvCustomDrawingEngine): Painting of the tiled images is a speed-critical task. By default, this is done using routines from the IntfGraphics unit; the corresponding drawing engine is in the TMvInfGraphicsDrawingEngine class. However, it is possible to provide a different drawing engine here. The standard installation of LazMapViewer comes with the alternative TMvRGBGraphicsDrawingEngine which is based on the RGBGraphics package, and with the TMvBGRADrawingEngine utilizing the BGRABitmap package.
- MapProvider (string): This string identifies the provider from which the maps are downloaded. Built-in providers allow to choose between OpenStreetMaps, GoogleMaps, Virtual Earth, Yandex etc. Details are given below.
- UseThreads (boolean): When set to true downloading and drawing of maps is delegated to several threads in order to achieve a smoother response. It is not recommended to turn this property off.
- Zoom (integer): Magnfication of the map: 0 = coarsest magnification, earth view, 17 or 18 = highest magnification. Each zoom step results in doubling of the magnfication factor.
- ZoomToCursor (boolean): When this is true zooming occurs relative to the mouse position, otherwise to the center of the map. This feature is interesing for zooming with the mouse wheel.
Here are properties related to overlayed GPS objects (points of interest, tracks):
- GPSItems: TGPSObjectList: list of GPS objects assigned to the MapView See below for details.
- DefaultTrackColor: TColor, DefaultTrackWidth: Integer: the default color and line width, respectively, of overlayed tracks. See below for details.
- POIImage: TBitmap: bitmap which will be overlayed to identify a "point of interest" (POI).
- POITextBgColor: TColor: background color of the overlayed text describing a point of interest. Turn off the text background by selecting clNone.
- OnCenterMove: fires whenever the Center of the MapView have been changed.
- OnChange: fires whenever the Center, size or Zoom factor of the MapView change.
- OnDrawGpsPoint: see below
- OnZoomChange: fires whenever the Zoom factor of the MapView changes.
- OnMouseDown, OnMouseEnter, OnMouseLeave, OnMouseMove, OnMouseUp: standard mouse events.
- procedure GetMapProviders(lstProviders: TStrings): Returns in lstProviders the names of all registered map providers. When one of these strings is assigned to the MapProvider property of the MapVieew the servers of the corresponding provider will become the source of the displayed maps.
- function GetVisibleArea: TRealArea: returns the top/left and bottom/right corner points of the displayed rectangle in geo coordinates. TRealArea is a record consisting of the TRealPoint records TopLeft and BottomRight.
- function LonLatToScreen(aPt: TRealPoint): TPoint: maps a geo point (longitude, latitude) to screen pixels (relative to the TMapView instance).
- function ScreenToLonLat(aPt: TPoint): TRealPoint: maps a the coordinates of a screen pixel (relative to the MapView instance) to geo coordinates (longitude, latitude). Here is an example how the geo coordinates of the mouse cursor can be displayed in two labels by means of the OnMouseMove event of the MapView:
uses mvTypes, // for TRealPoint mvEngine; // for LonToStr() and LatToStr() funtions procedure TForm1.MapView1MouseMove(Sender: TObject; Shift: TShiftState; X, Y: Integer); var P: TRealPoint; begin P := MapView1.ScreenToLonLat(Point(X, Y)); Label1.Caption := 'Longitude: ' + LonToStr(P.Lon, true); Label2.Caption := 'Latitude: ' + LatToStr(P.Lat, true); end;
- procedure SaveToFile(AClass: TRasterImageClass; const AFileName: String): Save the currently displayed map as bitmap of the given class to a file. Example for saving to a jpg image:
procedure TForm1.Button1Click(Sender: TObject); begin MapView1.SaveToFile(TJpegImage, 'mapview.jpg'); end;
- procedure SaveToStream(AClass: TRasterImageClass; AStream: TStream): Similar to SaveToFile, but output is not in a file, but in the stream provided.
- function SaveToImage(AClass: TRasterImageClass): TRasterImage: creates an instance of the given image class and writes the currently visible view port image to it.
- procedure CenterOnObj(obj: TGPSObj): Centers the map on the provided GPS object. More on GPS objects below.
- procedure ZoomOnArea(const aArea: TRealArea): Adjusts the Zoom level such that the given area is completely shown and fills the component bounds as much as possible.
- procedure ZoomOnObj(obj: TGPSObj): Adjusts the Zoom level such that the given GPS object is completely seen at highest magnification. More about GPS objects below.