Map Components for Delphi – documentation (EN)

Wersja polska · help site: https://help.imetroll.com/

Map components for RAD Studio 12 Athens (VCL and FireMonkey) built on MapLibre GL JS: raster tile maps, 3D vector maps served by our own server, an appearance editor, GeoJSON areas (world → continents → countries) and pluggable address-search providers.

Status: written for RAD Studio 12, not yet compiled in Delphi. Unit tests of the framework-neutral parts pass under FPC 3.2 (tests/fpc/run_fpc_check.py). Please report compile errors with the line number.

Contents

1. Components
2. Installation
3. Quick start
4. Tile maps TTileMapVCL / TTileMapFMX
5. 3D maps T3DMapVCL / T3DMapFMX
6. Zero point, main marker, radius
7. Navigation buttons
8. Address search and providers
9. Area selection and search inside an area
10. TEditMap – appearance of the 3D map
11. TMapAreas – world, continents, countries
12. TEditMapRaster – raster tiles
13. DEM terrain and elevation (T3DTerrain / T3DMap.Terrain)
    • 13a. TWeather – weather on the map
14. Reference
15. Recipes
16. Migrating from the previous version
17. Limitations and open issues
18. Troubleshooting

1. Components

Palette page: Maps.

One shared core (MapCommon.Core) drives all four maps, so they have the same properties, methods and events. The 3D maps add 2D/3D mode, theme and EditMap.

2. Installation

1. Open MapComponents.groupproj.
2. Build MapComponentsRT, MapComponentsVCL, MapComponentsFMX.
3. Install MapComponentsDsgn (Win32, design-time). The components appear on the Maps palette page.
4. Add Source to the Library path or the project search path (the demos compile from source).
5. Windows: copy WebView2Loader.dll of the matching bitness ($(BDS)\Redist\win32 or win64) next to the EXE. The WebView2 Runtime is required (preinstalled on Windows 10/11).

Demos (Demos): DemoTileVCL (tiles, zero point, radius, area), Demo3DVCL (3D + TEditMap), DemoAreasVCL (TMapAreas), Demo3DTerritoryVCL / Demo3DTerritoryFMX (DEM + provinces), DemoSearchVCL (providers), DemoFMX (FMX: tiles + areas, 3D + editor).

3. Quick start

Drop a TTileMapVCL (or TTileMapFMX) on a form, set Align = alClient and run. A TNominatimSearchProvider, TMapAreas or TEditMap on the same form is linked automatically to the empty SearchProvider, Areas, EditMap property (AutoLinkComponents = True).

uses MapCommon.Types, MapCommon.MapVCL;

procedure TForm1.FormCreate(Sender: TObject);
begin
  TileMap1.Style := tmsOpenStreetMap;     // tmsSatellite, tmsTerrain
  TileMap1.ZeroLat := 52.2297;            // zero point (Home button)
  TileMap1.ZeroLon := 21.0122;
  TileMap1.Zoom := 13;
  TileMap1.SearchToken := GetEnvironmentVariable('MAP_SEARCH_TOKEN');
end;

uses MapCommon.Types, MapCommon.MapFMX;

procedure TForm1.FormCreate(Sender: TObject);
begin
  TileMap1.Style := tmsOpenStreetMap;
  TileMap1.ZeroLat := 52.2297;
  TileMap1.ZeroLon := 21.0122;
  TileMap1.Zoom := 13;
  TileMap1.SearchToken := GetEnvironmentVariable('MAP_SEARCH_TOKEN');
end;

4. Tile maps TTileMapVCL / TTileMapFMX

The style is picked from an enum (Style: TTileMapStyle). Tile URLs are not in the Object Inspector: an own source is set in code only (CustomTileURL, CustomAttribution, CustomTileMaxZoom) together with Style := tmsCustom.

Tile terms of use (important for deployment):

• OpenStreetMap (tile.openstreetmap.org): the OSMF Tile Usage Policy applies – donation-funded servers without SLA; bulk downloading (prefetch, offline) is forbidden, an identifying User-Agent/Referer and visible attribution are required. For heavy traffic use a commercial provider or your own tile server (tmsCustom).
• Esri World Imagery: without an API key only limited use is allowed (per Esri terms, essentially non-commercial); commercial use needs an ArcGIS account/licence. Esri attribution is mandatory.
• OpenTopoMap: OSM + SRTM data, CC-BY-SA style; a private service with limited capacity – not suitable for heavy production traffic.

5. 3D maps T3DMapVCL / T3DMapFMX

Vector map with tiles from mapa.imetroll.com (style liberty, 111 layers). Everything the tile maps have plus 2D/3D mode, pitch, 3D buildings and a day/night theme. Colours are not edited in the map itself – use a TEditMap linked through EditMap.

Map3D.Style := m3sVector;             // own 3D vector tiles (mapa.imetroll.com)
Map3D.Mode := mm3D;                   // or Map3D.ToggleMode
Map3D.Pitch3D := 55;
Map3D.Theme := mtNight;
Map3D.Buildings3D := True;
// a style saved on the map server:
Map3D.ServerStyleName := 'moj-styl';
Map3D.Style := m3sServerStyle;
// custom URL - code only (public, not in the Object Inspector):
Map3D.CustomStyleURL := 'https://example.com/style.json';
Map3D.Style := m3sCustom;

StyleURL is no longer published. The only URLs left in the Object Inspector are BoundariesURL (a boundaries data source, not a style) and SearchProviderURL (fallback search address).

6. Zero point, main marker, radius

The zero point (ZeroLat, ZeroLon, default Warsaw 52.2297, 21.0122) is the reference point: the Home button flies there (HomeUsesZeroPoint) and distances are measured from it (MainMarkerDistanceFromZero, MainMarkerBearingFromZero, MainMarkerPixelOffsetFromZero – the same pixel maths as the old OSMMapViewer). It may have its own icon (ZeroIcon).

Main marker – source MainMarkerSource:

Own image: MainMarkerIcon (TPicture in VCL, TBitmap in FMX; sent as a PNG data URL). Without an image a dot is drawn (MainMarkerColor, MainMarkerBorderColor, MainMarkerSize, MainMarkerSquare, pulse PulseEnabled/PulseColor).

Map.ZeroLat := 52.2297;
Map.ZeroLon := 21.0122;
Map.ZeroPointVisible := True;
Map.ZeroIcon.LoadFromFile('zero.png');          // TPicture (VCL) / TBitmap (FMX)
Map.MainMarkerSource := mmsDeviceLocation;      // GPS, falls back to the zero point
Map.MainMarkerIcon.LoadFromFile('pin.png');     // own image instead of the dot
Map.MainMarkerIconWidth := 32;
Map.MainMarkerIconHeight := 40;
Map.PulseEnabled := True;
ShowMessage(Format('%.0f m od punktu zerowego', [Map.MainMarkerDistanceFromZero]));

Radius – a circle around the main marker, the zero point or any point, with fill and outline colours and opacity:

Map.RadiusCenter := rcMainMarker;
Map.RadiusMeters := 1500;
Map.RadiusColor := clRed;                // VCL TColor / FMX TAlphaColor
Map.RadiusFillOpacity := 0.12;
Map.RadiusLineColor := clMaroon;
Map.RadiusLineOpacity := 0.9;
Map.RadiusLineWidth := 2;
Map.RadiusLineStyle := mlsDashed;
Map.RadiusLabel := '1,5 km';
Map.RadiusVisible := True;

7. Navigation buttons

Button panel (NavVisible, NavPosition, NavOrientation, NavButtonSize) with the NavButtons collection. Each button has Kind, Visible, Hint, Icon (own icon) and Action.

Every click raises OnNavButtonClick(Kind); with Action = nbaEventOnly only the event runs.

// own icon and hint for a built-in button
with Map.NavButtons.Find(nbkHome) do
begin
  Icon.LoadFromFile('home.png');
  Hint := 'Wróć do punktu zerowego';
end;
// hide a button
Map.NavButtons.Find(nbkStyle).Visible := False;
// only the event, no built-in action
Map.NavButtons.Find(nbkMyLocation).Action := nbaEventOnly;
Map.NavPosition := bppTopRight;
Map.NavOrientation := bpoHorizontal;

8. Address search and providers

The map searches through the component in SearchProvider (linked automatically when it is on the form). When empty, an internal TNominatimSearchProvider with SearchProviderURL (default https://geoloc.imetroll.com) and SearchToken (never stored in the DFM) is used.

Pre-flight validation: missing token, bad token format, invalid URL, /status probe on first use (result in LastCheck*), HTTP error classification. Errors go to OnSearchError with a TMapProviderErrorKind and a PL/EN message:

// drop TNominatimSearchProvider on the form: every map links it automatically
NominatimSearchProvider1.BaseURL := 'https://geoloc.imetroll.com';
NominatimSearchProvider1.Token := GetEnvironmentVariable('MAP_SEARCH_TOKEN');
NominatimSearchProvider1.Language := 'pl';
NominatimSearchProvider1.CountryCodes := 'pl';
NominatimSearchProvider1.CheckConnection(
  procedure(Ok: Boolean; ErrorKind: TMapProviderErrorKind; const ErrorMessage, StatusJSON: string)
  begin
    if not Ok then
      ShowMessage(ErrorMessage);         // e.g. pekInvalidToken: "Token odrzucony (403)"
  end);
// any JSON geocoder
CustomUrlSearchProvider1.SearchURL := 'https://photon.komoot.io/api/?q={query}&limit={limit}&lang={lang}';
TileMap1.SearchProvider := CustomUrlSearchProvider1;

Usage policy and data licence. Results come from OpenStreetMap – licence ODbL: the app must show "© OpenStreetMap contributors", and derived databases you share are share-alike. The public nominatim.openstreetmap.org server has its own policy (max. 1 request/s for the whole application, identifying User-Agent, no autocomplete or systematic queries, caching required). The component uses our own geoloc.imetroll.com gateway by default, but the address is configurable – per the OSMF policy it must be changeable without a software update. Enable SearchLive (search while typing) only on your own server.

Client-side rate limit. TNominatimSearchProvider.MinRequestIntervalMs (default 1000 ms) queues requests so the provider sends at most one HTTP request per second (the /status probe counts too) – nothing is dropped, later results simply arrive later. After a 429 response (pekRateLimited, OnError event) the next request waits RateLimitBackoffMs (default 10000 ms). For TCustomUrlSearchProvider the limit is off by default (0).

9. Area selection and search inside an area

AreaShape = masRectangle, masPolygon or masCircle. Selection starts with the nbkSelectArea button or StartAreaSelection. Afterwards: OnAreaSelected(Area), HasArea, Area. SearchInArea(Query) searches inside the area (viewbox + point-in-polygon filter); with SearchOnAreaSelected = True the AreaSearchQuery runs automatically.

Map.AreaShape := masPolygon;             // masRectangle, masCircle
Map.StartAreaSelection;                  // or the "select area" button
// ...
procedure TForm1.MapAreaSelected(Sender: TObject; const Area: TMapArea);
begin
  Map.SearchInArea('hydraulik');         // results -> OnSearchResults
end;

10. TEditMap – appearance of the 3D map

Edit / Edit3D inheritance (like InfoWindow): Edit = TEditMapRaster (2D/raster, Areas popup); Edit3D = TEditMap / TEdit3DMap (3D + terrain). Properties: TileMap.Edit, Map3D.Edit3D (alias EditMap), Areas.Edit, Terrain.Edit3D. See docs/TEDIT_INHERITANCE_REQUIREMENTS.md.

TEditMap (the name TEdit3DMap works in code too) holds appearance changes of the 111 style layers: colour, opacity, visibility, line width and per-zoom values. Changes are applied live on every linked map (T3DMapVCL.EditMap, T3DMapFMX.EditMap) and again after every style load and page reload.

• editing: SetColor, SetPaintColor, SetOpacity, SetVisible, SetWidth, SetZoomStops, SetValueJSON, SetCategoryColor, SetCategoryVisible; reading Get*;
• BeginUpdate/EndUpdate – several changes as one undo step;
• Undo, Redo, CanUndo, CanRedo, UndoLimit;
• RestoreDefaults – back to DefaultSettingsFile (if valid) or the factory look; undoable, raises OnRestoreDefaults;
• files: SettingsFile (loaded at start when AutoLoad = True), LoadFromFile, SaveToFile, LoadFromJSON, SaveToJSON, ShowOpenDialog, ShowSaveDialog;
• server: SaveToServer(Name, Password) (base style + changes → styles_api.php), LoadFromServer;
• editor window: ShowEditor (category/layer tree, colour, opacity, width, visibility, Undo/Redo, Przywróć domyślne = restore defaults, load/save JSON).

In the IDE SettingsFile and DefaultSettingsFile have a "…" button with a *.json dialog; double-click opens the editor, the context menu has "Przywróć domyślne". Settings are not stored in the DFM – the editor offers to save them to SettingsFile.

An invalid file (bad JSON, unknown layer, bad colour, opacity outside 0..1) is not applied; the error list goes to OnValidationError and LastErrors.

// T3DMapVCL1.EditMap := EditMap1 (automatic at design time)
EditMap1.SetColor('water', '#1a3a6b');
EditMap1.BeginUpdate;                    // one undo step
try
  EditMap1.SetColor('road_trunk_primary', '#ff9800');
  EditMap1.SetWidth('road_trunk_primary', 6);
  EditMap1.SetOpacity('road_trunk_primary', 0.9);
finally
  EditMap1.EndUpdate;
end;
EditMap1.SetCategoryVisible('etykiety', False);
EditMap1.Undo;
EditMap1.RestoreDefaults;                // undoable, OnRestoreDefaults
EditMap1.SaveToFile('map-settings.json');
EditMap1.ShowEditor;                     // window: tree, colour, opacity, width, undo/redo

EditMap1.SaveToServer('moj-styl', Password);   // asynchronous, OnSaved
// later, in any application:
T3DMapVCL1.ServerStyleName := 'moj-styl';
T3DMapVCL1.Style := m3sServerStyle;

procedure TForm1.EditMap1ValidationError(Sender: TObject; const Source: string; Errors: TStrings);
begin
  Memo1.Lines.Add('Plik ustawień odrzucony (' + Source + '):');
  Memo1.Lines.AddStrings(Errors);        // e.g. "layers.water.color: not a colour"
end;

Layer categories (SetCategoryColor, SetCategoryVisible): tlo (background), teren (land use), zielen (green), woda (water), lotniska (airports), tunele (tunnels), drogi (roads), mosty (bridges), kolej (rail), budynki (buildings), obiekty (facilities), granice (boundaries), poi, etykiety (labels), inne (other). Names and descriptions of all 111 layers: MapCommon.LayerInfo (MAP_LAYER_CATEGORIES, MAP_LAYERS).

11. TMapAreas – world, continents, countries

Area edit on the map (RMB / long-press): right-click and, on mobile, long-press (~500 ms, cancelled on move) open the same feature style editor: fill colour, border colour/width, editable centre label (colour, font size). Property EditPopupEnabled (default True) disables that popup — then neither RMB nor long-press opens it. Page bridge command: setAreasEditEnabled ({"enabled":false}).

Areas1.EditPopupEnabled := False;   // disable edit popup (e.g. read-only mode)
Areas1.EditPopupEnabled := True;    // RMB + long-press open the editor again

Requirement (2026-10-05): after selecting a country on the list, its administrative units appear (e.g. voivodeships in Poland, US states; similarly for other countries).

TMapAreas shows GeoJSON areas on every linked map (Areas). Selection is hierarchical:

WholeWorld = True          → whole world: countries.geojson (258 countries)
                             (WorldDetail = mwdProvinces → admin-1 regions of the world)
WholeWorld = False
  Continents = [ ... ]     → one *_full.geojson file per checked continent,
                             with country outlines and regions (ShowCountryOutlines / ShowRegions)
  Countries = 'PL,DE,CZ'   → optional country filter (ISO alpha-2 or alpha-3);
                             with an empty Continents the continents follow from the countries

Continents is a set (TMapAreaContinents) – in the Object Inspector every continent has its own check box, and the "…" button opens the World › continents › countries tree with check boxes (the same window opens from "…" at Countries and by double-clicking the component). Checking a continent checks all its countries; checking only some countries stores them in Countries.

The continents (TMapAreaContinent) match the files on the server – hence a separate Central America and no Antarctica (it is only in the world file, WholeWorld). The TMapContinent enum (mcAuto, mcEurope …) in MapCommon.Types is for search routing, not for area files.

Files on the server – https://mapa.imetroll.com/geojson/ (version in versiongeojson.json, updated 2026-07-28):

Delphi downloads the files (background thread, Timeout), stores them in CacheFolder (default <cache>\MapComponents\geojson) and refreshes them when versiongeojson.json changes (CheckVersion). Offline, the cached copy is used. Data goes to the page in 256 KB chunks, so the server needs no CORS.

MapAreas1.WholeWorld := True;            // countries.geojson (258 countries)
MapAreas1.WorldDetail := mwdCountries;   // mwdProvinces = admin-1 regions of the world

MapAreas1.WholeWorld := False;
MapAreas1.Continents := [macEurope, macAfrica];   // europe_full + africa_full
MapAreas1.ShowCountryOutlines := True;
MapAreas1.ShowRegions := True;                    // admin-1 regions inside the countries

MapAreas1.BeginUpdate;                   // one reload
try
  MapAreas1.Continents := [];            // derived from the countries
  MapAreas1.Countries := 'PL,CZ,SK';
finally
  MapAreas1.EndUpdate;
end;
MapAreas1.ShowCountry('PL');             // filter + zoom

Events: OnAreaClick / OnAreaHover (HoverEvents) with the ISO country code, name and all feature properties, OnAreaLoaded (feature count or error), OnValidationError (e.g. unknown country code, a file that is not GeoJSON, swapped coordinates).

procedure TForm1.MapAreas1AreaClick(Sender: TObject; const SetId: string;
  const Lat, Lon: Double; const CountryISO2, FeatureName, PropertiesJSON: string);
begin
  Caption := FeatureName + ' (' + CountryISO2 + ')';
end;

Own files: the Items collection (path or URL, Countries, Style) and LoadFromFile, LoadFromURL, LoadFromString; hierarchy look – HierarchyStyle (CSS colours, opacity, line width and style, hover, labels LabelProperty e.g. name_pl, zoom range).

Item := MapAreas1.LoadFromFile('C:\dane\strefy.geojson', 'Strefy dostaw');
Item.Style.FillColor := '#2e7d32';
Item.Style.FillOpacity := 0.2;
MapAreas1.FitToArea(Item);

Administrative boundaries (ShowAdministrative + AdminLevel)

On the map server (https://mapa.imetroll.com/geojson/):

Areas1.ShowAdministrative := True;
Areas1.AdminLevel := malAdmin1;
Areas1.Countries := 'PL';   // Poland -> 16 voivodeships
Areas1.ShowAdministrativeCountry('PL', malAdmin1);

Per-level style: CountryStyle, Admin1Style, Admin2Style.

Country + borders inside: with AdminLevel = malAdmin1 (and malAdmin2) the map shows the country outline (CountryStyle, drawn on top, at least 1 px wider) and the admin unit borders inside it (Admin1Style: own colour / width / LineStyle). Every voivodeship is its own area (hover, OnAreaClick); the country outline that contains units does not cover them with its fill or hit-test. Zoom ladder = the styles' MinZoom/MaxZoom windows (the same ones TWeather uses): outside the Admin1Style window only the country is shown / selectable, inside it the voivodeships.

Areas1.ShowAdministrativeCountry('PL');      // Poland + 16 voivodeships
Areas1.CountryStyle.LineColor := '#1A237E';  // country outline
Areas1.Admin1Style.LineColor := '#7E57C2';   // voivodeship borders
Areas1.Admin1Style.MinZoom := 3.5;           // below 3.5: country only

Persisting editor settings (SettingsFile / AutoSave / AutoLoad)

JSON format map-areas-settings v1 (same idea as TEditMap). The HTML page also mirrors set options into localStorage. A server/DB endpoint is optional (same pattern as TEditMap.SaveToServer).

12. TEditMapRaster – raster tiles {#editmapraster}

Links to TTileMapVCL / TTileMapFMX via Map (FreeNotification + AutoDetect).

• Pixel editing (PaintMode): paint / crop / opacity on the tile canvas; results go to IndexedDB and an SQLite MBTiles-like store (modified flag).
• Optional proxy: tools/server/tile_proxy.py (or .php) — not deployed with the packages; see tools/server/README.md (OSM policy; do not proxy Google/Apple). The upstream URL and API key stay on the server (TILE_UPSTREAM, TILE_APIKEY); uploading edited tiles requires TILE_TOKEN. With ProxyURL set, tiles are requested as <ProxyURL>/tile/{z}/{x}/{y}.png.
• Styling: CSS filter + MapLibre raster paint + optional colour map; built-ins neutral, google-like, apple-like, night + custom JSON; switch at runtime without reload. ApiKey is appended through {apikey} in UrlTemplate. RefreshTile(z,x,y) busts caches.

13. DEM terrain and elevation (T3DTerrain / T3DMap.Terrain) {#terrain}

Palette component T3DTerrain (MapCommon.Terrain, RT package, Maps palette) and the nested Terrain property on T3DMapVCL / T3DMapFMX (MapLibre raster-dem + setTerrain) show real elevation in metres above sea level worldwide. With Enabled the 3D map rises with the DEM; “Show heights” (ShowElevation) reads elevation under the cursor / click (OnElevation) and can mark spots (ShowElevationSpots). Satellite hybrid m3sSatelliteHybrid on 3D maps is kept.

T3DTerrain – linking (auto-link)

When T3DTerrain is linked to a 3D map (and optionally TEditMap), 3D terrain turns on automatically (Enabled := True + ApplyToMap). Nested T3DMap*.Terrain still works without a separate component.

Standalone view: T3DTerrainVCL / T3DTerrainFMX (Maps palette) are 3D maps with terrain defaults (EditSubjectKind = eskTerrain) — TEditMap can attach without a separate T3DMap*. With both on the form, one TEditMap is enough: EditSubject switches map-layer editing (eskMapLayers) vs terrain options (eskTerrain); SetTerrainContourLines / SetTerrainElevationLabels / SetTerrainHillshade / SetTerrainObjectElevation toggle overlays independently (labels only, lines only, both, or neither).

Elevation labels and contours are independent. Buildings and POIs stay on the DEM; with ShowObjectElevation a click reports ground / object height / roof (OnObjectElevation).

DEM source (Mapterhorn planet.pmtiles)

Default (MAP_DEM_DEFAULT_URL):

pmtiles://https://mapa.imetroll.com/terrain/planet.pmtiles

Mapterhorn archive (~331 GB, WebP 512 px, Terrarium, zoom 0–12), served with CORS and Range. MapLibre loads it as raster-dem via pmtiles:// (source url:, without appending /{z}/{x}/{y}). PMTiles JS (MAP_DEFAULT_PMTILES_JS / PMTilesJSURL) is injected automatically when SourceURL starts with pmtiles://.

• Tiles up to zoom ≤ 12 – planet.pmtiles (worldwide); above that MapLibre overzooms z12.
• Higher zooms – regional 6-x-y.pmtiles from the same Mapterhorn set.
• TileBuffer is for http(s) XYZ; with pmtiles:// set it to 0.

{ Preferred: palette component (auto-link + auto-enable) }
Terrain1.Map := Map3D;
Terrain1.EditMap := EditMap1;
Terrain1.Exaggeration := 1.5;
Terrain1.ShowElevation := True;

{ Or nested map property: }
Map3D.Terrain.SourceURL := MAP_DEM_DEFAULT_URL;  // no /{z}/{x}/{y}
Map3D.Terrain.Enabled := True;

Help page: T3DTerrain.

Live HTML demo: help.imetroll.com/demo/t3dterrain.html — the same map page the component uses, with Exaggeration / labels / contours / hillshade / object-elevation toggles and Tatras–Alps–Himalayas fly-tos.

Delphi demos: Demo3DTerritoryVCL, Demo3DTerritoryFMX.

13a. TWeather – weather middleware

TWeather is middleware only (not a chart module): builds GET to https://weather.imetroll.com/v1/forecast, appends key=, returns JSON via OnDataReady(JSON) / DataJSON. Require ApiKey. Fields include UV, wind speed+direction, feels-like, and insolation (sunshine_duration [s], shortwave_radiation [W/m²]). Map.WeatherInfo gates rendering; Display has icon+temp labels, DensityMode (admin = one widget per admin unit at polygon centroid; temp = sample mean; area icon is NOT a naive mean of WMO codes — binary states as powers of two (WBS_CLEAR=1, WBS_SUN=2, WBS_CLOUDS=4, WBS_RAIN=8), sum votes in the polygon (AreaBinaryVotes.SumBits), WinningBit assigns the icon; grid = MaxPoints/PointsPerAdmin; auto by zoom: country→admin1 count, zoom-in→denser, place→1), LabelDensity thin 0/1/2, WidgetStyle, CreateWidget / CreateWidgetsForAreas, WeatherClickMode ladder, motion, ScaleFactor/MinScreenWidth, custom PNGs. Roadmap 2c: precip/cloud gradients on 2D tiles; live 3D clouds + rain.

Votes := Weather1.Data.AreaBinaryVotes;
Icon := WeatherBinaryStateIcon(Votes.WinningBit, True,
  Weather1.Data.AverageCurrent(wpTemperature2m));
// AverageCurrent(wpWeatherCode) = winning-bit WMO (0/1/3/61), not mean(codes)

13b. TWeatherScene – weather app background animation

TWeatherScene (MapCommon.Weather.Scene, Maps palette) is a light background scene (day/night, clouds, rain, sun, wind, stars) behind info panels. It is not a map and does not call the weather server.

Presets: wspAuto … wspNightCloudy. Options: Animated, ShowStarsAtNight, IntensityScale, SoftClouds.

Properties: Weather, Host, AutoLinkComponents, Active, Preset, Options, IsDay, CloudCover, PrecipIntensity, WindDirectionDeg, WindSpeedMs, SunVisible, StarsVisible, Overcast. Public: LastSceneJSON, SceneJSON, ApplyJSON, ApplyFromWeather, RefreshHost, Clear, DetectLinkedComponents. Events: OnStateChanged. Link: Weather.Scene ↔ Scene.Weather (Scene never calls the weather server).

UI family (AutoLink to TWeather only)

Drop next to TWeather — they register via RegisterLinkedView and fill on OnDataReady (no GET):

Demo: https://help.imetroll.com/demo/tweather-area-popup.html

14. Reference

Tables are generated from the same spec as the code (tools/gen_components.py).

14.1 Common properties (all four maps)

Also: MainMarkerIcon, ZeroIcon (TPicture / TBitmap), NavButtons, SearchProvider, Areas, AutoLinkComponents; VCL: WebView2UserDataFolder, WebView2BrowserFolder, DevToolsEnabled, OpenLinksExternally; FMX: BridgeTransport.

14.2 Colours

14.3 3D maps only

Plus Style: TMap3DStyle and EditMap: TEditMap. Tile maps have Style: TTileMapStyle.

14.4 Public properties (code only)

CustomTileURL, CustomAttribution, CustomTileMaxZoom (tiles), CustomStyleURL (3D), Core, Browser, IsMapReady, View, MarkerCount, LastResults, Area, HasArea.

14.5 Events

3D maps only:

14.6 Methods

3D maps only:

Plus AddMarker(Id, Lat, Lon, Color, Title, PopupText) and AddMarker(Id, Lat, Lon, Icon, …), Reload, DetectLinkedComponents.

14.7 Full API of all components (generated from the code)

The tables below are generated from the declarations in Source/*.pas (tools/api_ref.py) – every published property and event (inherited ones included), public properties and public methods.

TTileMapVCL (MapCommon.MapVCL)

Published properties

Events

Public properties (code only)

Public methods

TTileMapFMX (MapCommon.MapFMX)

Published properties

Events

Public properties (code only)

Public methods

T3DMapVCL (MapCommon.MapVCL)

Published properties

Events

Public properties (code only)

Public methods

T3DMapFMX (MapCommon.MapFMX)

Published properties

Events

Public properties (code only)

Public methods

TEditMap (MapCommon.EditMap)

Published properties

Events

Public properties (code only)

Public methods

TEditMapRaster (MapCommon.EditMapRaster)

Published properties

Events

Public methods

TMapAreas (MapCommon.Areas)

Published properties

Events

Public properties (code only)

Public methods

TNominatimSearchProvider (MapCommon.Search)

Published properties