Mappe di Google
copia linkVediamo come funziona e si utilizza il componente Google Maps.
Il componente
Il componente Google Maps permette di utilizzare le funzionalità delle mappe di Google all’interno delle applicazioni realizzate con Instant Developer Foundation. I servizi forniti da Google sono gratuiti, ma con alcune limitazioni; prima di utilizzare questo componente occorre aver letto ed accettato i termini di utilizzo di Google.
Le funzionalità del componente sono le seguenti:
- Visualizzazione di mappe altamente configurabili all’interno delle proprie videate.
- Posizionamento di marker e poligoni sulle mappe.
- Notifica di eventi all’applicazione causati dall’interazione dell’utente.
- Geo-decodifica di indirizzi in coordinate geografiche e viceversa.
- Calcolo di percorsi (dalla versione 10.1 di Instant Developer).
- Gestione della chiave di abilitazione delle API di Google.
Integrazione in un progetto
L’integrazione è immediata: dopo aver importato il componente nel progetto utilizzando il file GoogleMaps.idz, per mostrare una mappa in una videata basta tirare la videata Mappa, presente nel componente, su un campo statico, in una tabbed view o su un frame vuoto.
Configurazione della mappa
Dopo aver creato la sotto-videata della mappa occorre impostarne le proprietà utilizzando gli appositi metodi della videata. Quelli disponibili solo i seguenti:
ClearMap | Rimuove tutti gli oggetti dalla mappa. |
CenterMap | Centra la mappa in uno specifico punto e imposta il livello di zoom. |
AddObjectToMap | Aggiunge un oggetto alla mappa (GeoMarker, GeoPolygon, ecc). |
RemoveObjectFromMap | Rimuove un oggetto dalla mappa (GeoMarker, GeoPolygon, ecc). |
ApplyChanges | Applica le modifiche alla mappa. |
GetMapOptions | Recupera le opzioni della mappa restituendo un oggetto GoogleMap. |
CalcolateRoute | Calcola un percorso sulla mappa. |
GetImageMap | Ritorna il percorso completo di una mappa in formato immagine (png). |
Posizionamento di oggetti nella mappa
È possibile visualizzare sulla mappa dei marker e dei poligoni rappresentati relativamente dalle classi GeoMarker e GeoPolygon. Un marker è un’immagine di cui è possibile definire le seguenti proprietà:
Proprietà | Descrizione |
ID | Identificativo del marker; da utilizzare nella gestione degli eventi di interfaccia legati al marker. |
Latitude | Latitudine del punto sulla mappa. |
Longitude | Longitudine del punto sulla mappa. |
Label | Singolo carattere alfanumerico maiuscolo dall'insieme (A-Z, 0-9) |
Address | Indirizzo corrispondente del marker. |
Icon | Immagine da mostrare. Può essere impostato ad uno dei valori della lista MarkerIcon oppure ad un indirizzo internet di un immagine. Il valore predefinito è smallDot. |
Color | Colore dell’immagine nel caso si usi un’immagine della lista valori Colors. Il valore predefinito è blue. |
Title | Tooltip mostrato quando si passa il mouse sopra il marker. |
HTML | Testo HTML da mostrare nel tooltip che si apre quando l’utente clicca su di un marker. |
Clickable | Indica un marker cliccabile. |
Draggable | Indica che un marker draggabile. |
Un poligono è un insieme di punti di cui è possibile definire le seguenti proprietà:
Proprietà | Descrizione |
ID | Identificativo del poligono; utile nel caso sia cliccabile. |
StrokeColor | Colore dei bordi in formato HTML. Il valore predefinito è Red. |
StrokeWeight | Spessore dei bordi in pixel. Il valore di default è 1 pixel. |
StrokeOpacity | Livello di opacità del riempimento, tra 0, trasparente, e 1, pieno. Il valore predefinito è 0,2. |
FillColor | Colore di riempimento in formato HTML. Il valore predefinito è Red. |
FillOpacity | Livello di opacità del riempimento, tra 0, trasparente, e 1, pieno. Il valore predefinito è 0,2. |
Clickable | Indica che un poligono è cliccabile. |
Draggable | Indica che un poligono è draggabile. |
Points | IDCollection dei vertici del poligono (sono oggetti di tipo GeoPoint). |
Per aggiungere oggetti ad una mappa occorre prima pulirla con il metodo ClearMap, poi si possono aggiungere gli oggetti con il metodo AddObjectToMap ed infine si deve aggiornare la mappa chiamando ApplyChanges.
Se, ad esempio, si vuole visualizzare la mappa dell’Italia con un marker su Bologna occorre scrivere il seguente codice:
MapView map = MyMapView.IDForm()
GoogleMap gm = map.GetMapOptions()
//
GeoMarker marker1 = new()
marker1.init()
marker1.Draggable = true
marker1.Label = "A"
marker1.Latitude = 41
marker1.Longitude = 12
map.AddObjectToMap(marker1)
map.ApplyChanges()
Dove MyMapView è l'istanza della sotto videata di MapView del componente GoogleMaps.
Gestione degli eventi della mappa
Quando l’utente interagisce con la mappa alla videata in cui è ospitata la sotto-videata MapView, vengono notificati degli eventi tramite il metodo SendMessage. Gestendo l’evento OnSendMessage della videata ospitante è possibile intercettare i seguenti eventi:
Evento | Quando viene notificato |
onLoadError | Notificato quando si verifica un errore durante il caricamento di Google Maps. |
onClick | Notificato quando si fa clic su un punto o un oggetto sulla mappa. |
onDrag | Notificato quando un oggetto viene trascinato sulla mappa. |
onZoomChange | Notificato quando lo zoom della mappa cambia. |
onCenterChange | Notificato quando cambia il centro della mappa. |
onRouteResult | Notificato quando un percorso è stato calcolato. |
onContextMenu | Notificato quando si fa click con il pulsante destro del mouse su un punto o un oggetto della mappa. |
Se si vuole intercettare, ad esempio, lo spostamento di un marker su una mappa occorre scrivere il seguente codice nell'evento onSendMessage della videata che contiene MapsView:
switch (Message)
{
case MoveMarker:
GeoMarker m = (GeoMarker)Doc
GoogleMapsWebApp.messageBox(formatMessage("Marker spostato |1", m.ID, [par2], [par3], [par4], [par5]))
break
}
Geo codifica di indirizzi
La classe GoogleMaps mette a disposizione due metodi statici, GeocodeAddress e ReverseGeocodeAddress, che permettono di ottenere le coordinate geografiche di un indirizzo e viceversa. In particolare, il metodo GeocodeAddress ha un parametro stringa in cui deve essere specificato l’indirizzo, e restituisce un oggetto GeoPoint che ne contiene le coordinate. All’inverso, il metodo ReverseGeocodeAddress richiede un oggetto GeoPoint in input e restituisce una stringa che contiene l’indirizzo. In questo caso è possibile indicare il tipo di indirizzo cercato tramite il parametro AddressType e la corrispondente lista valori. Entrambi i metodi restituiscono il successo dell’operazione tramite i seguenti parametri di output:
- ResponseStatus: viene valorizzato con il valore OK se la geo-decodifica ha avuto esito positivo. Se invece è stato superato il limite giornaliero di richieste si ottiene il valore OVER_QUERY_LIMIT. I possibili valori sono elencati nella lista valori GeocodeStatus.
- ResponseResult: contiene il testo del documento xml di risposta ottenuto dal servizio di Google; può essere utile per ottenere maggiori dettagli.
Il seguente codice può essere usato se, ad esempio, si vogliono ottenere le coordinate geografiche dell’indirizzo “Via Indipendenza, Bologna, Italia”:
string address = GoogleMapsWebApp.inputBox("Dammi un indirizzo")
string status = ""
string result = ""
//
if (address != "")
{
GeoPoint gp = GoogleMap.GeocodeAddress(address, status, result)
//
switch (status)
{
case OK:
GoogleMapsWebApp.messageBox(formatMessage("L'indirizzo si trova alle coordinate |1 ; |2", gp.Latitude,
gp.Longitude, [par3], [par4], [par5]))
break
case ZERO_RESULTS:
break
case OVER_QUERY_LIMIT:
break
case REQUEST_DENIED:
break
case INVALID_REQUEST:
break
case UNKNOWN_ERROR:
break
}
}
Calcolo di percorsi
È disponibile anche la funzionalità di calcolo dei percorsi, che, a partire da una mappa contenuta in una videata, consente di ottenere le medesime informazioni della popolare versione web del servizio. Si noti che il calcolo avviene lato client in maniera asincrona, quindi non può essere paragonato alla chiamata di un web service. Per ottenere il calcolo di un percorso occorre utilizzare la seguente procedura:
- Creare un oggetto di tipo GeoRoute.
- Valorizzare le proprietà Origin e Destination usando le coordinate geografiche o l’indirizzo come stringa.
- Ordinare alla mappa di calcolare il percorso tramite il metodo della mappa CalculateRoute, passando l’oggetto GeoRoute creato in precedenza.
- Il calcolo avviene in modalità asincrona; quando è concluso la mappa notifica alla videata che la contiene l’evento OnSendMessage specificando come messaggio “CalcRoute” e passando nel parametro Document l’oggetto GeoRoute completo delle informazioni del percorso.
E’ possibile configurare il tipo di percorso che si desidera calcolare tramite le seguenti proprietà:
Avoid Tolls | Se true, indica al servizio DirectionsService di evitare le strade a pedaggio ove possibile (default false). |
Avoid Highways | Se true, indica al servizio DirectionsService di evitare le autostrade ove possibile (default false). |
Avoid Ferries | Se true, indica al servizio DirectionsService di evitare i traghetti ove possibile (default false). |
Show On Map | Indica se il percorso calcolato deve essere visualizzato anche sulla mappa. |
Transport Mode | Tipo di percorso richiesto. Necessario. Dalla lista valori TravelModes. |
Departure Time | L'orario di partenza desiderato per il percorso, specificato come oggetto Date. L'oggetto Date misura il tempo in millisecondi dal 1° gennaio 1970. Questo deve essere specificato affinché un DrivingOptions sia valido. L'orario di partenza deve essere impostato sull'ora attuale o futura. Non può essere nel passato. |
Traffic Model | L'ipotesi preferita da utilizzare per prevedere la durata del viaggio a causa del traffico. L'impostazione predefinita è BEST_GUESS. |
Optimize Waypoints | Se impostato su true, DirectionsService tenterà di riordinare i waypoint intermedi forniti per ridurre al minimo il costo complessivo del percorso. |
Shortest | Indica se deve essere calcolato il percorso più breve (default = true); se falso, viene calcolato il percorso più veloce. |
Preserve Viewport | Per impostazione predefinita, la mappa di input è centrata e ingrandita rispetto al riquadro di delimitazione di questo insieme di direzioni. Se questa opzione è impostata su true, il viewport rimane invariato, a meno che il centro della mappa e lo zoom non siano mai stati impostati. |
Region | Codice regionale utilizzato come bias per le richieste di geocodifica. Opzionale. |
Unit System | Sistema di unità di misura preferito da utilizzare durante la visualizzazione della distanza. |
Le informazioni che vengono fornite nel calcolo sono le seguenti:
Distance | Lunghezza totale del percorso in metri. |
Duration | Durata totale del viaggio in secondi. |
Response Status | Risultato del calcolo del percorso |
Steps | Elenco dei passaggi da seguire per arrivare a destinazione (una IDCOllection di oggetti GeoStep) |
Nel codice seguente viene mostrato un esempio di codice da utilizzare per il calcolo del percorso fra Cesena e Bologna con una tappa intermedia a Faenza.
MapView map = MyMapView.IDForm()
GeoRoute route = new()
route.init()
route.Origin.Address = "Cesena"
route.Destination.Address = "Bologna"
//
GeoPoint wp = new()
wp.Address = "Faenza"
route.Waypoints.add(wp)
route.PreserveViewport = true
map.AddObjectToMap(route)
map.ApplyChanges()
Quando il calcolo è completo possiamo reperire le informazioni tramite l’evento OnSendMessage della videata che ospita la mappa, come mostrato qui di seguito.
switch (Message)
{
case CalcRoute:
GeoRoute gr = (GeoRoute)Doc
if (gr.ResponseStatus == OK)
{
string lunghezza = toString(gr.Distance / 1000,00)
string durata = toString(round(gr.Duration / 3600,00, 2))
GoogleMapsWebApp.messageBox(formatMessage("Il percorso calcolato ha lunghezza |1 |3 e durata |2",
lunghezza, durata, gr.UnitSystem, [par4], [par5]))
}
else
{
GoogleMapsWebApp.messageBox(formatMessage("Il calcolo del percorso non è riuscito: |1",
gr.ResponseStatus, [par2], [par3], [par4], [par5])
}
}
Se la mappa è mostrata a video, verrà visualizzato il percorso calcolato.
Configurazione API di Google Maps
Per poter utilizzare il componente Google Maps occorre (anche in ambiente di sviluppo) avere un profilo nella console di Google Cloud Maps platform.
Per accedere al servizio utilizzare questo indirizzo:
https://console.cloud.google.com/google/maps-apis/
Le API di Google Maps Platform utilizzate dal componente Google Maps sono:
- Directions API
- Geocoding API
- Maps JavaScript API
- Places API
Quindi nella console di Google Maps Platform andranno abilitate queste API nel cliccando sul menu Esplora e abilita le API.
Nella videata che viene aperta al click andranno selezionate le API necessarie e infine avremo l'elenco delle API selezionate.
A questo punto dal menu di sinistra si clicca sulla voce Credenziali dalla quale si possono aggiungere chiavi specifiche per le vostre applicazioni che utilizzeranno il componente Google Maps.
Da questa videata è possibile gestire le attuali chiavi o aggiungerne di nuove.
Nella gestione di una chiave possiamo indicare il dominio che la potrà utilizzare in modo che non possa essere usato in modo improprio da altri.
Per l'ambiente di sviluppo è possibile codificare l'indirizzo ip della propria connessione ad internet.
Per poter generare una chiave per l'ambiente di sviluppo basta essere registrati alla Google Maps Platform, mentre per utilizzarlo in un sito in produzione occorre avere un profilo di fatturazione con un conto bancario o una carta di credito abilitati al pagamento.
Ultima modifica: 17/08/2023 / Validità: da 22.5.8700