Bing Maps Concepts
(formerly Virtual Earth)
Mike Garza   
VEMaps@garzilla.net   

   
Concept:Bing Maps v7 Modules - Shape Toolbox Module


The previous example outlined how to implement the Drag Handle Module that allowed you to edit a given shape on the map. The Drag Handle module was my first attempt at writing a Bing Maps Module and having gone through that process, I can see how this framework is a great means of implementing functionality for your mapping applications.

That being the case, I decided to write another module for Bing Maps and this article is going to discuss just that. Since the first module involved editing shapes, it seemed that the logical progression would be to have a module that allowed you to add shapes to the map. The Shape Toolbox Module is an easy way to add drawing capabilities. Simply by loading the module in your map and activating it, you can add polylines, polygons, rectangles, circles and push pins to your map. Additionally, once the shapes have been added to the map, you can edit those shapes to fine tune them.

The map in this example has the Shape Toolbox Module loaded. There are two buttons at the bottom of the map that will show and hide the Shape Toolbox. When the Shape Toolbox is activated, it appears in the upper right hand corner of the map. Click on a button for a given shape and start drawing that shape on the map. For polyline and polygons, click as many points as needed and either double click or hit escape to exit drawing mode. For rectangles and circles, click on the starting point and move the mouse to the ending point and click a second time to complete the shape. For push pins, just click on as many locations as needed.

Once you have your shapes on the map, you can edit any of the shapes. Click on a given shape and drag handles will appear. Move the drag handle to the desired location and the shape will be updated. Hit escape to exit edit more. For push pins, just drag the push pin to the new location. Note: you can only edit one shape at a time.

Before we walk through the implementation, I just wanted to recognize Ricky Brundritt for his efforts on this module. Ricky spent a lot of time, during the development of this module, reviewing the functionality and providing feedback. His efforts certainly helped guide this module to where it is now. Thanks Ricky!

Walk Through:

The implementation of this module is pretty simple and just follows the normal pattern for implementing modules. All of the logic for the toolbox, drawing functionality and editing functionality is encapsulated in the module itself. There is no additional logic needed in your mapping application, as far as the drawing/editing is concerned.

To implement the Shape Toolbox Module, first add the map to your page in the typical fashion. Once the map has been initialized, you will need load the Shape Toolbox Module. The implementation is as follows:

	// Register and load a new module
	Microsoft.Maps.registerModule("ShapeToolboxModule", "your-path-to-the/ShapeToolboxModule.js");
	Microsoft.Maps.loadModule("ShapeToolboxModule", { callback: myModuleLoaded });
	
First the module is registered by passing module key name and the module URL/script name to the registerModule method in the Bing Maps API. Once that has been done, the module is loaded via the loadModule method in the Bing Maps API using the previously defined key name. Also as part of the loadModule process, a call back function (myModuleLoaded) is specified to be executed once the module has loaded.

The call back function is executed once the module has completely loaded. This provides an opportunity to initialize the module and prepare it for use. For the Shape Toolbox Module, the implementation is as follows:

	//Callback function for loaded module
	function myModuleLoaded() {
		myToolbox = new ShapeToolboxModule(map);
	}
	
In this function, the variable "myToolbox" is assigned a new instance of the Shape Toolbox Module (shapeToolboxModule). An instance of the current map is passed in the construction method, so that the Shape Toolbox Module has a reference to map that it is interacting with. Additionally, there is a second optional parameter for all of the supported options for the map. The options allow you to configure the look and feel of the Shape Toolbox as well we the shapes that are being drawn. These options will be outline later in this article.

Once the map has been instantiated, all that remains is to decide when to show and hide the Shape Toolbox. There are two methods in the Shape Toolbox Module and they are as follows:

	//Show the Shape Toolbox
	myToolbox.show();
	 
	//Hide the Shape Toolbox
	myToolbox.hide();
	
These are pretty straight forward and work as you would expect. Use “show()” to activate the ShapeToolbox and “hide()” to deactivate the Shape Toolbox.

That is pretty much all there is to it. Everything else is encapsulated in the Shape Toolbox Module itself. As mentioned previous, there you can configure the look and feel of the module with an optional parameter in the construction method. The options parameter follows a JSON format and supports the following properties:

Options:

Property Default Description
targetLayer map.entities Default layer to add shapes
maskStrokeColor Microsoft.Maps.Color(200, 100, 100, 100) Line color of shape mask
maskFillColor Microsoft.Maps.Color(000, 000, 000, 000) fill color of shape mask (polygon only)
maskStrokeThickness 2 line width of shape mask
maskStrokeDashArray 2 2 dash pattern of shape mask
shapeStrokeColor Microsoft.Maps.Color(200, 0, 0, 200) Line color of shape
shapeStrokeThickness 2 line width of shape
shapeFillColor Microsoft.Maps.Color(100, 000, 100, 000) fill color of shape (polygon only)
toolBarPolygonIcon your-path-to/polygonIcon.png Icon for polygon
toolBarPolygonHoverIcon your-path-to/polygonHoverIcon.png Hover icon for polygon
toolBarPolygonActiveIcon your-path-to/polygonActiveIcon.png Active icon for polygon
toolBarPolylineIcon your-path-to/polylineIcon.png Icon for polyline
toolBarPolylineHoverIcon your-path-to/polylineHoverIcon.png Hover icon for polyline
toolBarPolylineActiveIcon your-path-to/polylineActiveIcon.png Active icon for polyline
toolBarPushPinIcon your-path-to/pushpinIcon.png Icon for push pin
toolBarPushPinHoverIcon your-path-to/pushpinHoverIcon.png Hover icon for push pin
toolBarPushPinActiveIcon your-path-to/pushpinActiveIcon.png Active icon for push pin
toolBarRectangleIcon your-path-to/rectangleIcon.png Icon for rectangle
toolBarRectangleHoverIcon your-path-to/rectangleHoverIcon.png Hover icon for rectangle
toolbarRectangleActiveIcon your-path-to/rectangleActiveIcon.png Active icon for rectangle
toolbarCircleIcon your-path-to/circleIcon.png Icon for circle
toolbarCircleHoverIcon your-path-to/circleHoverIcon.png Hover icon for circle
toolbarCircleActiveIcon your-path-to/circleActiveIcon.png Active icon for circle
DragHandleImage your-path-to/DragHandleWhite.gif Image for default drag handle
DragHandleImageActive your-path-to/DragHandleGreen.gif Image for active drag handle
DragHandleImageHeight 10 Default/active drag handle image height
DragHandleImageWidth 10 Default/active drag handle image width
DragHandleImageAnchor Microsoft.Maps.Point(5, 5) Anchor Point for drag handle image
shapeMaskStrokeColor Microsoft.Maps.Color(200, 100, 100, 100) Line color of shape mask
shapeMaskFillColor Microsoft.Maps.Color(000, 000, 000, 000) fill color of shape mask (polygon only)
shapeMaskStrokeThickness 2 line width of shape mask
shapeMaskStrokeDashArray 2 2 dash pattern of shape mask

Specifying and one of these parameters will override the default behavior and implement the look that best suits your application.

Wrap-up:

As you can see, the implementation of the Shape Toolbox Module is fairly simple and straight forward. The Shape Toolbox Module is a nice way to add drawing/editing features to your mapping application when needed. All of the functionality needed for drawing and editing shapes is packaged up in this module and the implementation in your mapping application does not require any complex code.

This is just the first version of this module and there is a lot of opportunity to improve and extend this framework to make it more feature rich. Again, thank to Ricky Brundritt for his help on this first version of the Shape Toolbox Module.

As always, feedback, comments or questions are welcome. I look forward to hearing from you.

Return to Home Page

©2007-2017, Mike Garza, All Rights Reserved