Skip to content

TTMSFMXNativeMKMapView

Usage

A TMSFMXNativeMKMapView object provides an embeddable map interface, similar to the one provided by the Maps application. You use this class as-is to display map information and to manipulate the map contents from your application. You can center the map on a given coordinate, specify the size of the area you want to display, and annotate the map with custom information.

Methods

Method name Description
AddAnnotation(ALatitude, ALongitude: Double): TTMSFMXNativeMKAnnotation Adds and returns a new annotation based on a Latitude and Longitude.
AddAnnotation(ALatitude, ALongitude: Double; ATitle, ASubTitle: String): TTMSFMXNativeMKAnnotation Adds and returns a new annotation based on a Latitude, Longitude, Title and SubTitle.
AddAnnotation(ALocation: TTMSFMXNativeMKMapLocation): TTMSFMXNativeMKAnnotation Adds and returns a new annotaton based on a location.
AddAnnotation(ALocation: TTMSFMXNativeMKMapLocation; ATitle, ASubTitle: String): TTMSFMXNativeMKAnnotation Adds and returns a new annotation based on a location, Title and SubTitle.
AddCircle(ALatitude, ALongitude: Double; ARadius: Double): TTMSFMXNativeMKOverlay Adds and returns a new circle overlay shape based on a Latitude, Longitude and Radius parameter. The Radius parameter is in meters.
AddCircle(ALocation: TTMSFMXNativeMKMapLocation; ARadius: Double): TTMSFMXNativeMKOverlay Adds and returns a new circle overlay shape based on a Latitude, Longitude and Radius parameter. The Radius parameter is in meters.
AddPolygon(ALocations: array of TTMSFMXNativeMKMapLocation): TTMSFMXNativeMKOverlay Adds and returns a new polygon overlay shape based on an array of Locations.
AddPolyline(ALocations: array of TTMSFMXNativeMKMapLocation):TTMSFMXNativeMKOverlay Adds and returns a new polyline overlay shape based on an array of Locations.
DeSelectAnnotation(AAnnotation: TTMSFMXNativeMKAnnotation) Deselects the annotation with or without animation.
function AddImage(AURL: String; ATopLeftLocation, ABottomRightLocation: TTMSFMXNativeMKMapLocation): TTMSFMXNativeMKOverlay; Adds and returns a new overlay image at a specific topleft and bottomright coordinate. (iOS 7 or later)
function AddTiling(AURL: String): TTMSFMXNativeMKOverlay; Adds and returns a new overlay object that supports rendering tiles from a specific tile server. (iOS 7 or later)
GetAnnotation(Annotation: MKAnnotion): TTMSFMXNativeMKAnnotatio Returns the annotation collection item based on the native MKAnnotation.
GetOverlay(Overlay: MKOverlay): TTMSFMXNativeMKOverlay Returns the overlay collection item based on the native MKOverlay.
GetRegion: TTMSFMXNativeMKMapRegion; Returns the current region.
GetUserLocation: TTMSFMXNativeMKMapLocation Returns the current user location
procedure GetDirections(AStartLocation, AEndLocation: TTMSFMXNativeMKMapLocation; AAlternateRoutes: Boolean = False; ATransportType: TTMSFMXNativeMKMapViewDirectionsTransportType = ttDirectionsTransportTypeAutomobile; ADepartureDate: TDateTime = -1; AArrivalDate: TDateTime = -1); Starts a get directions request with a given start and end location and optional parameters such as the possibility to calculate alternate routes and a departure and arrival date. When calling this method, the OnGetDirections event is triggered. When an error occurred during the request, the OnGetDirectionsError event is triggered.

There is a second overload that accepts latitude and longitude parameters for both the start and the end location as doubles. (iOS 7 or later)
RemoveAllAnnotations Removes all annotations from the collection and the MapView.
RemoveAllOverlays Removes all the overlays from the collection and the MapView
RemoveAnnotation(AAnnotation: TTMSFMXNativeMKAnnotation) Removes a specific annotation from the collection and the MapView.
RemoveOverlay(AOverlay:TTMSFMXNativeMKOverlay) Removes a specific overlay from the collection and the MapView.
SelectAnnotaion(AAnnotation: TTMSFMXNativeMKAnnotation; AAnimated: Boolean) Selects a specific annotation and shows the callout, with or without animation.
SetCenterLocation(ALocation: TTMSFMXNativeMKMapLocation) Centers the map at a specific location.
SetRegion(ARegion: TTMSFMXNativeMKMapRegion; AAnimated: Boolean) Sets the visible region of the MapView.
SetRegion(ATopLeftLocation, ABottomRightLocation: TTMSFMXNativeMKMapLocation; AAnimated: Boolean) Sets the visible region of the MapView with TopLeft and BottomRight coordinates.
XYToCoordinate(X, Y: Single): TTMSFMXNativeMKMapLocation Returns a latitude and longitude of an X and `Y coordinate on the map based on the current region of the MapView.
ZoomToFitAnnotations(AIncludeUserLocation: Boolean = false; ALatitudeSpanOffset: Double = 0; ALongitudeSpanOffset: Double = 0); Zoom the mapview to show/fit all annotations with optional parameters to include user location and additional region span offset.

Events

Property name Description
OnAnnotationDragStateChanged Event called when a pin is being dragged to a new location.
OnAnnotationLeftCalloutAccessoryTapped Event called when the left callout accessory is tapped on an annotation.
OnAnnotationRightCalloutAccessoryTapped Event called when the right callout accessory is tapped on an annotation.
OnClick Event called when clicking on the map. The latitude and longitude of the position on the map are passed as parameters.
OnDidDeselectAnnotationView Event called when deselectin an annotation.
OnDidFailLoadingMap Event called when the map loading failed.
OnDidFailToLocateUser Event called when the map did fail to locate the user location when the user location is active.
OnDidFinishLoadingMap Event called when the map did finish loading.
OnGetDirections Event called when a directions request is finished and successfully found one or multiple routes.
OnGetDirectionsError Event called when a directions request is finished and an error occurred during the request.
OnSelectAnnotationView Event called when an annotation is selected.
OnDidStopLocatingUser Event called when the MapView stops locating the user.
OnDidUpdateUserLocation Event called when the user location is updated.
OnLongPress Event called when tap holding on the MapView for at least 1.5 seconds
OnRegionDidChangeAnimated Event called when the region of the MapView is changed.
OnRegionWillChangeAnimated Event called when the region of the MapView will change.
OnWillStartLoadingMap Event called when the MapView will start loading.
OnWillStartLocatingUser Event called when the MapView will start locating the user.

Adding Annotations

Annotations can be added to the map by directly adding them to the collection, or through one of the AddAnnotation overload methods. Below is a sample that demonstrates this.

In this sample, we drop a TMSFMXNativeMKMapView control on the form and add the following code in a button click: 

var
  loc: TTMSFMXNativeMKMapLocation;
begin
  loc := TMSFMXNativeMKMapView1.XYToCoordinate(TMSFMXNativeMKMapView1.Width / 2, 
    TMSFMXNativeMKMapView1.Height / 2);
  TMSFMXNativeMKMapView1.AddAnnotation(loc, 'Hello World', 'Subtitle');

This code will return the correct coordinate of the center of the map, regardless of where the map is positioned. Clicking the button drops an annotation on the MapView:

ttmsfmxnativemkmapview

If you pan the Map, and click the button, the pin will be dropped in the center of the MapView again, but on a different coordinate. The XYToCoordinate functionality is using the current region, and zooming level of the MapView to return the correct coordinate.

Pin vs View

By default, the annotation that is added on the map displays a pin, but this can also be changed per annotation. On the annotation collection item, a Bitmap property is available to customize the default view of an annotation. The sample below shows how to add a custom image for an annotation. 

var
  loc: TTMSFMXNativeMKMapLocation;
  ann: TTMSFMXNativeMKAnnotation;
begin
  loc := TMSFMXNativeMKMapView1.XYToCoordinate(TMSFMXNativeMKMapView1.Width / 2, 
    TMSFMXNativeMKMapView1.Height / 2);
  ann := TMSFMXNativeMKMapView1.AddAnnotation(loc, 'Hello World', 'Subtitle');
  ann.Bitmap.LoadFromFile(ExtractFilePath(ParamStr(0))+'pin.png');
ttmsfmxnativemkmapview1

Adding Overlays

Overlays are shapes that can be added to the map, there are different kinds of overlays, and each ovelay can be configured in stroke and fill color and opacity. The MapView exposes an overlay collection and a couple of functions that can be used to add an overlay to the map. Currently, a circle, polygon and polyline can be added to the MapView. Below is a sample of a circle and a polyline that is added to the MapView. Note that the code is wrapped with a BeginUpdate and EndUpdate. This is crucial to make sure the overlay shape has the correct position, and appearance when added. 

//Center circle with 500 km radius
TMSFMXNativeMKMapView1.BeginUpdate;
c := TMSFMXNativeMKMapView1.AddCircle(TMSFMXNativeMKMapView1.XYToCoordinate(TMSFMXNativeMKMapView1.Width / 2,
  TMSFMXNativeMKMapView1.Height / 2), 500000);
c.LineWidth := 3;
c.LineColor := TAlphaColorRec.Greenyellow;
c.Color := TAlphaColorRec.Darkgoldenrod;
c.Opacity := 0.5;
c.LineOpacity := 0.5;
TMSFMXNativeMKMapView1.EndUpdate;

//Bermuda triangle
TMSFMXNativeMKMapView1.BeginUpdate;
arr[0].Latitude := 25.774252;
arr[0].Longitude := -80.190262;
arr[1].Latitude := 18.466465;
arr[1].Longitude := -66.118292;
arr[2].Latitude := 32.321384;
arr[2].Longitude := -64.75737;
arr[3] := arr[0];

c := TMSFMXNativeMKMapView1.AddPolyline(arr);
c.LineColor := TAlphaColorRec.Red;
TMSFMXNativeMKMapView1.EndUpdate;

User Location

The MapView can also display the user location, to show the user location, you can set the property ShowsUserLocation to true. When the application shows the user location for the first time, the application asks if it is ok to allow access. After clicking ok, the user location is being displayed inthe MapView.

When the user location is displayed, the MapView does not automatically scroll to the location. The sample implements the OnDidUpdateUserLocation to center the user location and log the latitude and longitude in a listbox.

ttmsfmxnativemkmapview2

ttmsfmxnativemkmapview3

Included in the distribution is a Map demo that demonstrates adding annotations, panning and zooming in the MapView as well as showing a callout accessory view to display additional information.

Directions (iOS 7 or later)

The MapView has built-in functionality to calculate directions between 2 locations. Below is a sample between San Francisco and Los Angeles with the optional parameter to calculate alternative routes. 

TMSFMXNativeMKMapView1.GetDirections(37.774929499999999, -122.4194155, 34.054434999999998, -118.253393, true);
After executing this request, the OnGetDirections event is called with a TTMSFMXNativeMKDirectionsResponse record which contains information about the routes that were found. To visualize this data, you can add a polyline to the map that accepts an array of locations with the following code: 
procedure TForm1.TMSFMXNativeMKMapView1GetDirections(Sender: TObject;
  AResponse: TTMSFMXNativeMKDirectionsResponse);
var
  r: Integer;
  pl: TTMSFMXNativeMKOverlay;
begin
  TMSFMXNativeMKMapView1.BeginUpdate;
  for r := 0 to Length(AResponse.Routes) - 1 do
  begin
    pl := TMSFMXNativeMKMapView1.AddPolyline(AResponse.Routes[r].Locations);
    pl.LineOpacity := 0.75;
    if r = 0 then
      pl.LineColor := TAlphaColorRec.Red
    else if r = 1 then
      pl.LineColor := TAlphaColorRec.Blue
    else if r = 2 then
      pl.LineColor := TAlphaColorRec.Purple;
  end;
  TMSFMXNativeMKMapView1.EndUpdate;
end;
This gives the following result:

ttmsfmxnativemkmapview4

Tiles (iOS 7 or later)

The MapView also supports the MKTileOverlay, which implements an overlay that is optimized for covering an area of the map using individual bitmap tiles. The bitmap tiles are provided by a server through a specific URL. Below is a sample before and after applying Google Maps and OpenStreetMap tiles with their specific formatted URL’s. 

procedure TForm1.TMSFMXNativeUIButton1Click(Sender: TObject);
begin
  TMSFMXNativeMKMapView1.BeginUpdate; 
  TMSFMXNativeMKMapView1.AddTiling('http://mt1.google.com/vt/lyrs=m@110&hl=pl&x={x}&y={y}&z={z}');
  TMSFMXNativeMKMapView1.EndUpdate;
end;

procedure TForm1.TMSFMXNativeUIButton2Click(Sender: TObject);
begin
  TMSFMXNativeMKMapView2.BeginUpdate;
  TMSFMXNativeMKMapView2.AddTiling('http://tile.openstreetmap.org/{z}/{x}/{y}.png');
  TMSFMXNativeMKMapView2.EndUpdate;
end;
ttmsfmxnativemkmapview5

ttmsfmxnativemkmapview6

Image overlay (iOS 7 or later)

When a specific area needs to be marked, you can add an image that is added on top of the map, bounded by a topleft and bottomright coordinate. Below is a sample that adds an image (added through the deployment window in your project) and renders it at the specific topleft and bottomright coordinate. It also centers and zooms the map on a specific coordinate to visualize the image.

TMSFMXNativeMKMapView1.BeginUpdate;
tl := MakeMapLocation(34.4311, -118.6012);
tr := MakeMapLocation(34.4311, -118.5912);
bl := MakeMapLocation(34.4194, -118.6012);
br := MakeMapLocation(34.4194, -118.5912);
mr := MakeMapLocation(34.4248, -118.5971);
splat := Abs(br.Latitude - tl.Latitude);
splon := Abs(br.Longitude - tl.Longitude);
rgn.Center.Latitude := mr.Latitude;
rgn.Center.Longitude := mr.Longitude;
rgn.Span.latitudeDelta := splat;
rgn.Span.longitudeDelta := splon;
TMSFMXNativeMKMapView1.SetRegion(rgn, True);
TMSFMXNativeMKMapView1.AddImage(ExtractFilePath(ParamStr(0)) + 'overlay_park.png', tl, br);
TMSFMXNativeMKMapView1.MapType := mtMapTypeHybrid;
TMSFMXNativeMKMapView1.EndUpdate;
The result of the code is shown in the screen below, with and without the image to demonstrate the difference. Comment out the line TMSFMXNativeMKMapView1.MapType := mtMapTypeHybrid; to have a better view of the added image.
ttmsfmxnativemkmapview7 ttmsfmxnativemkmapview8