Extended Nomads Objects -- Google Maps Interface v10
From PxPlus
PxPlus supports Extended Controls that allow you to access external features, such as the Google Maps API, in a Nomads or iNomads environment. PxPlus Extended Controls are available through the Nomads COM interface, allowing you to select from a list of PVX Controls in addition to the list of Activex Controls when selecting a COM Control Name in the Nomads Designer. The remainder of the Nomads definition and processing is identical to that of a COM control. However, unlike most other COM controls, extended controls are also supported by iNomads.
A Google Maps interface using Google Maps API V3 is one of the extended controls added to PxPlus. Google Maps is a web mapping service application and technology provided by Google Inc., so access to the internet is a requirement to use the service. The PxPlus Google Maps extended control offers access to a wide range of features available in the Google Maps API,including map-related properties, methods and events, marker and info window processing, as well as geocoder functions and directions requests. A built-in link on all maps also gives the user access to the Google Maps web page and additional functionality.
| Nomads | iNomads |
|---|---|
| 
|
Please visit the Google web site to learn the terms and conditions for including maps, geocoding and other content from Google in your webpages or applications. http://code.google.com/apis/maps/terms.html
Also visit the Google web site for more information on the Google Maps API V3: http://code.google.com/apis/maps/documentation/v3/
Contact PVXPlus Technologies to inquire about incorporating additional functionality into the PxPlus Google Map extended control.
To see a Flash presentation on using the Google Map extended control, go to http://www.pvxplus.com/swf/gmaps.htm
To see a Flash presentation on making directions requests, go to http://www.pvxplus.com/swf/gdir.htm
Contents |
Using the Google Map Extended Control
Example 1 - Displaying a Map, Markers, InfoWindows and Geocoding
Use the Nomads Designer to add a Google Map to your application panel.
Select External Tools (COM control) from the Controls window and outline the location of the map on the panel.
In the Properties window, name the control; in our example we have called it MAP. Then click the COM Control Name button in the Display section and select PVX Controls from the pop-up menu. Select Google Maps Control from the list.
Click the Properties/Methods/Events button in the Display section of the Properties window.
Four properties are required when defining a map:
latitude - Latitude in degrees of the centerpoint of the map.
Range is -90 to 90 degrees.
longitude - Longitude in degrees of the centerpoint of the map.
Range wraps from -180 to 180 degrees.
mapTypeId - Type of map to be displayed.
Options are hybrid, roadmap, satellite and terrain.
zoom - Numeric zoom factor for the map. (Zero based).
Other properties are optional. Save the definition. This is sufficient to display the map on your panel, complete with map type and zoom controls, and full standard Google Map UI capability, including full mouse and keyboard control.
Now add some controls and logic to demonstrate some of the functionality available in Google Maps, such as adding and removing markers and info windows, and a demonstration of geocoding which translates human-readable addresses into latitude/longitude locations and vice-versa.
Add three multilines, address, latitude and longitude, as well as fonted-text prompts to accompany them. Set the Numeric attribute for the latitude and longitude multilines.
You will need more than standard precision to handle latitude and longitude values, so set Precision to 6 in the Display section of the panel header Properties window.
Add a Geocode_Address button, a Geocode_Location button, and a Close button to exit the panel. Set the On Change logic for the Close button to End.
Set the On Change logic for the Geocode_Address button to Execute:
location$=map.ctl'geocode$(address$); latitude=map.ctl'geocodeLatitude; longitude=map.ctl'geocodeLongitude; map.ctl'addMarker(latitude,longitude, location$) When the button is pushed, the address is passed to the geocode method which returns the latitude and longitude as a string with a comma separator. The geocoder also loads the geocodeLatitude and geocodeLongitude properties which are used here to populate the latitude and longitude multilines. A marker is then created using the given latitude and longitude, and the location is used as the marker title, which is displayed as the marker tip. | 
|
| Set the On Change logic for the Geocode_Location button to Execute:
address$=map.ctl'geocode$(latitude, longitude,0); map.ctl'showInfoWindow(latitude, longitude,address$) When the button is pushed, the latitude, longitude and level are passed to the geocode method. The level indicates how specific or general the returned address is to be, with 0 being the most specific address. The address is then displayed in an info window placed at the given latitude and longitude. |
Finally, click the Properties/Methods/Events button in the Display section of the Map Properties window. Set the markerClick event logic to Execute:
markerid=map.ctl'clickmarker; map.ctl'removeMarker(markerid) When a marker is clicked, it is removed from the map. | 
|
This examples shows just a few of the properties, methods and events available to the Google Maps Extended Control. Full details are described in the rest of this document. Also visit the Google Maps web site for additional information. http://code.google.com/apis/maps/documentation/v3/
Example 2 - Requesting Directions
Using the methodology described in the first example, create a new application panel in the NOMADS Designer and add a Google Map extended control. Call it DIRECTIONS.
Besides the four properties (latitude, longitude, mapTypeID and zoom) required to display a map, two other properties must be set in order to request directions. These are showDirectionsPane and directionsPanePercent:
showDirectionsPane - Used to enable the directions service and indicate the placement
of the directions. Values are:
0 = Directions service not enabled. (default)
1 = Directions service enabled. Directions are displayed to the left of the map.
2 = Directions service enabled. Directions are displayed to the right of the map.
directionsPanePercent - Percent (0-100) of the designated horizontal map area to be
used to display directions. If set to 0, then a default value of 30 will be used.
These properties must be set in the map definition and cannot be changed dynamically. In this example, we have set latitude=44, longitude=-79, zoom=8, and left the default setting for mapTypeId (hybrid). The showDirectionsPane property has been set to 1, to display directions to the left of the map, and directionsPanePercent has been set to 33, setting the directions display to occupy 33% of the width allotted for the map.
There are many directions-related properties.
The following properties are used as parameters for directions requests:
directionsAvoidHighways directionsAvoidTolls directionsOptimizeWaypoints directionsProvideRouteAlternatives directionsRegion$ directionsTravelMode$ directionsUnitSystem$ These properties are display options: directionsDraggable directionsHideRouteList directionsPreserveViewport directionsRouteColor$ directionsRouteColour$ directionsRoutePixels directionsRouteOpacity directionsSuppressBicyclingLayer directionsSuppressInfoWindows directionsSuppressMarkers directionsSuppressPolylines When set, the above properties will affect any subsequent directions requests; they have no effect on currently displayed directions. These properties may be set in the map definition, or any time prior to making a directions request. | 
|
A full list and description of all directions-related properties is found in #Directions Properties.
Now add some controls and logic to demonstrate how to generate directions.
Add three multilines, Origin, Stopover and Destination, as well as fonted-text prompts to accompany them. Two locations, an origin and destination, are required to request directions. These may be in the form of an address, or as latitude/longitude pairs. Addresses are used in this example. Stopover locations, or waypoints, are optional. The example has one stopover, but up to 8 are allowed (23 waypoints for Google Maps API Premier customers). Add a Get_Directions button and a Close button to exit the panel. Set the On Change logic for the Close button to End.
Set the On Change logic for the Get_Directions button to Execute:
directions.ctl'clearDirections(); directions.ctl'clearWaypoints(); if stopover$<>"" then directions.ctl'addWaypoint(1,stopover$)end_if; status$=directions.ctl'getDirections$(origin$,destination$)
When the button is pushed, any directions currently on the map are cleared, as are any waypoints that have been defined. This is necessary due to the design of the sample panel which allows mulitple directions requests for different origins, destinations and waypoints.
Then the optional waypoint is added. Waypoints are additional locations through which the calculated route must pass. In this case a single waypoint is added with 1 representing the sequence number. Multiple waypoints are possible, where, by default, the route follows the order of the waypoint sequence numbers. Also, by default, waypoints are stopover points, which divides the route into legs. You can specify that waypoints are not stopovers (addWaypoint(sequence,address,stopoverFlag) where stopoverFlag=0), in which case they are marked on the route with a dot and do not divide the route into legs. If all waypoints are stopovers, then the directionsOptimizeWaypoint property can be turned on, in which case the sequence of the waypoints is ignored and an optimal route determined.
Finally the getDirections$() method is passed the Origin and Destination, and based upon these values and previously set values, such as waypoints and the various directions-related properties, a route is drawn on the map and directions displayed in the directions pane. As well, the method returns a status to indicate whether the method was successful ("OK") or not.
Detailed descriptions of the individual directions methods can be found at #Directions Methods.
Map Properties
Following are the map-related properties supported by the PxPlus Google Maps Extended Control. The properties are set when the map is created, and are read-only (except for the value property). Their values can be changed subsequently by using the corresponding set method.
(Note: Properties relating to Directions Services are discussed separately in #Directions Properties.)
| Property | Description |
|---|---|
| backgroundColor$ | Colour used for the background of the map. This colour is visible when tiles have not yet been loaded and the user pans. Format is hex #HHHHHH (e.g. #FF00FF) or a standard HTML colour name (e.g. yellow). |
| clickLatitude | Latitude in degrees at the location where a Click or RightClick event occurs on a map. |
| clickLongitude, | Longitude in degrees at the location where a Click or RightClick event occurs on a map. |
| clickMarker | Numeric identifier of the marker involved in a MarkerClick event. |
| client | Client id for Google Maps API Premier customers. Visit the Google website for information about becoming a Premier customer. |
| col | Horizontal screen position of map in columns. |
| cols | Width of map in column units. |
| containerObject | Object id of browser object in which the map is displayed. (NOMADS only) |
| ctlName$ | Control type. Value is 'Extended'. |
| disableDefaultUI | Enables/disables all default user interface features, such as double click zoom, draggability, scrollwheel, etc. UI features may be overridden individually. Boolean. Default is false (enabled). |
| draggable | Enables/disables the ability to drag the map. Boolean. Default is true (enabled). |
| geocodeLatitude | Longitude in degrees at the location of the last invoked #Geocoder Method. |
| geocodeLongitude | Longitude in degrees at the location of the last invoked #Geocoder Method. |
| geocodeStatus$ | Status of the last invoked #Geocoder Method. |
| HTTPS | Boolean flag indicating that a secure URL is to be used to access the Google Maps JavaScript API. This is only available to Google Maps API Premier customers whose client ID has be set in the client property, and who have registered the HTTPS URL of their website with Google for use with their client ID. |
| infoWindowCount | Number of info windows currently displayed. |
| keyboardShortcuts | Enables/disables keyboard control of the map. Boolean. Default is enabled (true). |
| latitude | Latitude in degrees of the map center. Range is clamped between -90 degrees and 90 degrees. |
| longitude | Longitude in degrees of the map center. Longitude is wrapped between -180 degrees and 180 degrees. |
| mapTypeControl | Enabled/disabled state of the map type control. Boolean. Default is enabled. |
| mapTypeControlStyle$ | Display option for the map type control. Options are 'default', 'dropdown_menu' and 'horizontal_bar'. |
| mapTypeId$ | Map type. Options are 'hybrid', 'roadmap', 'satellite' and 'terrain'. Required. |
| markerCount | Number of markers currently displayed. |
| name$ | Control name. |
| navigationControl | Enabled/disabled state of the navigation control. Boolean. Default is enabled. |
| navigationControlStyle$ | Display option for the navigation control. Options are 'default', 'android', 'small' and 'zoom_pan'. The default setting varies depending on map size and other factors. |
| noClear | If true, the contents of the map are not cleared. |
| pvxError$ | Error value. |
| pvxEvents$ | List of available events. |
| region$ | Unicode region subtag identifier. Can be used to override the standard location bias. (Optional) |
| scaleControl | Enabled/disabled state of the scale control. |
| scaleControlStyle$ | Display option for the scale control. Option is 'default'. |
| scrollWheel | Enables/disables scrollwheel zooming on the map. Boolean. Default is true (enabled). |
| sensor | Indicates whether the application is using a sensor (such as a GPS locator) to determine the location. Boolean. Default is false. Required. |
| value$ |  String of value pairs that contain all the data required to define the current map. Format is a list of assignment expressions separated by $00$. e.g. "sensor=0"+$00$+ "region$="""""+$00$+ "latitude=43.77"+$00$+ "longitude=-79.4525"+$00$+ "mapTypeID$=""hybrid""+$00$+ "zoom=14"+$00$+ [etc.] An example (not showing the $00$ separators) is shown on the right. The value$ property is a read/write property. When set, the map is redisplayed using the new value settings. |
| zoom | Initial zoom level for the map. Required. |
Map Events
Following are the events supported by the PxPlus Google Maps Extended Control.
| Event | Description |
|---|---|
| click | This event is fired when the user clicks on the map. The location of the last click can be found in the clickLatitude and clickLongitude properties. |
| rightClick | This event is fired when the user right-clicks on the map. The location of the last right-click can be found in the clickLatitude and clickLongitude properties. |
| markerClick | This event is fired when the user clicks on a marker. The marker identifier can be found in the clickMarker property. |
Map Methods
Following are the map-related methods supported by the PxPlus Google Maps Extended Control.
| Method | Description |
|---|---|
| fitBounds(S,W,N,E) | Sets the map to fit the given boundaries, where:
S - Southernmost latitude in degrees. W - Westernmost longitude in degrees. N - Northernmost latitude in degrees. E - Easternmost longitude in degrees. |
| getBounds$() | Returns a string containing the southernmost latitude, westernmost longitude, northernmost latitude and easternmost longitude in degrees, separated by commas. |
| getCenter$() | Returns the latitude and longitude in degrees of the centerpoint of the map. |
| getLatitude() | Returns the latitude in degrees of the centerpoint of the map. |
| getLongitude() | Returns the longitude in degrees of the centerpoint of the map. |
| getMapTypeId$() | Returns the type of map. Types are 'roadmap', 'satellite', 'hybrid' and 'terrain'. |
| getZoom() | Returns the current zoom setting. |
| initialize(name$,properties$, methods$,events$,eventCount) | Initializes properties, methods and events used by Nomads and iNomads. |
| panBy(cols,lines) | Changes the center of the map by the given number of columns and rows. Use positive values to pan to the right or down, and negative values to pan left or up. |
| panTo(latitude,longitude) | Changes the center of the map to the given latitude and longitude. |
| setCenter(latitude,longitude) | Changes the center of the map to the given latitude and longitude. |
| setMapTypeId(type$) | Sets the map type. Options are 'roadmap', 'satellite', 'hybrid' and 'terrain'. |
| setOptions(options$) | Sets map attributes specified in options$, a list of SEP-separated values pairs, consisting of attribute names and values in the format attribute=value.
Boolean values can be specifed using 0 and -1, or true and false. Null string values can be specified by leaving the value blank. E.g. "mapTypeID=terrain"+SEP+"draggable=false"+SEP+"zoom=4"+sep+"backgroundColor="+SEP |
| setZoom(n) | Sets the zoom level of the map. |
Marker Methods
Following are the marker methods supported by the PxPlus Google Maps Extended Control.
| Method | Description |
|---|---|
| addMarker(latitude,longitude [,title$,icon$,zIndex]) | Add a marker at the specified latitude and longitude.
Returns a numeric identifier to be used when referencing the marker in marker-related methods. The following arguments are optional: Title$ - Title is displayed in the marker tip. Icon$ - URL to image to be used for the marker. zIndex - Markers are displayed in order of their zindex; those with higher values are displayed in front of those with lower values. By default, markers with lower latitudes take precedence. |
| clearMarkers() | Removes all markers from the map. |
| getMarkerClickable(markerid) | Returns a boolean value indicating whether the specified marker is clickable. |
| getMarkerDraggable(markerid) | Returns a boolean value indicating whether the specified marker is draggable. |
| getMarkerFlat(markerid) | Returns a boolean value indicating whether the specified marker is flat (i.e. has no shadow). |
| getMarkerIcon$(markerid) | Returns the URL of the image for the specified marker. |
| getMarkerLatitude(markerid) | Returns the latitude in degrees of the specified marker. |
| getMarkerLongitude(markerid) | Returns the longitude in degrees of the specified marker. |
| getMarkerPosition$(markerid) | Returns a comma-separated string containing the latitude and longitude in degrees of the specified marker. |
| getMarkerTitle$(markerid) | Returns a string containing the title of the specified marker. |
| getMarkerVisible(markerid) | Returns a boolean value indicating whether the specified marker is visible. |
| getMarkerZIndex(markerid) | Returns the zIndex of the specifed marker. (See addMarker() for an explanation of zIndex.) |
| removeMarker(markerid) | Remove the specified marker. |
| setMarkerClickable(markerid,flag) | Sets whether or not the specified marker is clickable. Flag is boolean. |
| setMarkerDraggable(markerid,flag) | Sets whether or not the specified marker is draggable. Flag is boolean. |
| setMarkerFlat(markerid,flag) | Sets whether or not the specified marker is flat. Flag is boolean.
Note - If an icon is specified, the marker will be flat. |
| setMarkerIcon(markerid, icon$) | Sets the image to be used as the specified marker.
Icon$ - URL to the image. e.g. setMarkerIcon(markerid,"file:///c:/work/images/star.bmp")
setMarkerIcon(markerid,
"http://www.google.com/mapfiles/marker"+chr(65+map.ctl'markerCount)+".png")
|
| setMarkerOptions(markerid,options$) | Sets marker attributes specified in options$ for the given marker. Options$ contains a list of SEP-separated values pairs, consisting of attribute names and values in the format attribute=value.
Boolean values can be specifed using 0 and -1, or true and false. Null string values can be specified by leaving the value blank. E.g. "draggable=true"+SEP+"title="+SEP+"+"icon=file:///work/images/star.bmp"+SEP |
| setMarkerPosition(markerid, latitude,longitude) | Move the specified marker to the given latitude and longitude. |
| setMarkerTitle(markerid,title$) | Sets the title of the specified marker. The title is displayed as the marker tip. |
| setMarkerVisible(markerid, flag) | Sets whether or not the specified marker is visible. Flag is boolean. |
| setMarkerZIndex(markerid,n) | Sets the zIndex of the specified marker. (See addMarker() for an explanation of zIndex.) |
Info Window Methods
An info window is a text bubble that can be displayed at a given location or connected to a marker. Following are the info window methods supported by the PxPlus Google Maps Extended Control.
| Method | Description |
|---|---|
| closeInfoWindow(iw_id) | Closes the info window with the specified identifier. |
| getInfoWindowContent$(iw_id) | Returns the text content of the info window with the specified identifier. |
| getInfoWindowLatitude(iw_id) | Returns the latitude in degrees of the info window with the specified identifier. |
| getInfoWindowLongitude(iw_id) | Returns the longitude in degrees of the info window with the specified identifier. |
| getInfoWindowPosition$(iw_id) | Returns a comma-separated string specifying the latitude and longitude in degrees of the info window with the specified identifier. |
| setInfoWindowContent(iw_id,content$) | Sets the content to be displayed in the specified info window. This can be a plain-text string or a string containing HTML. |
| setInfoWindowPosition(iw_id,lat,lng) | Moves the info window with the specified identifier to the indicated latitude and longitude. |
| showInfoWindow(lat, lng, content$ [,zIndex, disableAutoPan])
showInfoWindow(markerid, contents$ [,zIndex, disableAutoPan]) | Displays an info window with the given content at the specified latitude and longitude, or at the marker with the specified identifier. Returns a numeric identifier to be used when referencing the info window in info window-related methods.
Optional arguments include: zIndex - Info windows are displayed in order of their zindex, with higher values displaying in front of info windows with lower values. By default, info windows with lower latitudes take precedence. disableAutoPan - Disables the default auto-pan behaviour that makes the info window fully visible when it is initially displayed. |
Geocoder Method
Geocoding is the process of converting human-readable addresses (like "42 Scenic Drive, Yourtown, ON") into geographic coordinates (like latitude 44.123456 and longitude -79.654321), which you can use to place markers or position the map. The process of translating a location on a map to a human-readable address is known as reverse geocoding. Both processes are available using the two formats of the geocode$( ) method.
| Method | Description |
|---|---|
| geocode$(address$) | Given a human-readable address, returns a string containing the corresponding latitude and longitude in degrees, separated by a comma. The resulting latitude and longitude are also loaded into the geocodeLatitude and geocodeLongitude properties. |
| geocode$(lat,lng,level) | Given a latitude, longitude and level, returns the corresponding human-readable address. The level indicates how specific or general the resulting address will be, with 0 being the most specific. (Note that the geocoder will attempt to find the closest addressable location, within reason. If none exists, a null string is returned.) |
Directions Properties
Following are the directions-related properties supported by the PxPlus Google Maps Extended Control. All properties are read-only, except for showDirectionsPane and directionsPanePercent, and can be set using their corresponding set methods, described in #Directions Methods. When the properties are set, they will affect the next directions request; they will have no effect on the current direction results.
| Property | Description |
|---|---|
| directionsAvoidHighways | When set to non-zero, major highways are avoided where possible when the route is calculated. Boolean value. Default is off (0). |
| directionsAvoidTolls | When set to non-zero, toll roads are avoided where possible when the route is calculated. Boolean value. Default is off (0). |
| directionsDestination$ | Contains the address of the destination used in the last directions request. Set to null if the last request used latitude/longitude values to specify the location of the destination. |
| directionsDestinationLatitude | Contains the latitude of the destination used in the last directions request. Set to 0 if the last request used an address to set the location of the destination. |
| directionsDestinationLongitude | Contains the longitude of the destination used in the last directions request. Set to 0 if the last request used an address to set the location of the destination. |
| directionsDraggable | When set to non-zero, the user will be able to dynamically modify directions by clicking and dragging the paths on the map. Boolean value. Default is off (0). |
| directionsHideRouteList | When set to non-zero, the route list in the directions pane that is displayed when alternate routes are calculated is suppressed, i.e. when the directionsProvideRouteAlternatives property is turned on. Boolean value. Default is off (0). |
| directionsOptimizeWaypoints | When this property is set to non-zero and all waypoints are classified as stopovers, the waypoint sequence is overridden and the optimum route through the waypoints is determined. Boolean value. Default is off (0). |
| directionsOrigin$ | Contains the address of the origin used in the last directions request. Set to null if the last request used latitude/longitude values to specify the location of the origin. |
| directionsOriginLatitude | Contains the latitude of the origin used in the last directions request. Set to 0 if the last request used an address to set the location of the origin. |
| directionsOriginLongitude | Contains the longitude of the origin used in the last directions request. Set to 0 if the last request used an address to set the location of the origin. |
| directionsPanePercent | Percent (0-100) of the designated horizontal map area to be used to display directions. If set to 0, then a default value of 30 will be used.
This property must be set in the map definition and cannot be changed subsequently. |
| directionsPreserveViewport | When set to non-zero, the current map viewport is maintained when directions are displayed, rather the viewport being adjusted to center and display the entire route. Boolean value. Default off (0). |
| directionsProvideRouteAlternatives | When set to non-zero, alternate routes may be calculated. Setting this property may slow down response time, and multiple routes are not guaranteed. |
| directionsRegion$ | Region code. Used for biasing results to a particular region. |
| directionsRouteColor$
directionsRouteColour$ | Colour of the route displayed on the map. Can be a standard ProvideX colour (e.g. Light red, Dark blue, etc.) or an RGB value (e.g. RGB:192 0 255) |
| directionsRouteOpacity | Opacity of route displayed on the map, between 0.0 and 1.0. |
| directionsRoutePixels | Width of the route displayed on the map in pixels. Range is 0 to 10. |
| directionsSuppressBicyclingLayer | When set to non-zero, the rendering of the Bicycling layer is suppressed when bicycling directions are requested. Boolean value. Default is off (0). |
| directionsSuppressInfoWindows | When set to non-zero, the rendering of Info windows is suppressed . Boolean value. Default is off (0). |
| directionsSuppressMarkers | When set to non-zero, the display of markers on the route is suppressed. Boolean value. Default is off (0). |
| directionsSuppressPolylines | When set to non-zero, the line that marks the route is not displayed. Boolean value. Default is off (0). |
| directionsTravelMode$ | Type of transportation mode. Options are 'driving', 'walking' and 'bicycling'. If not specified, the default id 'driving'. |
| directionsUnitSystem$ | Unit system to be used in the directions result. Options are 'default' (or null), 'metric' and 'imperial'. By default, the unit system of the origin's country or region is used; therefore a route from Toronto, Canada to Buffalo, NY would use metric units, while a route from Buffalo to Toronto would use imperial units. Specifically setting the unit system to metric or imperial will override this behaviour. |
| routeCount | The number of routes calculated in the directions result. Normally this is 1, unless the directionsProvideRouteAlternatives property is turned on. |
| showDirectionsPane | Used to enable the directions service and indicate the placement of the directions.
Values are: 0 = Directions service not enabled. (default) 1 = Directions service enabled. Directions are displayed to the left of the map. 2 = Directions service enabled. Directions are displayed to the right of the map. This property must be set in the map definition and cannot be changed subsequently. |
| waypointCount | Number of waypoints that have been added to the directions request. The maximum number of waypoints may vary. The standard number is 8, while the maximum for Google Maps API Premier developers is 23. |
Directions Methods
Following are the directions-related properties supported by the PxPlus Google Maps Extended Control.
| Method | Description |
|---|---|
| addWaypoint(sequence,address,[stopover])
addWaypoint(sequence,lat,lng,[stopover]) | Adds a waypoint on the route to be requested. Waypoints are additional locations through which the calculated route must pass. The location may be specified as an address or using latitude/longitude settings.
By default, waypoints are stopover points, which divides the route into legs. You can specify that a waypoint is not a stopover by setting the optional stopover flag to zero (0), in which case its location is marked on the route with a dot and it does not divide the route into legs. A sequence number must be specified when adding waypoints, where the route would follow the order of the sequence numbers. Gaps in sequence numbers are allowed. A sequence number of zero (0) can be used to assign the waypoint to the first available sequence number. Sequence number order can be overridden if all waypoints are stopover points and the directionsOptimizeWaypoints property is turned on, in which case the order of the sequence numbers is ignored and an optimal route through the waypoints determined. There is no maximum to the number of waypoints you may add using this method, however the Google Maps API limits the maximum number of waypoints for a standard user to 8, and 23 for Google Maps API Premier customers. If you add more than the allowed number of waypoints then the directions request will fail when the getDirections$() method is invoked, i.e. the directions will not be displayed on the map, and the return status of the getDirections$() method will contain the value "MAX_WAYPOINTS_EXCEEDED". Returns the sequence number. |
| clearDirections() | Clears the directions display from the map and directions pane. Does not affect any directions-related properties or defined waypoints. |
| clearWaypoints() | Clears all waypoints that have been defined. |
| getDirections$(originAddress$,destinationAddress$)
getDirections$(originLat,originLng,destLat,destLng) getDirections$() | Based upon the specified origin and destination, as well as pre-defined waypoints and directions-related properties, this method calculates and draws the route, markers, etc. on the map and displays directions in the directions pane. If the origin and destination are omitted, then the origin and destination of the last directions request are used.
Returns one of the following statuses:
|
| getDirectionsCalculatedWaypointOrder([route,] originalPosition) | Given a waypoint's original position in the waypoint order, this method returns the position in the waypoint order after the route is calculated. Waypoint order my be altered due to route optimization (see the directionsOptimizeWaypoints property.) |
| getDirectionsHTML$() | Returns the current HTML contents of the directions pane. |
| getDirectionsLegCount([route]) | Returns the number of legs in a route. The number of legs is dependent on the number of waypoints, and whether a waypoint has been classified as a stopover. A route with no stopovers has one leg; a route with 1 stopover has two legs, etc. If the directionsProvideRouteAlternatives property has been turned on, you can specify a route number, where the primary route number is one (1). |
| getDirectionsLegDistance([route,] leg) | Returns the distance of the specified leg number in meters (regardless of the directionsUnitSystem$ setting). |
| getDirectionsLegDuration([route,] leg) | Returns the duration of the specified leg number in seconds. |
| getDirectionsLegStartLatitude([route,] leg) | Returns the latitude of the starting location of the specified leg. Default route is the primary route (1). |
| getDirectionsLegStartLongitude([route,] leg) | Returns the longitude of the starting location of the specified leg. Default route is the primary route (1). |
| getDirectionsLegEndLatitude([route,] leg) | Returns the latitude of the ending location of the specified leg. Default route is the primary route (1). |
| getDirectionsLegEndLongitude([route,] leg) | Returns the longitude of the ending location of the specified leg. Default route is the primary route (1). |
| getDirectionsOriginalWaypointOrder([route,] calculatedPosition) | Given a waypoint's position in the waypoint order after a route has been calculated, this method returns the original position in the waypoint order before the route was calculated. Waypoint order my be altered due to route optimization (see the directionsOptimizeWaypoints property.) |
| getDirectionsRouteDistance([route]) | Returns the total route distance in meters (regardless of the directionsUnitSystem$ setting). If the directionsProvideRouteAlternatives property has beens turned on, then you can specify a route number for the distance of the alternate routes. The primary route number is one (1). |
| getDirectionsRouteDuration([route]) | Returns the total route duration in seconds. If the directionsProvideRouteAlternatives property has been turned on, then you can specify a route number for the duration of alternate routes. The primary route number is one (1). |
| getDirectionsText$()
getDirectionsText$(route) getDirectionsText$(route,leg) | Returns directions for the route in plain text format.
If the directionsProvideRouteAlternatives property has been turned on, then you can specify a route number for alternate routes. The primary route number is one (1). If route and leg numbers are specified, the text for that just that leg is returned. |
| getWaypointAddress$(sequence) | Returns the address of the waypoint with the specified sequence, if that waypoint was added using an address. The address is null if the waypoint was added using a latitude/longitude location. |
| getWaypointLatitude(sequence) | Returns the latitude of the waypoint with the specified sequence, if that waypoint was added using a latitude/longitude location. The latitude is 0 if the waypoint was added using an address as its location. |
| getWaypointLongitude(sequence) | Returns the longitude of the waypoint with the specified sequence, if that waypoint was added using a latitude/longitude location. The longitude is 0 if the waypoint was added using an address as its location. |
| getWaypointStopover(sequence) | Returns the value of the stopover flag for the waypoint with the specified sequence. |
| removeWaypoint(sequence) | Removes the waypoint with the specified sequence number. If the removal of a waypoint results in a gap in the sequence, then that sequence number is skipped when directions are requested. |
| setDirectionsAvoidHighways(flag) | Sets the option to avoid major highways where possible when the route is calculated. Flag is boolean. |
| setDirectionsAvoidTolls(flag) | Sets the option to avoid toll roads where possible when the route is calculated. Flag is boolean. |
| setDirectionsDraggable(flag) | Sets the option to allow the user to dynamically modify directions by clicking and dragging the paths on the map. Flag is boolean. |
| setDirectionsHideRouteList(flag) | Sets the option to suppress the route list in the directions pane that is displayed when alternate routes are calculated, i.e. when the directionsProvideRouteAlternatives property is turned on. Flag is boolean. |
| setDirectionsOptimizeWaypoints(flag) | Sets the option to override the waypoint sequence and determine the optimum route through the waypoints. Flag is boolean. |
| setDirectionsPreserveViewport(flag) | Sets the option to maintain the current map viewport when directions are displayed, rather than adjusting the viewport to center and display the entire route. Flag is boolean. |
| setDirectionsProvideRouteAlternatives(flag) | Sets the option to calculate alternate routes. Setting this property may slow down response time, and multiple routes are not guaranteed. Flag is boolean. |
| setDirectionsRegion(code$) | Sets the region code which is used for biasing results to a particular region. |
| setDirectionsRouteColor(color$)
setDirectionsRouteColour(colour$) | Sets the colour of the route displayed on the map. Colour$ can be a standard ProvideX colour (e.g. Light red, Dark blue, etc.) or an RGB value (e.g. RGB:192 0,255). When setting the route colour, standard route width (pixels) and opacity are reset, so you may want to set these as well. |
| setDirectionsRouteOpacity(opacity) | Sets the opacity of route displayed on the map. Valid opacity values are between 0.0 and 1.0. |
| setDirectionsRoutePixels(pixels) | Sets the width of the route displayed on the map in pixels. Range is 1 to 10. |
| setDirectionsSuppressBicyclingLayer(flag) | Sets the option to suppress the rendering of the Bicycling layer when bicycling directions are requested. Flag is boolean. |
| setDirectionsSuppressInfoWindows(flag) | Sets the option to suppress the rendering of info windows. Flag is boolean. |
| setDirectionsSuppressMarkers(flag) | Sets the option to suppress the placement of markers when a route is displayed. Flag is boolean. |
| setDirectionsSuppressPolylines(flag) | Sets the option to suppress the the line that marks the route. Flag is boolean. |
| setDirectionsTravelMode(mode$) | Sets the type of transportation mode. Options are 'driving', 'walking' and 'bicycling'. If not set, default is 'driving'. |
| setDirectionsUnitSystem(unit$) | Sets the unit system to be used in the directions result. Options are 'default' (or null), 'metric' and 'imperial'. By default, the unit system of the origin's country or region is used; therefore a route from Toronto, Canada to Buffalo, NY would use metric units, while a route from Buffalo to Toronto would use imperial units. Specifically setting the unit system to metric or imperial will override this behaviour. |
