What's new in Version 6 Routing
VE6 released a new multi-point routing engine with customizable options that gives you much more control over generated routes than in older VE vers. The aim of this article will be to help developers who have experience with VE routing and want a comprehensive guide to the new VE6 routing features.
Generating a VE6 Route
To begin routing, pass an array of strings (representing locations) to a map.GetDirections call after loading a VE6 map. You will notice that the map.GetRoute method from VE5 is now deprecated but still useable.
map.GetDirections(["Microsoft", "Everett WA", "Bellingham WA"]);
Generating a VE6 route
The first element corresponds to the starting point and the last element of your array corresponds to the destination point. You may also want to note that you can set the destination the same as the starting point. However, the route pushpins will end up overlapping by default and the route pushpins that get plotted last will be the one on top.
A route going from “Microsoft” to “Everett, WA”, “Monroe, WA”, and finally ending in “Microsoft”
You can now provide customization options to the route by passing an instance of VERouteOptions as a parameter to the map.GetDirections method. Below is a full list of properties that you can set in this class (taken from http://msdn2.microsoft.com/en-us/library/bb877805.aspx).
|
Property
|
Description
|
|
VERouteOptions.DistanceUnit Property
|
A VERouteDistanceUnit Enumeration value specifying the units used for the route. Optional. The default value is VERouteDistanceUnit.Mile.
|
|
VERouteOptions.DrawRoute Property
|
A Boolean value specifying whether the route is drawn on the map. Optional. The default value is true, which means the route is drawn on the map.
|
|
VERouteOptions.RouteCallback Property
|
The name of the function called when the method has generated the route. Optional. The default value is null. The called function receives a VERoute Class object.
|
|
VERouteOptions.RouteColor Property
|
The VEColor Class object specifying the color of the route line. The default value is default is VEColor(0,169,235,0.7).
|
|
VERouteOptions.RouteOptimize Property
|
A VERouteOptimize Enumeration object specifying how the route is optimized. Optional. The default value is VERouteOptimize.Default, which means the route is calculated in the order in which the locations are specified.
|
|
VERouteOptions.RouteWeight Property
|
The thickness, in pixels, of the route line. The default value is 6 pixels.
|
|
VERouteOptions.RouteZIndex Property
|
The z-index of the route line. The default value is 4.
|
|
VERouteOptions.SetBestMapView Property
|
A Boolean value specifying whether the map view is set to the best view of the route after it is drawn. Optional. The default is true, which means that the map view is set.
|
|
VERouteOptions.ShowDisambiguation Property
|
A Boolean value specifying whether a disambiguation dialog box is shown. Optional. The default value is true, which means the disambiguation dialog box is shown. If false, no disambiguation dialogs are displayed and the route uses the first geocoded response for each location.
|
|
VERouteOptions.ShowErrorMessages Property
|
Whether to show any error messages. The default value is true.
|
Important improvements are the ability to modify the route line as well as the ability to disable the disambiguation box and any error messages. The example below will generate a black route with a thickness of 20.
var options = new VERouteOptions();
options.RouteColor = new VEColor(100,100,100,0.7);
options.RouteWeight = 20;
map.GetDirections(["Microsoft", "Everett WA", "Monroe, WA","Microsoft"], options);
A Route using customized polylines
Using the VE6 Route Callback
You set your callback function inside the VERouteOptions object. Consuming the route generated by map.GetDirections in the callback function is different from the VE5 map.GetRoute method. In my previous article “
Customizing Route Pushpins in V5”, we discussed a workaround that uses the map._dm object to re-generate the route using the route cache with customized pushpins. Now with VE6 the route cache no longer needs to be manipulated as all the necessary information exists inside the VERoute being returned in the callback function set inside the VERouteoptions object.
To begin, pass the callback function name to the VERouteOptions.RouteCallback property. As usual, an instance of VERoute will get passed to the callback function.
The returned VERoute has an array of VERouteLeg instances within it. A VERouteLeg is a segment of the route. Therefore a route without any stops will have one VERouteLeg while a route that goes through a location will have two VERouteLegs. Each VERouteLeg contains all the stops/turns required to reach its end point specified within a VERouteItinerary object. Within each VERouteItinerary contains the VELatLong and VEShape for that location.
Also to note, the StartLocation of the first VERouteItinerary is the start flag and also the first item in the VERouteItinerary array. The same applies to the last element in the VERouteItinerary to the end flag. In addition the route pushpins are now properly inserted into VEShapes.
A VERoute object returned in the callback function for VE6
Here is a brief summary of what needs to be done if you wish to customize the route pushpins in VE6
- Remove all of the auto-generated route pushpins
- Iterate through each VERouteLeg, adding pushpins at each item in the VEItinerary array
You can find sample code of a customized route using VE6 here
Concluding Remarks
VE6 routing provides more customization options to the route and also removes the need to use hacks to customize the route pushpins. Some routing limitations that hopefully will be addressed are having multiple routes on the map and showing route lines while in birds eye view.
Article contributed by Derek Chan (www.infusion.com). Have you got something to contribute?