Map Control

Map Control

Windows Live

Map Control

This topic describes the parameters and default values created when you add the Map control to enable Virtual Earth map functionality on a Web page.

Syntax

<ve:Map 
   ID="Map1" 
   Height=height 
   Width=width 
   ZoomLevel=zoomlevel 
/>

Parameters

The parameters shown in the syntax section and in the beginning of the parameters table are the parameters created when dragging the control from the Toolbox and dropping it on a Web page. The default values in the description are also those created when dragging the control from the Toolbox and dropping it on a Web page.

Parameter	Description
ID	Required. The unique identifier for the control on the Web page. The default value is Map1.
Height	Optional. The height of the control on the Web page. The default value is 400px.
Width	Optional. The width of the control on the Web page. The default value is 400px.
ZoomLevel	Optional. The zoom level of the map on the Web page. The default value is 4.
Altitude	Optional. The altitude, in meters.
Center-Latitude	Optional. The latitude, in degrees, of the center of the map. The allowed range is from -90 (south pole) to 90 (north pole). The default value is 40.
Center-Longitude	Optional. The longitude, in degrees, of the center of the map. The allowed range is from -180 to 180. The default value is -104.
ClearInfoBoxStyles	Optional. Whether to clear any style settings for the information boxes. If true, the styles are cleared. The default value is false.
ClientToken	Optional. The unique client token from the Virtual Earth Platform service. Used to enable paid features and also track usage the token is received server side from the Virtual Earth Platform Web service. The default value is empty (""). Client tokens are required to get traffic information.
DashBoard	Optional. Whether to display the dashboard. If true, the dashboard is shown. The default value is true.
DashBoardSize	Optional. The size of the dashboard, if displayed. The allowed values are Tiny, Small, and Normal. The default value is Normal.
DisambiguationDialog	Optional. Whether to show the default disambiguation dialog is displayed when multiple results are returned from a location query. If true, the disambiguation dialog is displayed. The default value is true.
EnableShapeDisplayThreshold	Optional. Whether shapes are drawn below a threshold zoom level. If true, shapes are drawn below the threshold level. The default value is false.

Note:
As with any control, the Map control parameters can be retrieved or set in server-side code and retrieved in client-side code. What makes the Map control special is that these parameters also can be set in client-side code. The only additional work required is if you update the look of the control, remember also to update the DOM.

Events

The Map control can raise both server and client events. Server events occur after client events and are handled in server-side code that you write for the Web page. Client events are handled in client script, typically ECMAScript (JavaScript), and are raised before server events. The server-side events are triggered even if client-side events are not present.

Event	Designation: Server or Client	Description
OnClientChangeMapStyle	Client	Raised when the map style is changed
OnClientChangeView	Client	Raised when the map view is changed
OnClientEndPan	Client	Raised when a pan of the map ends
OnClientEndZoom	Client	Raised when a zoom of the map ends
OnClientFind	Client	Raised when a particular result is selected from multiple results in the Disambiguation dialog
OnClientGetDirections	Client	Raised when the route is rendered on the map
OnClientLoadMap	Client	Raised when the map is loaded
OnClientModeNotAvailable	Client	Raised when the map mode fails to change to 3D mode
OnClientObliqueChange	Client	Raised when the when the bird's eye image is changed, such as when the map is displaying a bird's eye image and that image is changed
OnClientObliqueEnter	Client	Raised when bird's eye images are available at the center of the current map
OnClientObliqueLeave	Client	Raised when bird's eye images are no longer available at the center of the current map

Handling Client Events

Client events are handled as JavaScript functions that are declared within a <script> tag. All JavaScript event handling functions must have the same signature, where OnClientEventHandler is the name of the JavaScript function that handles the event.

JavaScript Syntax

function OnClientEventHandler (sender, args)

Parameters

Parameter	Description
sender	The DOM element raising the event.
args	The event arguments object. This object has the methods `get_cancel` and `set_cancel`.

Remarks

Use the set_cancel method to cancel the execution of the associated server event.

Handling Server Events

Server events are handled as C# methods within the main class. All but one C# event handling method must have the same signature, where OnServerEventHandler is the name of the C# method that handles the event.

The exception is the handler for the OnServerChangeMapStyle event, which takes a MapEventArgs object for the second argument.

C# Syntax

protected void OnServerEventHandler(object sender, EventArgs e)

Parameters

Parameter	Description
Sender	The Map control object.
e	The event arguments object.

Remarks

Server-side event handlers often use classes, such as the MapEventArgs class, from the Microsoft.Live.ServerControls.VE namespace. Therefore, the file in which these event handlers are defined should contain the following using statement:

using Microsoft.Live.ServerControls.VE;