Table of Contents

TMS FNC Google Maps Guides

Use TTMSFNCGoogleMaps when the application needs Google Maps JavaScript API features from the TMS FNC Maps component model. The component supports the shared map workflows, including markers, labels, shapes, popups, and events, while exposing Google-specific features such as KML layers, Street View, marker clustering, heat maps, overlay views, map styling, and keyboard shortcut control. The examples below assume a TTMSFNCGoogleMaps named TMSFNCGoogleMaps1 is already on the form and has a valid APIKey.

Labels And Keyboard Shortcuts

The Labels collection is accessible on Google Maps the same way it is on the shared map control. Use labels for persistent text that should remain anchored to a coordinate without becoming a marker popup. Options.ShowKeyboardShortcuts controls whether Google Maps keyboard shortcuts remain active, which is useful when the map shares focus with editors, grids, or shortcut-heavy application screens.

procedure TForm1.ConfigureGoogleMapsLabels;
var
  LLabel: TTMSFNCMapsLabel;
begin
  TMSFNCGoogleMaps1.Options.ShowKeyboardShortcuts := False;
  TMSFNCGoogleMaps1.Labels.Clear;

  LLabel := TMSFNCGoogleMaps1.Labels.Add;
  LLabel.Coordinate.Latitude := 51.5074;
  LLabel.Coordinate.Longitude := -0.1278;
  LLabel.Text := 'Operations hub';
  LLabel.BackgroundColor := gcWhite;
  LLabel.BorderColor := gcDodgerblue;
end;

Use visible labels sparingly on dense maps. For many points, prefer marker titles, clustering, or an overlay view that appears only for selected data.

KML Layers And Click Events

KML layers are useful when external systems publish route, region, or asset overlays as KML files. Use AddKMLLayer for runtime setup and pass ASuppressInfoWindows when the application owns the click response instead of using Google Maps' default KML info windows. OnKMLLayerClick receives the map event data for application-level inspection or context actions.

procedure TForm1.ConfigureGoogleMapsKMLLayer;
begin
  TMSFNCGoogleMaps1.ClearKMLLayers;
  TMSFNCGoogleMaps1.AddKMLLayer(
    'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml',
    True,
    True);
  TMSFNCGoogleMaps1.OnKMLLayerClick := TMSFNCGoogleMaps1KMLLayerClick;
end;

procedure TForm1.TMSFNCGoogleMaps1KMLLayerClick(Sender: TObject;
  AEventData: TTMSFNCMapsEventData);
begin
  { Inspect AEventData.ID or AEventData.Coordinate and show your own detail UI. }
end;

The KML URL must be reachable by the embedded browser and accepted by Google Maps. If a KML layer is private or generated on demand, expose it through a URL that the map runtime can fetch.

Street View Coordinate And State Events

Options.StreetView controls whether the Google Street View panorama is shown and how its location is chosen. Set Location to slCoordinate when the panorama must open at a known coordinate, then assign Coordinate, Heading, Pitch, and Zoom. Use OnStreetViewEnabledChange when UI outside the map needs to react to the user entering or leaving Street View.

procedure TForm1.ConfigureGoogleMapsStreetView;
begin
  TMSFNCGoogleMaps1.Options.ShowStreetViewControl := True;
  TMSFNCGoogleMaps1.Options.StreetView.Location := slCoordinate;
  TMSFNCGoogleMaps1.Options.StreetView.Coordinate.Latitude := 40.6892;
  TMSFNCGoogleMaps1.Options.StreetView.Coordinate.Longitude := -74.0445;
  TMSFNCGoogleMaps1.Options.StreetView.Heading := 120;
  TMSFNCGoogleMaps1.Options.StreetView.Pitch := 0;
  TMSFNCGoogleMaps1.Options.StreetView.Zoom := 1;
  TMSFNCGoogleMaps1.Options.StreetView.Enabled := True;
  TMSFNCGoogleMaps1.OnStreetViewEnabledChange :=
    TMSFNCGoogleMaps1StreetViewEnabledChange;
end;

procedure TForm1.TMSFNCGoogleMaps1StreetViewEnabledChange(Sender: TObject;
  AEventData: TTMSFNCMapsEventData;
  AStreetViewData: TTMSFNCGoogleMapsStreetViewData);
begin
  { Use AStreetViewData.Enabled to synchronize external UI state. }
end;

Street View availability depends on Google coverage at the requested coordinate. Keep a normal map fallback available when Google cannot return a panorama for the selected location.

Heat Maps And Overlay Views

Heat maps show density while preserving the underlying Google basemap. Populate HeatMaps with weighted coordinates and use opacity or gradient colors to keep the overlay readable. Overlay views are different: they place custom HTML over a coordinate or bounds region, which is useful for rich callouts, badges, images, or status panels that need more layout control than a marker title.

procedure TForm1.ConfigureGoogleMapsHeatMapAndOverlayView;
var
  LHeatMap: TTMSFNCGoogleMapsHeatMap;
  LWeightedCoordinate: TTMSFNCMapsWeightedCoordinate;
  LOverlayView: TTMSFNCGoogleMapsOverlayView;
begin
  TMSFNCGoogleMaps1.ClearHeatMaps;
  TMSFNCGoogleMaps1.ClearOverlayViews;

  LHeatMap := TMSFNCGoogleMaps1.HeatMaps.Add;
  LHeatMap.Opacity := 0.55;
  LHeatMap.GradientStartColor := gcGreen;
  LHeatMap.GradientMidColor := gcYellow;
  LHeatMap.GradientEndColor := gcRed;

  LWeightedCoordinate := LHeatMap.WeightedCoordinates.Add;
  LWeightedCoordinate.Coordinate.Latitude := 34.0522;
  LWeightedCoordinate.Coordinate.Longitude := -118.2437;
  LWeightedCoordinate.Weight := 0.85;

  LOverlayView := TMSFNCGoogleMaps1.AddOverlayView;
  LOverlayView.Mode := omCoordinate;
  LOverlayView.Coordinate.Latitude := 34.0522;
  LOverlayView.Coordinate.Longitude := -118.2437;
  LOverlayView.CoordinatePosition := cpBottomCenter;
  LOverlayView.Text := '<strong>High activity</strong>';
  LOverlayView.Width := 160;
  LOverlayView.Clickable := True;
end;

Use heat maps for aggregate intensity and overlay views for selected, explainable content. Overlay views can consume pointer events, so keep Clickable aligned with the interaction you want users to have.

Marker Clustering

Marker clustering keeps dense point sets readable by grouping nearby markers through Google Maps' MarkerClusterer-backed rendering. Add a TTMSFNCGoogleMapsCluster, tune MinimumNumberOfMarkers, MaxZoom, and ZoomOnClick, then assign markers to the cluster and the cluster marker list.

procedure TForm1.ConfigureGoogleMapsClusters;
var
  LCluster: TTMSFNCGoogleMapsCluster;
  LMarker: TTMSFNCGoogleMapsMarker;
begin
  TMSFNCGoogleMaps1.Markers.Clear;
  TMSFNCGoogleMaps1.Clusters.Clear;

  LCluster := TMSFNCGoogleMaps1.Clusters.Add;
  LCluster.Title := 'Regional offices';
  LCluster.MinimumNumberOfMarkers := 2;
  LCluster.MaxZoom := 12;
  LCluster.ZoomOnClick := True;
  LCluster.ImagePath := 'images/google-cluster.png';

  LMarker := TMSFNCGoogleMaps1.Markers.Add;
  LMarker.Coordinate.Latitude := 48.8566;
  LMarker.Coordinate.Longitude := 2.3522;
  LMarker.Title := 'Paris office';
  LMarker.Cluster := LCluster;
  LCluster.Markers.Add(LMarker);

  LMarker := TMSFNCGoogleMaps1.Markers.Add;
  LMarker.Coordinate.Latitude := 50.8503;
  LMarker.Coordinate.Longitude := 4.3517;
  LMarker.Title := 'Brussels office';
  LMarker.Cluster := LCluster;
  LCluster.Markers.Add(LMarker);
end;

Clusters should be rebuilt when you change the marker set or cluster styling after the map has already rendered. Use Clusters.Recreate when the current cluster instances need to be regenerated.

Complex Polygons

Complex polygons use polygon holes to represent areas such as service territories with excluded islands, building footprints with courtyards, or administrative regions that omit protected zones. Add the outer polygon with AddPolygon, then add each inner ring with AddHole.

procedure TForm1.AddGoogleMapsComplexPolygon;
var
  LOuter: TTMSFNCMapsCoordinateRecArray;
  LInner: TTMSFNCMapsCoordinateRecArray;
  LPolygon: TTMSFNCGoogleMapsPolygon;
begin
  SetLength(LOuter, 4);
  LOuter[0].Latitude := 37.782;
  LOuter[0].Longitude := -122.447;
  LOuter[1].Latitude := 37.782;
  LOuter[1].Longitude := -122.425;
  LOuter[2].Latitude := 37.768;
  LOuter[2].Longitude := -122.425;
  LOuter[3].Latitude := 37.768;
  LOuter[3].Longitude := -122.447;

  SetLength(LInner, 4);
  LInner[0].Latitude := 37.778;
  LInner[0].Longitude := -122.441;
  LInner[1].Latitude := 37.778;
  LInner[1].Longitude := -122.431;
  LInner[2].Latitude := 37.772;
  LInner[2].Longitude := -122.431;
  LInner[3].Latitude := 37.772;
  LInner[3].Longitude := -122.441;

  LPolygon := TMSFNCGoogleMaps1.AddPolygon(LOuter, True);
  LPolygon.FillColor := gcDodgerblue;
  LPolygon.FillOpacity := 0.35;
  LPolygon.StrokeColor := gcNavy;
  LPolygon.AddHole(LInner);
end;

Keep outer and inner rings in a consistent coordinate order. When importing polygon data from GeoJSON or another source, verify that the hole coordinates describe only the excluded area and do not cross the outer boundary.

Combined Google Maps Setup

Most production screens combine several Google-specific features: API options, labels, clusters, KML, heat maps, and event wiring. Group setup in an update block so the component can apply the final state without repainting after every individual property assignment.

procedure TForm1.BuildGoogleMapsOperationsScene;
var
  LCluster: TTMSFNCGoogleMapsCluster;
  LMarker: TTMSFNCGoogleMapsMarker;
  LHeatMap: TTMSFNCGoogleMapsHeatMap;
  LWeightedCoordinate: TTMSFNCMapsWeightedCoordinate;
begin
  TMSFNCGoogleMaps1.BeginUpdate;
  try
    TMSFNCGoogleMaps1.APIKey := '<your Google Maps JavaScript API key>';
    TMSFNCGoogleMaps1.Options.ShowKeyboardShortcuts := False;
    TMSFNCGoogleMaps1.Options.StreetView.Location := slCoordinate;
    TMSFNCGoogleMaps1.Options.StreetView.Coordinate.Latitude := 52.52;
    TMSFNCGoogleMaps1.Options.StreetView.Coordinate.Longitude := 13.405;

    TMSFNCGoogleMaps1.AddKMLLayer(
      'https://developers.google.com/maps/documentation/javascript/examples/kml/westcampus.kml',
      True,
      True);

    LCluster := TMSFNCGoogleMaps1.Clusters.Add;
    LCluster.Title := 'Operations markers';
    LCluster.MinimumNumberOfMarkers := 2;
    LCluster.ZoomOnClick := True;

    LMarker := TMSFNCGoogleMaps1.Markers.Add;
    LMarker.Coordinate.Latitude := 52.52;
    LMarker.Coordinate.Longitude := 13.405;
    LMarker.Title := 'Berlin depot';
    LMarker.Cluster := LCluster;
    LCluster.Markers.Add(LMarker);

    TMSFNCGoogleMaps1.AddLabel(52.52, 13.405, 'Berlin depot', gcWhite, gcDarkgreen);

    LHeatMap := TMSFNCGoogleMaps1.HeatMaps.Add;
    LHeatMap.Opacity := 0.45;
    LWeightedCoordinate := LHeatMap.WeightedCoordinates.Add;
    LWeightedCoordinate.Coordinate.Latitude := 52.52;
    LWeightedCoordinate.Coordinate.Longitude := 13.405;
    LWeightedCoordinate.Weight := 0.8;

    TMSFNCGoogleMaps1.OnKMLLayerClick := TMSFNCGoogleMaps1KMLLayerClick;
    TMSFNCGoogleMaps1.OnStreetViewEnabledChange :=
      TMSFNCGoogleMaps1StreetViewEnabledChange;
  finally
    TMSFNCGoogleMaps1.EndUpdate;
  end;
end;

Split this combined pattern when users can toggle overlays at runtime, but keep API key assignment and option setup close to the map initialization path.

Common Pitfalls

  • Assign APIKey before adding Google-specific overlays or Street View options.
  • Use AddKMLLayer when you need SuppressInfoWindows; the KML item exposes those values through the overload rather than writable published properties.
  • Disable Options.ShowKeyboardShortcuts when the map sits inside a shortcut-heavy application screen.
  • Check Street View availability for the requested coordinate and keep a map fallback.
  • Recreate clusters after substantial marker or cluster styling changes.
  • Keep heat map weights consistent across refreshes so colors remain meaningful.

See Also