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.
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.
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.
_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 | Description |
|---|
| 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 )
Structures
| NetMapMarkerQueueType |
|---|
| Field | 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) | The 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) | 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. |
| Title (string) | A title for the info box associated
with this marker. |
| Description (string) | 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) | The 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 then 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 | Description |
|---|
AddressQueue
&NetMapAddressQueueType |
A queue of addresses returned after doing a
GetAutoComplete command. |
| AutoCompleting | 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)
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. |
Return Value
The method returns nothing.
See Also
AutoCompleteFound
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. |
NotesTypically 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. |
NotesTypically 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. |
NotesIf 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>)
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. |
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>)
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. |
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>)
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. |
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)
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>)
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. |
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>)
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 | PProvider 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. |
Example
free(net.WaypointsQueue)
net.WaypointsQueue.StartPoint = true
net.WaypointsQueue.EndPoint = true
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')
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. |
NotesIf 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 text is not displayed in the info
box. |
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
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
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. |
