CapeSoft.Com
Clarion Accessories
NetTalk
Doc Index
NetMaps
CapeSoft Logo

CapeSoft NetTalk
NetMaps

Download Latest Version
Installed Version Latest Version

NetTalk NetMaps

Available in NetTalk Desktop, NetTalk Server and NetTalk Apps. Applies to Desktop (ABC or Clarion) apps.

Introduction

This document is for maps in Desktop apps. For maps in Webserver apps see here.

Seeing a Map in a web application is fairly common. NetTalk Maps introduces the ability to include maps (and related map functionality) directly into an ABC or Legacy Desktop Application.


Requirements

NetMaps for Desktop apps requires
Note: Map Providers use TLS for Secure communications. Read Deploying a TLS Client or Server for more details.

Terminology

Name Description
Chaining Commands In some cases a sequence of commands is necessary in order to achieve the desired result. For example given a set of waypoints it may be desirable to optimize the order of the points, get text instructions to travel to each point, and also display the points on a map.  Since these commands are all asynchronous each one has to complete before the next can be initiated.

Command chaining is the concept of calling one method, with instructions to chain to the other commands when this one completes.
Latitude
Longitude
The system used to identify every position on the planet. In the NetMaps classes these values are REALs, indicating degrees.
Latitude are lines north and south of the equator. Valid values for Latitude are -90 (south pole) to +90 (north pole).
Longitude are lines west and east of the Greenwich Meridian (a line that goes through Greenwich, London, England). Valid values for Longitude are -180 to +180.
Mouse Wheel Zooming The Zoom of the map determines how far (or how close) the viewer is to the surface of the Map. If the application has WinEvent enabled then the zoom value of the map can be altered by simply moving the mouse over the map and rotating the mouse wheel forward or backward. If WinEvent is not available then the zoom property can be manipulated in other ways (like letting the user edit the value on the screen) to change the zoom of the map.
Provider The web service that provides the root mapping services is known as the Map Provider.
Tiles Each map is broken into small graphic squares, based on the latitude, longitude and zoom level of the map. Each of these small squares is known as a Tile. Ultimately each map is made up of one, or more, tiles. Each change to the map location, zoom level, or map type will result in more tiles being fetched from with the cache, or from the tile provider.
Zoom The zoom is a measure of the distance from the viewer to the map. A low zoom value (1) means the viewer is "far away" and the details on the map are very coarse. High zoom values (20) mean the user is very close to the ground, and the map is very detailed. The Valid values for zoom are 1 to 20. 1 is the "furthest" away while 20 is closest to the ground.

Features

Draw Maps

The most obvious feature in a mapping class is the ability to, well, display maps. Maps can be moved around using the mouse, zoomed and unzoomed using the mousewheel, have marker on them, be displayed in map or satellite form and in some cases provide information like traffic conditions and so on.

If a user clicks on the map then the program can identify where they clicked, and do an appropriate action (like open a form) based on that.

Markers

Markers are icons placed on the map. These markers can have an associated image, Title and description that appears in an info box, either permanently open or opens when the user hovers the mouse over the icon.

Geocoding

Geocoding is the process of taking a street address and turning it into a latitude / longitude position.

Reverse Geocoding

Reverse Geocoding is the process of taking a latitude / longitude position and turning it into a street address.

Route Optimization

Given a number of waypoints, Route Optimization is the process or ordering the waypoints so that you can travel to each one in the least amount of time.

HERE: If using the HERE provider, note that this makes use of the Waypoints Sequence Extension. This is not enabled by default. See Extensions for more information.

Route Instructions

Given a route (with one, or more destinations)  this returns the directions needed to travel from one point to the next.

Address Autocomplete

As the user type an address, the auto-complete suggests the rest of the address. This delivers not only reduced time to enter the address, but also corrects address formatting so that more consistent addresses are entered.

Searching

You can do a search on the map, looking for places of interest, specific businesses, restaurants and so on.

Providers

There are a variety of map providers on the market. NetTalk provides a consistent interface so that different providers can be used. This allows the programmer to choose which mapping service is right for them.

Usually a "consistent interface" means a "lowest common denominator" approach - you can easily switch providers, but you can't easily take advantage of features unique to one or other provider. NetTalk provides the best of both worlds, allowing for a common interface for common features, as well as allowing you to make use of individual unique features if you wish to do so.

Currently NetTalk Desktop supports the following map providers;

HERE Maps

HERE Maps were the original map providers for Nokia and are generally accepted to be one of the premier map providers available today. They have a good balance of reasonable pricing, a permissive license and a powerful, and effective, Mapping API.

The developer portal for HERE is at https://developer.here.com/.

Licensing

It is important to make sure you are using the appropriate licensing model for your application. HERE Plans are located at https://developer.here.com/plans.

Authentication

HERE makes use of a number of authentication schemes.
Method Description
AppId and AppCode  The original authentication system. As a HERE developer you add your project to your list of projects, and generate an App ID and App Code. This system is considered by HERE to be a legacy system and new projects will no longer generate AppCodes. Use the ApiKey system for new projects, and switch existing projects to the ApiKey system
ApiKey The currently preferred approach. On the HERE site generate a REST API KEY for your application. Enter this on the NetTalk Global Extension, Options tab. (Hint: use the REST ApiKey not the JavaScript API key).
AuthToken Not supported yet.

Adding Maps Support to an Application.

Multi DLL

If this is a Multi-DLL system then add all the above to the data DLL.
In the Data DLL, on the MultiDLL tab of each (if it exists) set both options on.

Add the above to any other app(s) in the system that contain a map.
If you add them to the Exe app be sure to set the "This is part of a Multi-DLL program" switch on for each of them.

Adding Map Functionality in a Procedure

Control Template

In most cases the NetMap object will be used to display a map to the user. A control template has been provided for this purpose. To populate the control template on a window simply go to the Window Designer, go to the Control Templates pad, select the MapControls from the list available and place it somewhere on the window.

You can adjust the position and size of the Map control using the normal designer tools. If the window is resizable then be sure to set the appropriate resize options for the control as well.

Using the Class without a Window Control

The NetMaps class is not all about displaying a map. There are other features provided which are "text only". Therefore the NetMaps classes are designed with this in mind, and can be used on a window with no physical map. Some features which can be used in this text mode include Geocoding, Reverse Geocoding, Route Optimization, Route Instructions and Address AutoComplete.

Note that if you do not have Draw you can still make use of these features that work without a visual map control.

Code

The following section covers common tasks that you may want to do in embed code.

Draw map based on position and zoom

You can call the GetMap method, with a latitude, longitude and optionally a zoom factor, and the control will draw the map centered on that position. If the zoom parameter is omitted then the current zoom level for the map will be used.

A slight variation on this method allows you to enter two positions. The map then sets the zoom optimally  to that both these extremes are visible.

This is an asynchronous command. You can monitor the command queue to determine when all the tiles for the map have been retrieved.

Draw map based on address

You can call the GetMap method with a string field containing an address, and optionally a zoom. If the zoom parameter is omitted then the current zoom level for the map will be used. This is an asynchronous command. You can monitor the command queue to determine when all the tiles for the map have been retrieved.

Get address based on longitude and latitude

The GetAddress method takes a longitude and latitude and returns an address.  This is known as Reverse Geocoding. This is an asynchronous command. The result, when available, will be sent to the AddressFound method.

Get longitude and latitude based on address.

The GetLocation method takes an address, and returns the location as a latitude and longitude. This is an asynchronous command. The result, when available, will be sent to the LocationFound method.

AutoComplete a partial address

The GetAutoComplete method takes a partial address and returns a suggestion list of complete addresses. this is an asynchronous command. The result, when available, will be sent to the AutoCompleteFound method.

The suggestions will be returned in a queue form. This queue contains fields with both the complete address and each address component separately. You can parse this queue however you wish, copying the fields into your address fields, or populating a queue for a suggestion list.

Note that for entry fields, combo fields and so on if the Immediate attribute is set on the control, then an event will be generated for each keystroke. This allows you to track what the user is typing, and do the auto-complete request in the background.

Search for something on the map

Searching can be done using the GetSearch method. This method is asynchronous and the results, when retrieved, are automatically added to the Marker Queue, and displayed on the map with an icon of your choice.

Once the search is complete the SearchFound method will be called, although you typically won't need to put any code into here.

Optimize a Route

Routes work with a queue of Waypoints. The object has a property called WaypointsQueue, which is of type NetMapWaypointsQueueType. You can add points to this queue, then call several methods to make use of this queue.

The OptimizeRoute method takes this queue and passes it to the provider. The provider then determines the optimal path that incorporates all the points.

This method can chain to the GetRoute method, and from there to the GetMap method if desired.

HERE Provider:  For the HERE provider you can have up to 120 waypoints if traffic is not considered, but only up to 50 with traffic taken into consideration. If the routing mode pedestrian is used, the distance between each two of the waypoints must not be greater than 5km.

HERE Provider: If using the HERE provider, note that this makes use of the Waypoints Sequence Extension. This is not enabled by default. See Extensions for more information.

Get Route Instructions

Routes work with a queue of Waypoints. The object has a property called WaypointsQueue, which is of type NetMapWaypointsQueueType. You can add points to this queue, then call several methods to make use of this queue.

The GetRoute method takes this queue

Set the Map Type and Style

Use the SetMapType method to set the desired map type (map, satellite, traffic etc) and style (day, night, etc).

Add a Marker to the Map

Markers are added to the map by calling the SetMarker method. You can add multiple markers with multiple calls to the method. Once all the markers are added call the DrawMarkers method to draw the markers on the map.

The SetMarker method takes up to 8 parameters. The first one is the Marker ID. This is the value that will be returned when a user clicks on the icon, so is usually some unique identifier to the underlying data for the marker (a record ID in a table or queue, or whatever.)

Markers can have a description, and an image associated with them. These appear in an info box, positioned near the marker.
You can set the text for a marker using the SetMarkerDescription method. An Image can also be added using a SetMarkerImage method. You can call either method, or both, to associate with the marker.

If the Description and Image are both set to hide, then the info box will only be displayed when the user mouse-overs a marker. If either are set to unhide then the info box will appear all the time.

User clicked on a Marker Icon

When a user clicks on the map (without moving the mouse) then a call to the MapClicked method is made. This method takes two parameters, the Longitude and Latitude of the click. If the click is on an Icon then the Marker ID will be returned. This is the ID that was used when the SetMarker method was called.

If you wish to take an action then embed code into the MapClicked method, after the parent call, inspecting the value returned by the parent call.

User clicked on the map

When a user clicks on the map (without moving the mouse) then a call to the MapClicked method is made. This method takes two parameters, the Longitude and Latitude of the click.

You can embed code into this method, before or after the parent call. If after the parent call then you can also determine if the click was on an existing icon on  the map.

Monitor the CommandQueue

All the networking commands (ie calls to the provider, or cache) are executed asynchronously. There is a list of current, and outstanding commands in the CommandQueue property. When commands are added, or removed, from this queue then the CommandQueueChanged method is called.

You can embed in this method if you need to know when commands are waiting, and when there are no more commands to execute.

Get the distance between two points

The Distance method returns the "crow flies" distance between two co-ordinates. The result can be in yards, miles, meters or kilometers.

Lock map position or zoom

To prevent the user from moving the map location, using the mouse, set the LockPositionProperty property to true. To prevent the mouse wheel being used to change the zoom, set the LockZoom property to true. The map can still be moved by setting the co-ordinates directly (ie calling one of the GetMap variations mentioned above.)
 

Determine if a location is currently visible on the map

The OnMap method takes in a position, and returns true if the point is currently visible on the map, false otherwise.

Draw a Route as a List of GPS Coordinates

Most Route functions involve finding a driving-route over land. However in some cases (such as on water, or in the air) there's no restriction like that and a route is simply a list of GPS coordinates. The SetRoute method can be used to construct such a route.

You can pass the SetRoute method a pre-constructed queue (of type NetMapCoordinatesQueueType) or you can feed it individual coordinates. The route has an ID, and in the case of individual coordinates, a leg number. For example;

net.SetRoute('route1',1, 18.012 , 33.111,color:green)
net.SetRoute('route1',2, 28.112 , 33.511,color:red)
net.SetRoute('route1',3, 18.212 , 33.811,color:green)


here's another example;

routequeue   NetMapCoordinatesQueueType
  code
  ! populate routequeue here
  net.setroute('route2',routequeue,color:blue)


Other methods which you may use in this context include GetRoute, DeleteRoute and DrawRoutes.

Caching

Fetching the same tiles over and over from the server is undesirable for performance and cost reasons. For this reason NetMaps caches images in the CacheFolder. When the object needs a tile it will look first in the cache folder, if the tile is there then it is used, if it is not there then the request is passed to the tile provider.

The default cache folder is c:\temp\maps. This can be changed by setting the CacheFolder property to any suitable value by calling the SetCacheFolder method. If the folder does not exist then it will be created. Setting the cache folder to a Network folder means that all users can share the same cache.

The length of time a file is valid in the cache is determined by the CacheExpiryDays property. This property defaults to 30.
Traffic based tiles are automatically invalid after 15 minutes.

The cache can be disabled completely by setting the ForceNoCache property to true. This is not recommended.

To force a request to fetch the Tiles from the server, and not from the cache, set the RefreshCache property to true before the call to GetMap. It is recommended that the property be reset back to false after the request.

Template Reference

Global Template

Options / Maps Tab

Base Class
This is the base class you want to use as the default provider for this app. For example to use the HERE maps as your provider then this would be set to NetMapsHERE.
App ID
This is the Application ID as provided by the maps provider. This can be overridden at the local level, but setting it here allows you to change it more easily if necessary. This field is an expression so you can use a variable here, or a fixed value surrounded by quotes.
App Code
This is the Application Code as provided by the maps provider. See App ID above.
API Key
This is the ApiKey as provided by the MAPS provider.
Use Testing Server
If a provider differentiates between a productin server, and a testing server then you can choose which one to use here. For example the HERE provider has a Production environment and a Customer Integration Testing (CIT) envornment, used when developing and testing. To use the HERE CIT server you would turn this option on.

Control Template

Settings / Options Tab

Use Mouse Wheel Zooming
If you have WinEvent in the application, and this option is on, then the user will be able to zoom in and out of the map using the mouse wheel. If you do not have WinEvent, or this option is off, then you will need to provide the user another method (like an entry field) if you want to allow them to change the zoom.
Default Zoom
The default value to use for the zoom when the map opens. This is an expression so can be a variable.
Mark with Icon
If this option is open then the opening position of the map is automatically identified with a marker.
Default Icon
The icon to use for the opening marker.

Settings / Authentication Tab

The authentication settings are issued to you by the map provider. These settings are usually set on the global extension (and left blank here) however you can override the global settings if you wish. This is useful if you use multiple providers in the same app, and this object is not using the primary provider.

Settings / Fields Tab

The Fields tab allows you to link controls on the window with the map. If the user then navigates the map these controls will update. Conversely if the controls are altered then the map is updated as well. these settings are FIELDs not Expressions, so a single field is used for each setting. Note that the Field is set, not the control which displays that field. This allows you to update fields even if those fields are not displayed on the window.
Address
Field containing the address.
Latitude
Field containing the Latitude
Longitude
Field containing the Longitude
Zoom
Field containing the Zoom level
Icon
Field containing the icon. If this is left blank then the default icon (see Options tab above) is used.

Extension Template

It is possible to use the map class without using a screen control. This is useful for ancillary tasks like Geocoding or Reverse Geocoding which don't need a map. You can add a NetTalk Object to a procedure in the usual way to do this.

Set the BaseClass of the object to your preferred provider. For example NetMapsHERE.
On the settings tab enter any specific settings (or leave them blank to use the global settings.)

Class Reference

_NetMapsWebClient

Included in NetTalk Desktop

This class is used internally by the NetMapsBase class. The underscore prefix means it is not a generally accessible class, it's designed to be used only by the Maps class. This class is basically a NetWebClient class with only a few small tweaks. Calls to ErrorTrap and PageReceived in this object are passed to the ErrorTrap and PageReceived methods in the NetMapsBase object.

The NetMapsBase object maintains a queue of these objects, which in turn allows for multiple requests to be sent at the same time. This improves performance when fetching map tiles.

Derivation

  • _NetMapsWebClient ( NetMaps.Inc / NetMaps.Clw )

Properties

Property DeDescription
APIBusy The object is currently busy processing a request for the host object.
Maps
&NetMapsBase
A pointer to the host NetMapsBase object (or object derived from the NetMapsBase class).
Qid The location of this object in the host NetMapsBase object ClientsQueue. This is the unique id number for this WebClient object, to distinguish it from all the other web client objects.
Request The URL for the most recent request done by the object.

Methods

Method Description
PageReceived Incoming data received from the remote server.  Passed to the parent NetMapsBase class, PageReceived method.
ErrorTrap Incoming Errors received from the remote server. Passed to the parent NetMapsBase class, ErrorTrap method.

NetMapsBase

Included in NetTalk Desktop

Derivation

  • NetMapsBase ( NetMaps.Inc / NetMaps.Clw )
    • _NetAll

Structures

NetMapMarkerQueueType
Fieldth> Description
ID (string) A unique identifier for the icon. This is the identifier that will be returned if the user clicks on the icon.
Latitude (real) The latitude of the position being marked.
Longitude (real) The longitude of the position being marked.
Icon (string) ThThe icon name to use. Use a ~ in front of the name if the icon is a resource in the EXE or DLL. If no ~ is used the the icon will be read from the disk.
HideIcon (long) Set to true if the icon should not be displayed.
PointX (long) The x-offset, from the left, to the "point" of the icon. In pixels.
PointY (long) The y-offset, from the top, to the "point" of the icon. In pixels.
IconIndex (long) If the icon contains multiple images, this indicates which one should be used.
Position (Long) ThThe preferred position of the info box relative to the point on the map. If the info box will not fit in this position then another position is used. Valid values are net:North, net:NorthEast, net:East, net:SouthEast, net:South, net:SouthWest, net:West, net:NorthWest.
Title (string) A title for the info box associated with this marker.
Description (string) A A short description for the info box associated with this marker.
HideText (Long) If set to true then the Title and Description are not displayed.
Image (string) ThThe name (and if necessary, path) of an image (on the disk) to include in the info box.
ImageWidth (long) The width of the image to display.
ImageHeight (long) The height of the image to display.
HideImage (long) If this is set to true ththen the image is not displayed in the info box.
NetMapManeuverQueueType
Field Description
ID (string)
Latitude (real)  
Longitude (real)  
InstructionHTML (string)  
InstructionText (string)  
TravelTime (long)  
Length (long)  
NetMapWaypointsQueueType
Field Description
ID (string) A unique identifier for the point.
Format (string)  
Type (string)  
Latitude (real)  
Longitude (real)  
Position (string)  
TransitRadius (real)  
Label (string)  
StreetName (string)  
StartPoint  
EndPoint  
SortOrder  
NetMapAddressQueueType
Field Description
Combined (string) A combination of the fields below in a single comma separated string
Unit (string)  
HouseNumber (string)  
Street (string)  
District (string)  
City (string)  
County (string)  
State (string)  
Country (string)  
NetMapCoordinatesQueueType
Field Description
LatitudeY A real value containing the Latitude of the point.
LongitudeX A real value containing the Longitude of the point.

Properties

Property DeDescription
AddressQueue
&NetMapAddressQueueType
A queue of addresses returned after doing a GetAutoComplete command.
AutoCompleting A A request to auto-complete a partial address is currently underway. Additional requests to autocomplete a partial address will be rejected until the current operation is finished.
CacheExpiryDays
long
The number of days a (non traffic) map tile can be in the cache and considered valid. If set to 0 then cached files never expire. The default value is 30 days. This setting does not apply to traffic tiles which will become invalid after 15 minutes. See Caching.
CacheFolder
string
The folder containing the cached tiles. Use the SetCacheFolder method to set this property.  See Caching.
ClientsQueue
&NetMapClientsQueueType
A queue of _NetMapsWebClient objects. Multiple objects means hat multiple requests can be handled at the same time. As soon as a WebClient is available a command from the CommandQueue is passed to that object for processing. This parallel processing allows for maximum performance when a number of requests (eg a number of tiles) are created at the same time.
CommandQueue &NetMapCommandQueueType A queue of commands. The queue declaration is in netmaps.inc. When commands need to be sent to a provider for processing, then they are added to the CommandQueue. The Next method passes waiting commands to available web client objects (ie clients in the ClientsQueue).
ForceNoCache
long
If this is set to true then incoming files will not be saved to the cache. See Caching. . This setting is not recommended.
InfoBackgroundColor
long
The color of the information box that can appear near markers.
InfoBorderColor
long
The color of the border around the information box that can appear near markers.
InfoDescriptionFontColor
long
The color of the font used for the description text in an information box.
InfoTitleFontColor
long
Tthe color of the font used for the title text in an information box.
LockPosition
long
If set to true then the map cannot be moved with the mouse. It can still be moved with calls to GetMap.
LockZoom
long
If set to true then the map cannot be zoomed with the mouse wheel. It can still be zoomed with calls to GetMap.
MapStyle
long
One of net:day, net:night. Use the SetMapType method to set this property.
MapType
long
One of Net:Map, Net:Satellite, Net:Traffic, Net:TrafficHybrid, Net:Hybrid, Net:Panoramic, Net:Weather, Net:Terrain, Net:Pedestrian  .Use the SetMapType method to set this property.
ManeuverQueue &NetMapManeuverQueueType A queue containing the maneuvering instructions returned by a call to GetRoute. Can be used inside the RouteFound method.
MarkerQueue &NetMapMarkerQueueType A queue of the markers currently on the map. Note that not all markers may be visible, some may be off the map boundaries.
net
&_NetMapsClient
The WebClient object that was used to fetch the request. Not usually needed, but can be inspected in any of the Found methods.
RefreshCache
long
If this is set to true then files will not be used from the cache, but will be re-fetched from the provider. If you set this to true then you will need to set it back to false when the object can use the cache again or it will continue to re-fetch files from the provider, not the cache. See Caching.
TestServer Can be true or false. Default value is false. Set to true if the account should use the provider's test server. (The HERE provider calls this the CIT server.) Often used for demo accounts and so on.
ThisPage
StringTheory
The complete response received by from the provider. Use only in methods where it is indicated to be in scope.
WaypointsQueue
&NetMapWaypointsQueueType
A queue of positions. This queue can be fed into various methods, like OptimizeRoute, GetRoute and so on.
Zoom
long
The current zoom level of the map. Use the SetZoom method to set this property.

Methods

Method Description
AddressFound Called when the reply to a GetAddress command is received.
Authenticate Sets the authentication properties in the class.
AutoCompleteFound Called when the reply to a GetAutoComplete command is received.
Cached Determines if a valid file is in the disk cache.
ClearTile Clears a tile space on the map.
CommandQueueChanged Called whenever a command is added to, or removed from, the command queue.
CopyrightFound Called when the reply to a GetCopyright command is received.
DeleteMarker Deletes a marker from the icons queue.
DeleteRoute Deletes a route from the routes queue.
Distance Calculates the crow-flies distance between two points.
DrawMarkers Draws all the visible icons in the icons queue on the map image.
DrawRoutes Draws all the visible route legs on the map image.
DrawTile Draws a tile on the map. Called when tiles are received from the provider, or when tiles are found in the cache.
ErrorTrap Called when there is an error communicating with the provider.
Get Calls the Get method of the current _NetMapsWebClient object.
GetAddress Given a latitude and longitude, get an address for the location. This method is asynchronous. When the result is returned the AddressFound method is called.
GetAutoComplete Given a partial address, return a list of suggested complete addresses.
GetCopyright Get copyright information from the provider. This method is asynchronous. When the result is returned the CopyrightFound method is called.
GetFileName Returns an appropriate name for a tile based on the current map type, zoom, factor, location and so on.
GetLocation Given an address, get a latitude and longitude for the address. This method is asynchronous. When the result is returned the LocationFound method is called.
GetMap Gets a map from the provider based on many possible parameters.
GetMouseLatitude Gets the Latitude of the current mouse position over the map.
GetMouseLongitude Gets the Longitude of the current mouse position over the map.
GetRoute Given a queue of Waypoints, get text (or HTML) instructions for moving from each waypoint to the next.
GetSearch Search for an item on the displayed map.
Init Calls the Init method for all the _NetMapsWebClient objects.
Kill Calls the Kill method for all the _NetMapsWebClient objects.
LocationFound A location has been determined from an address. Optionally redraw the map to this location.
MapClicked Called when the user clicks on the map. If the user clicked on an Icon then the ID of the marker is passed into the method.
MouseOverMarker Returns the ID of a marker if the mouse is currently over a marker.
Move Moves the map my a specified number of deltaX and deltaY pixels.
MoveMouseToCenter Moves the map so that the clicked position is now the center of the map.
Next Finds the next waiting command in the CommandQueue and passes it to the next available _NetMapsWebClient object.
OnMap Determines if a specific latitude and longitude is currently visible on the map, given the current map coordinates and zoom level.
OptimizeRoute Given a queue of Waypoints, determine the best route that covers all the points.
PageReceived Called when data is received from the provider.
Refresh Redraws the map and all other items associated with the map (Markers, routes and so on)
RefreshExtras Redraws all the ancillary map items - markers, routes, areas and so on.
RoundUp Rounds a real value to the next integer value.
RouteFound A route was found.
RouteOptimized A route was optimized.
SetCacheFolder Sets the folder name for the cached tiles. If the folder does not exist it will be created.
SetMarker Adds an marker to the MarkerQueue property.
SetMarkerDescription Adds description text to a marker, for displaying in an info box.
SetMarkerImage Adds an image to a marker for displaying in an info box.
SetMapControl Binds the map object to an image control on the window. A region control is also created to get events.
SetMapType Sets the MapType and MapStyle properties for the map.
SetRoute Sets a route, or route leg.
SetZoom Sets the Zoom property for the map.
Start Return the properties of the object back to their default state.
TakeEvent Processes windows events and handles events that affect the map.
WatchControls Sets various properties in the object to match controls on the window, so they can be monitored and the map changed automatically.

AddressFound

AddressFound (String pFirstAddress, Real pDistance)

Description

Called when the reply to a GetAddress command is received. The CommandQueue record containing the just-completed command is in scope.

Parameters

Parameter Description
pFirstAddress The first address in the list of most likely addresses for this location.
pDistance The distance (in meters) from the location to the address.

Notes

The requested command in the CommandQueue is in scope.
The complete response returned by the provider is in the ThisPage property, and is in scope.

Return Value

The method returns nothing.

See Also

GetAddress

Authenticate

Authenticate (<String pAppId>, <String pAppCode>, <String pApiKey>, <String pAuthToken>)

Description

This method sets the authentication properties in the class.

Parameters

Parameter Description
pAppId The app ID as provided by the provider.
pAppCode The AppCode as provided by the provider.
pApiKey An alternative to the App Code and App Id is the API Key.  Use this parameter if you have it. If this parameter exists it will be used in preference to the AppCode AppId combination.
pAuthToken Not used yet.

Return Value

The method returns nothing.

See Also



AutoCompleteFound

AutoCompleteFound()

Description

Called when the reply to a GetAutoComplete command is received. The CommandQueue record containing the just-completed command is in scope.

Parameters

None.

Notes

The requested command in the CommandQueue is in scope.
The complete response returned by the provider is in the ThisPage property, and is in scope.

Return Value

The method returns nothing.
The AddressQueue property is loaded with the suggestion list.

See Also

GetAutoComplete, AutoComplete a partial address

CommandQueueChanged

CommandQueueChanged (Long pChange)

Description

This method is called whenever a record is added to, or deleted from the command queue

Parameters

Parameter Description
pChange One of net:InsertRecord or net:DeleteRecord.
this indicates if the call was made because a record was added or deleted.

Return Value

The method returns nothing.

See Also



DeleteMarker

DeleteMarker (<String pId>)

Description

This method is called to remove a marker from the markers queue. If no ID is passed then the queue is cleared. This does not clear icons already visible on the map - it only removes the markers from the queue. To refresh the map so that deleted markers are removed use the Refresh method.

Parameters

Parameter Description
pID The ID of the icon being removed. If this parameter is omitted, or blank , then all the icons in the queue are removed.

Return Value

The method returns nothing.

See Also

SetMarker, Refresh

DeleteRoute

DeleteRoute(<String pId>)

Description

This method is called to remove a route from the routes queue. If no ID is passed then the queue is cleared. This does not clear routes already visible on the map - it only removes the routes from the queue. To refresh the map so that deleted routes are removed use the Refresh method.

Parameters

Parameter Description
pID The ID of the route being removed. If this parameter is omitted, or blank , then all the routes in the queue are removed.

Return Value

The method returns nothing.

See Also

SetRoute, GetRoute, DrawRoutes

Distance

Distance (Real pLatitudeA, Real pLongitudeA, real pLatitudeB, real pLongitudeB, Long pUnit = net:metres)

Description

Calculates the "crow flies" distance between two points.

Parameters

Parameter Description
pLatitudeA The latitude of the first point.
pLongitudeA The longitude of the first point.
pLatitudeB The latitude of the second point.
pLongitudeB The longitude of the second point.
pUnit One of net:yards, net:miles, net:kilometres, net:metres

Return Value

Returns a REAL indicating the shortest distance between the points.

See Also

OnMap

DrawMarkers

DrawMarkers (Long pDisplay=true)

Description

This method draws all the markers (which are visible, and fall into the map confines) from the markers queue onto the map.

Parameters

Parameter Description
pDisplay If this is true then the map, and hence image control are DISPLAYed at the end of this call. If this call is being made before the ACCEPT command for the window, it's preferable to set this parameter to false so the window will not be prematurely displayed.

Notes

Typically this method is not called directly. The RefreshExtras method draws all the map ancillaries, and should be used instead.

Return Value

The method returns nothing.

See Also

SetMarker, GetSearch

DrawRoutes

DrawRoutes(Long pDisplay=true)

Description

This method draws all the route legs (which are visible, and fall into the map confines) from the routes queue onto the map.

Parameters

Parameter Description
pDisplay If this is true then the map, and hence image control are DISPLAYed at the end of this call. If this call is being made before the ACCEPT command for the window, it's preferable to set this parameter to false so the window will not be prematurely displayed.

Notes

Typically this method is not called directly. The RefreshExtras method draws all the map ancillaries, and should be used instead.

Return Value

The method returns nothing.

See Also

GetRoute, SetRoute

GetAddress

GetAddress(real pLatitude, real pLongitude, Long pDistance = 25,<String pMode>, Long pType = net:json, <String pURLParameters>)

Description

Given a latitude and longitude, get an address for the location. This methods adds the request to the command queue. When this command is done then the result is returned to the AddressFound method.

Parameters

Parameter Description
pLatitude The latitude of the address
pLongitude The longitude of the address.
pDistance The maximum distance (in meters) from the location to the address.
pMode Provider dependant.
HERE: One of nhm:mode_retrieveAddresses, nhm:mode_retrieveAreas, nhm:mode_retrieveLandmarks, nhm:mode_retrieveAll, nhm:mode_trackPosition. Defaults to nhm:mode_retrieveAddresses.
pType The data type. Can be one of net:json or net:xml. Defaults to net:json.
pURLParameters And additional parameters that should be used when sending the request to the provider.

Notes

If an auto-complete address command is already underway then another call to this method is rejected, and the method returns 0 for the command number. The AutoCompleting property is set to true when a request is currently underway.


Return Value

An ID value into the command queue. The command queue contains a (unique) field for each command, called Counter. This is the (unique) ID for the command. This value is returned by this method.

See Also

AddressFound, Reverse Geocoding

GetAutoComplete

GetAutoComplete(string pSearchText, Long pMaxResults = 10, <String pCountryCodes> ,<String pURLParameters>, Long pSearchTextEncoding=st:EncodeAnsi)

Description

Given a partial address, return a list of suggested complete addresses. This methods adds the request to the command queue. When this command is done then the result is returned to the AutoCompleteFound method.

Parameters

Parameter DDescription
pSearchText The text containing the partial address.
pMaxResults An optional value from 1 to 20. The default value is 10. This determines how many suggestions are returned.
pCountry Codes An optional, comma separated list, of ISO 3 Country Codes. Use this to limit the address search to a particular country.
pURLParameters Any additional parameters required by the specific provider.
pSearchTextEncoding Identifies the encoding of the pSearchText parameter. By default this value is st:EncodeAnsi. If it is then it is converted to utf-8 before sending to the service. The codePage property is used to determine the ANSI code page.
Valid values for this parameter are; st:EncodeAnsi, stEncodeUtf8, st:EncodeUtf16

Return Value

An ID value into the command queue. The command queue contains a (unique) field for each command, called Counter. This is the (unique) ID for the command. This value is returned by this method.

See Also

AutoComplete a partial address, AutoCompleteFound

GetLocation

GetLocation(String pSearchText, Long pChainCommand = 0,<String pMode>, Long pType = net:json, <String pURLParameters>, Long pSearchTextEncoding=st:EncodeAnsi)

Description

Given an address, return a latitude and longitude for the position of the address. This is known as geocoding. This methods adds the request to the command queue. When this command is done then the result is returned to the LocationFound method.

Parameters

Parameter Description
pSearchText The text containing the address.
pChainCommand If set to Net:GetMap then once the location has been found, the map will draw at that position.
pMode  
pType One of net:json, net:xml. Indicates the preferred response type from the server.
pURLParameters Any additional parameters required by the specific provider.
pSearchTextEncoding Identifies the encoding of the pSearchText parameter. By default this value is st:EncodeAnsi. If it is then it is converted to utf-8 before sending to the service. The codePage property is used to determine the ANSI code page.
Valid values for this parameter are; st:EncodeAnsi, stEncodeUtf8, st:EncodeUtf16

Return Value

An ID value into the command queue. The command queue contains a (unique) field for each command, called Counter. This is the (unique) ID for the command. This value is returned by this method.

See Also

LocationFound, Geocoding, Chaining Commands

GetMap

GetMap()
GetMap(Real pLatitude, Real pLongitude, Long pZoom)
GetMap(String pAddress, Long pZoom=-1)
GetMap(Real pLatitudeBottom, Real pLongitudeLeft, Real pLatitudeTop, Real pLongitudeRight, Long pMinZoom=0, Long pMaxZoom=20)
GetMap(NetMapIconQueueType pIconQueue, Long pMinZoom=0, Long pMaxZoom=20)
GetMap(NetMapWaypointsQueueType pWaypointsQueue, Long pMinZoom=0, Long pMaxZoom=20)

Description

This method draws a map at the specified location. If no parameters are passed then the map is refreshed at the current location.

Parameters

Parameter Description
pLatitude The latitude of the center of the map.
pLongitude The longitude of the center of the map.
pZoom The zoom value for the map. To maintain the current value use self.zoom. In the address version of the call this field can be omitted.
pAddress A text address. Can be used in place of latitude and longitude.
pLatitudeBottom,
pLatitudeTop,
pLongitudeLeft,
pLongitudeRight
Bottom Left and Top right corners of an area to be included in the map. If this call is used then the zoom factor is automatically calculated to the highest value that includes the desired rectangle.
pIconQueue,
pWaypointsQueue
Automatically calculates the optimal parameters for the map so that all the items in the queue are visible.
pMinZoom
pMaxZoom
Restrict the automatic zooming to these boundaries.

Return Value

The method returns nothing.

See Also

SetZoom, SetIcon, SetMapType, GetRoute, GetLocation

GetMouseLatitude

GetMouseLatitude()

Description

Gets the latitude position of the mouse over the map.

Return Value

A REAL containing the Latitude. If the mouse is not over the map then a value of -999 is returned.

See Also

MapClicked, GetMouseLongitude

GetMouseLongitude

GetMouseLongitude()

Description

Gets the longitude position of the mouse over the map.

Return Value

A REAL containing the Longitude. If the mouse is not over the map then a value of -999 is returned.

See Also

MapClicked, GetMouseLatitude

GetRoute

GetRoute (String pId, Long pChainCommand=0,<String pIcon>,<String pMode>, Long pTime = -1, Long pDate = 0, Long pDepartArrive=net:depart, Long pType = net:json, <String pURLParameters>, Long pMetric=net:metric)

Description

This method takes the current values in the WayPointsQueue and passes them to the routing engine. Some providers take traffic into account, and some allow for future traffic conditions (based on past traffic conditions at that time.)

This methods adds the request to the command queue. When this command is done then the result is returned to the RouteFound method.

Parameters

Parameter Description
pID An ID for the route. Any value can be used. This is the value that will be passed to the DeleteRoute method if the route needs to be deleted.
pChainCommand If set to Net:GetMap then the map will be drawn, once the route has been fetched.
pIcon If set, then the waypoints will be added to the map as icons.
pMode Provider dependant.
HERE: Defaults to 'fastest;car;traffic:enabled'
pTime The time when the trip will take place.
pDate The date when the trip will take place.
pDepartArrive Set to one of net:depart (the default) or net:arrive. This refers to the above date and time being either the date and time of departure or arrival.
pType Set to one of net:json or net:xml. This determines the formatting of the return values.
pURLParameters Any additional parameters required by the specific provider.
pMetric Set to either net:metric (the default) or net:imperial. Controls whether the distances in the instructions in the reply is either kilometers (metric) or miles (imperial).

Example

  free(net.WaypointsQueue)
  net.WaypointsQueue.ID = 'home'
  net.WaypointsQueue.Label = 'home'
  net.WaypointsQueue.Position='-34.0143047,18.4871816'
  add(net.WaypointsQueue)
  net.WaypointsQueue.ID = 'postoffice'
  net.WaypointsQueue.Label = 'postoffice'
  net.WaypointsQueue.Position='-34.0213891,18.4663502'
  add(net.WaypointsQueue)
  net.WaypointsQueue.ID = 'gym'
  net.WaypointsQueue.Label = 'gym'
  net.WaypointsQueue.Position='-34.0175648,18.4502971'
  add(net.WaypointsQueue)
  net.WaypointsQueue.ID = 'work'
  net.WaypointsQueue.Label = 'work'
  net.WaypointsQueue.Position='-34.0398816,18.4698507'
  net.GetRoute(net:GetMap)
! after getting the route, get the map and show the points on the map.

Return Value

An ID value into the command queue. The command queue contains a (unique) field for each command, called Counter. This is the (unique) ID for the command. This value is returned by this method.

See Also

WayPointsQueue, RouteFound, OptimizeRoute, GetMap, Chaining Commands

GetSearch

GetSearch(String pSearchText, <String pIcon>, Long pMaxresults=100, <String pURLParameters>, Long pSearchTextEncoding=st:EncodeAnsi)

Description

This method takes a search string, and then searches the currently displayed map for items that match that string.

This methods adds the request to the command queue. When this command is done then the result is returned to the SearchFound method.

Parameters

Parameter Description
pSearchText The text that will be searched for.
pIcon An Icon to use to mark the search results. If the icon is omitted then the value MapSearch.Ico will be used.
pMaxResults The maximum number of results to get back. The default is 100.
pURLParameters Any additional parameters required by the specific provider.
pSearchTextEncoding Identifies the encoding of the pSearchText parameter. By default this value is st:EncodeAnsi. If it is then it is converted to utf-8 before sending to the service. The codePage property is used to determine the ANSI code page.
Valid values for this parameter are; st:EncodeAnsi, stEncodeUtf8, st:EncodeUtf16

Example

net.search('golf') 
 

Return Value

An ID value into the command queue. The command queue contains a (unique) field for each command, called Counter. This is the (unique) ID for the command. This value is returned by this method.

See Also

Searching, SearchFound

LocationFound

LocationFound (String pAddress,Real pLatitude, Real pLongitude, Long pGetMap)

Description

This method is called when a user clicks on the map (without moving the mouse.)

Parameters

Parameter Description
pAddress The address that was used in the call to GetLocation.
pLatitude The latitude of the location.
pLongitude The longitude of the location.
pGetMap Set by the call to GetLocation. If true then the map will automatically go to this position.

Return Value

Nothing.

See Also

GetLocation

MapClicked

MapClicked (Real pLatitude, Real pLongitude)

Description

This method is called when a user clicks on the map (without moving the mouse.)

Parameters

Parameter Description
pLatitude The latitude of the click .
pLongitude The longitude of the click.

Return Value

The method returns a STRING. If the user clicked on an Icon then the string contains the Icon identifier. If the user did not click on an icon then it returns a blank string.

See Also

GetMouseLatitude, GetMouseLongitude, SetIcon, User clicked on an icon, User clicked on the map

OnMap

OnMap(Real pLatitude, Real pLongitude)

Description

This method is called when a user clicks on the map (without moving the mouse.)

Parameters

Parameter Description
pLatitude The latitude of the position.
pLongitude The longitude of the position.

Return Value

The method returns true if the position is currently visible on the map. Returns false otherwise.

See Also

Distance

OptimizeRoute

OptimizeRoute(Long pChainCommand=0, <String pIcon>, <String pMode>, Long pTime = -1, Long pDate = 0, Long pDepartArrive=net:depart, Long pType = net:json, <String pURLParameters>, long pMetric=net:metric)

Description

This method takes the current values in the WayPointsQueue and passes them to the routing engine. Some providers take traffic into account, and some allow for future traffic conditions (based on past traffic conditions at that time.)

This methods adds the request to the command queue. When this command is done then the result is returned to the RouteOptimized method.

Parameters

Parameter Description
pChainCommand If set to Net:GetRoute then the GetRoute method will be called once the route has been optimized.
If set to Net:GetMap then the map will be drawn, once the route has been fetched.
This is an additive parameter - ie this can be set to Net:GetRoute + Net:GetMap
pIcon If set, then the waypoints will be added to the map as icons.
pMode Provider dependent.
HERE: Defaults to 'fastest;car;traffic:enabled'
pTime The time when the trip will take place.
pDate The date when the trip will take place.
pDepartArrive Set to one of net:depart (the default) or net:arrive. This refers to the above date and time being either the date and time of departure or arrival.
pType Set to one of net:json or net:xml. This determines the formatting of the return values.
pURLParameters Any additional parameters required by the specific provider.
pMetric Set to either net:metric (the default) or net:imperial. Controls whether the distances in the instructions in the reply is either kilometers (metric) or miles (imperial).

Example

  free(net.WaypointsQueue)
  net.WaypointsQueue.StartPoint = true
  net.WaypointsQueue.EndPoint = true     
! start and end at the same place
  net.WaypointsQueue.ID = 'home'
  net.WaypointsQueue.Label = 'home'
  net.WaypointsQueue.Position='-34.0143047,18.4871816'
  add(net.WaypointsQueue)
 
  net.WaypointsQueue.StartPoint = false
  net.WaypointsQueue.EndPoint = false
  net.WaypointsQueue.ID = 'postoffice'
  net.WaypointsQueue.Label = 'postoffice'
  net.WaypointsQueue.Position='-34.0213891,18.4663502'
  add(net.WaypointsQueue)

  net.WaypointsQueue.ID = 'school'
  net.WaypointsQueue.Label = 'school'
  net.WaypointsQueue.Position='-34.0329420,18.3514123'
  add(net.WaypointsQueue)

  net.WaypointsQueue.ID = 'gym'
  net.WaypointsQueue.Label = 'gym'
  net.WaypointsQueue.Position='-34.0175648,18.4502971'
  add(net.WaypointsQueue)

  net.WaypointsQueue.ID = 'work'
  net.WaypointsQueue.Label = 'work'
  net.WaypointsQueue.Position='-34.0398816,18.4698507'
  add(net.WaypointsQueue)

  net.OptimizeRoute(Net:GetRoute + net:GetMap,'MapPinRed.ico')
! after optimizing the route,
                                                              
! get instructions and draw the map.

 Return Value

An ID value into the command queue. The command queue contains a (unique) field for each command, called Counter. This is the (unique) ID for the command. This value is returned by this method.

See Also

RouteOptimized, WayPointsQueue, GetRoute, GetMap, Chaining Commands, Optimize a Route

Refresh

Refresh()

Description

Redraws the map image. Includes a call to RefreshExtras.

 Return Value

This method returns nothing.

RefreshExtras

RefreshExtras()

Description

Redraws all the ancillary information on the map. Markers, Routes, Areas and so on.

 Return Value

This method returns nothing.

RoundUp

RoundUp (Real pr, Long pd)

Return Value

This method returns the first whole number equal to, or greater than, pr divided by pd.


RouteFound

RouteFound (Long pChainCommand)

Description

This method is called when Route instructions have been received from the server.

Parameters

Parameter Description
pChainCommand The pChainCommand from the original call to GetRoute. ie whatever was passed into GetRoute ccomes out here.

Notes

If the pchainCommand parameter contains the net:getMap equate then then GetMap method, with the current WaypointsQueue property will be called by the parent call of this method. Thus manipulating this queue before the parent call will alter the map. Changing the value of pChainCommand can also change this behavior.

Return Value

Nothing.

See Also

GetRoute

RouteOptimized

RouteOptimized (Long pChainCommand)

Description

This method is called when route optimizations  have been received from the server.

Parameters

Parameter Description
pChainCommand The pChainCommand from the original call to OptimizeRoute. ie whatever was passed into OptimizeRoute comes out here.

Notes

If the pchainCommand parameter contains the net:getRoute equate then the GetRoute method, with the current WaypointsQueue property will be called by the parent call of this method. Thus manipulating this queue before the parent call will alter the route. Changing the value of pChainCommand can also change this behavior.

If it does not contain the net:GetRoute equate and if the pchainCommand parameter contains the net:getMap equate then the GetMap method, with the current WaypointsQueue property will be called by the parent call of this method. Thus manipulating this queue before the parent call will alter the map. Changing the value of pChainCommand can also change this behavior.

Return Value

Nothing.

See Also

OptimizeRoute

SearchFound

SearchFound()

Description

This method is called when the results of a search have been received.

Return Value

The method returns nothing.

When a search is complete then the results of the search are automatically added to the Marker Queue. The position and description of the found values are set.

See Also

Searching, GetSearch

SetCacheFolder

SetCacheFolder (String pFolder)

Description

This method is called whenever a record is added to, or deleted from the command queue

Parameters

Parameter Description
pFolder The folder to use as the cache folder for tiles. If the folder does not exist then this method will create the folder.

Return Value

The method returns nothing. The CacheFolder property is updated with the new value.

See Also

Caching

SetMarker

SetMarker(String pID, Real pLatitude, Real pLongitude, String pIcon, Long pIconIndex=1, Long pPointX=16, Long pPointY = 32, Long pHide=false)

Description

This method adds an icon to the markers queue. It does not actually draw the icon on the map (see DrawMarkers.)

Parameters

Parameter Description
pID The ID of the Marker. This is the ID that will be returned by the MapClicked method if the user clicks on an icon.
pLatitude The latitude of the icon.
pLongitude The longitude of the icon.
pIcon The name of the icon. Use a ~ as the first character of the name if the icon is a resource in the DLL or EXE. If no ~ is used then the icon will be read off disk.
pIconIndex If the icon contains multiple images, then the desired image can be set here.
pPointX The x-offset, from the left, identifying the "point" of the icon.
pPointY the y-offset from the top, identifying the "point" of the icon.
pHide If true then the icon is not displayed.

Return Value

The method returns nothing.

See Also

DeleteIcon, DrawIcons, MapClicked, Add an Icon to the map, User clicked on an icon ,

SetMarkerDescription

SetMarkerDescription (String pId, String pTitle, String pDescription, Long pPosition, Long pHide=false)

Description

This method adds an image to the info box for a marker. It does not actually draw the info box (see DrawMarkers.)

Parameters

Parameter Description
pID The ID of the Marker. This is the ID that will be returned by the MapClicked method if the user clicks on an icon.
pTitle The Title text to appear in the Info box.
pDescription The description text to appear in the info box.
pPosition The preferred position of the info box relative to the point on the map. If the info box will not fit in this position then another position is used. Valid values are net:North, net:NorthEast, net:East, net:SouthEast, net:South, net:SouthWest, net:West, net:NorthWest.
pHide If true then the info box is not displayed. It will be displayed if the user moves the mouse over the marker.

Return Value

The method returns nothing.

See Also

DeleteMarker, DrawMarkers, MapClicked, SetMarker, SetMarkerImage

SetMarkerImage

SetMarkerImage (String pId, String pImage, Long pWidth=0, Long pHeight=0, Long pPosition=0, Long pHide=false)

Description

This method adds an image to the info box for a marker. It does not actually draw the info box (see DrawMarkers.)

Parameters
Parameter Description
pID The ID of the Marker. This is the ID that will be returned by the MapClicked method if the user clicks on an icon.
pImage The name, and if necessary path, of the image to display.
pWidth The width the image should draw to. If 0 then the actual image width is used.
pHeight The height the image should draw to. If 0 then the aspect ratio of the original image is preserved.
pPosition The preferred position of the info box relative to the point on the map. If the info box will not fit in this position then another position is used. Valid values are net:North, net:NorthEast, net:East, net:SouthEast, net:South, net:SouthWest, net:West, net:NorthWest.
pHide If true then the image is not displayed in the info box.

Return Value

The method returns nothing.

See Also

DeleteMarker, DrawMarkers, MapClicked, SetMarker, SetMarkerDescription

SetMapType

SetMapType (Long pMapType=0,Long pStyle=0)

Description

This method sets the MapType and MapStyle properties for the object. Not all types and styles are supported by all provides. Where a provider does not support a style the closest appropriate style will be set.

Parameters

Parameter Description
pMapType One of Net:Map, Net:Satellite, Net:Traffic, Net:TrafficHybrid, Net:Hybrid, Net:Panoramic, Net:Weather, Net:Terrain, Net:Pedestrian  . If this parameter is omitted then the property is unchanged.
pMapStyle One of net:night, net:day. If this parameter is omitted then the property is unchanged.

Return Value

Returns net:ok

See Also

GetMap

SetRoute

SetRoute(string pID, Long pLeg, real pLongitudeX, real pLatitudeY, Long pColor = COLOR:Orange)
SetRoute(string pID, NetMapCoordinatesQueueType pRouteQueue, Long pColor = COLOR:Orange)

Description

This method adds an route, or route leg, to the routes queue. It does not actually draw the icon on the map (see DrawRoutes.)

Parameters

Parameter Description
pID The ID of the Route. This is the ID that will be passed to DeleteRoute if you want to delete a route.
pRouteQueue A queue, of type NetMapCoordinatesQueueType which contains all the legs for the route. If this form of the method is used then multiple legs are added to the route at the same time.
pLeg The leg number for the leg of the route being added. If this form of the method is used only one leg is added to the route.
pLatitude The latitude of the next waypoint in the route.
pLongitude The longitude of the next waypoint in the route.
pColor The color of the route, or route leg, when displayed on the map.

Return Value

The method returns nothing.

See Also

GetRoute, DeleteRoute, DrawRoutes

SetZoom

SetZoom (Long pZoom, Real pLatitude=1000)

Description

This method sets the zoom property for the object. when the zoom changes a number of other properties are recalculated, so the property should not be set directly.

Because the early is not a perfect sphere, the latitude being displayed can affect the calculations slightly. If the latitude is incorrect though the error will not be greater than 0.3%, so it's not a major problem if the latitude is not known.

Parameters

Parameter Description
pZoom the desired zoom level. This value should be in the range 1 (furthest away) to 20 (closest to the ground.)
pLatitude If omitted (or set to 1000) then the current latitude of the map is used.

Return Value

Returns nothing

See Also

GetMap

ClassNetMapsHERE

Included in NetTalk Desktop

Derivation

  • NetMapsHERE

Properties

Property Description
  There are no properties declared for this class. However all the properties for the base class are in scope.

Methods

Method Description
APIGetAddress Makes a request to the provider for the nearest address to a specific latitude, longitude position. This method is asynchronous. When the result is returned it is passed to the appropriate ParseReverseGeoCodeReply method for processing. The AddressFound method in the parent class is then called.
APIGetCopyright Makes a request to the provider for copyright information. This method is asynchronous. When the result is returned it is passed to the appropriate ParseCopyrightReply method for processing. The AddressFound method in the parent class is then called.
APIGetLocation Makes a request to the provider for a specific latitude and longitude, based on an address. This method is asynchronous. When the result is returned it is passed to the appropriate ParseGeoCodeReply method for processing. The LocationFound method in the parent class is then called.
APIGetTile Makes a request to the provider for a specific tile. This method is asynchronous. When the tile arrives it is passed to the PageReceived method of the parent class.
APIGetRoute Makes a request to the provider for specific route information. This method is asynchronous. When the result is returned it is passed to the appropriate ParseCalcRouteReply method for processing. The RouteFound method in the parent class is then called.
ParseCalcRouteReplyJSON Parses the reply from the specific provider, incoming data is JSON.
ParseCalcRouteReplyXML Parses the reply from the specific provider, incoming data is XML.
ParseCopyrightReplyJSON Parses the reply from the specific provider, incoming data is JSON.
ParseCopyrightReplyXML Parses the reply from the specific provider, incoming data is XML.
ParseGeocodeReplyJSON Parses the reply from the specific provider, incoming data is JSON.
ParseGeocodeReplyXML Parses the reply from the specific provider, incoming data is XML.
ParseReverseGeocodeReplyJSON Parses the reply from the specific provider, incoming data is JSON.
ParseReverseGeocodeReplyXML Parses the reply from the specific provider, incoming data is XML.
[End of this document]
Return to NetTalk Documentation Index