Overview
MapToolset is a server control that is used to display a set of image buttons. Buttons can be removed from or added to the toolset. They can be displayed vertically or horizontally and can be divided into columns or rows. These buttons are generally tied to mapping functions although user-defined buttons could be tied to any behavior.
MapToolset should be used in a page that inherits from
MDNAjaxPage. The page should have a
MapControlBridge control as well. The MapToolsetID property of the
MapControlBridge should be set to the ID of the MapToolset. The
MapControlBridge should also have an associated
MapNavigator control. This provides out-of-the-box functionality for a standard set of toolbox buttons.
Types of Buttons
Buttons come in two types.
"Mode" buttons place the map in a state where mouse actions on the map result in different actions. For instance, in "Zoom In" mode, holding the mouse on the map and dragging displays a rectangle and when the mouse is released the map zooms to the area of the rectangle whereas in "Recenter" mode the same actions move the image within the borders of the
MapNavigator and then pan the map to the new position, filling in the empty space exposed by dragging the map image. Mode buttons stay depressed once they are clicked to indicate the mode in effect.
"Command" buttons execute a function once, such as zooming the map to its initial extents or printing the map. They do not change how the map responds to mouse actions. Command buttons do not stay depressed. The current mode button remains depressed after a command button is clicked.
Buttons can also be set to post back rather than to use Ajax. Standard buttons used within an
MDNAjaxPage never post back but it may sometimes be useful for a user-defined button to post back.
Configuration
Begin by adding the control to the page. Set the MapToolsetID property of the
MapControlBridge to the ID of the control.
When first added the toolset will look like this:
There are numerous properties that can be configured. Some important ones are "Orientation", which can be set to "Horizontal" or "Vertical"; "ImagesSubfolder", which is the location where button images are saved to; "ButtonAlign" or "ButtonVAlign" to change how buttons lay out when there are multiple rows or columns; and "BackColor", which sets the color for buttons as well as for the control as a whole. Note that changing "BackColor", "ToolsetButtonSize", or "ImagesSubfolder" will trigger regeneration of the standard buttons. See
DIGS for how to get the system to regenerate your custom buttons for you.
Click "Configure Toolset Buttons" to add, remove, or hide buttons and to add or remove spacers and row or column breaks.
Click "Remove" to remove the selected item. Use "Up" and "Down" to reorder by moving the selected button. Click "Add" and then select "Add Button", "Add Separator", or "Add Break". (Note how the existing separators and breaks affect the layout of the toolset as seen above.)
All three types of items have a "Visible" property and an "ID". Set "Visible" to false to hide a button, break, or separator without actually removing it. Only buttons will display the other properties visible in this screen shot. "ModeStatusText" is only useful if the MapToolset's "ModeStatusLabel" property is set. If there is a ModeStatusLabel, it will display the ModeStatusText for the selected mode rather than the CommandName if ModeStatusText has content.
Out-of-the-Box Functionality
Used in an
MDNAjaxPage, the following buttons have out-of-the-box support:
"Zoom In"
"Zoom Out"
"Zoom All"
"Recenter"
"Draw Polygon"
"Draw Point"
"Draw Polyline"
"Draw Rectangle"
"Draw Circle"
"Draw Text"
(displays "test" unless MDNAjaxPage.GetTextForDraw is overridden)"Clear All"
"Selection Rectangle"
"Selection Circle"
"Selection Polyline"
"Selection Polygon"
"Print Map"
(calls "window.print()" unless a MapPrintManager is configured, if so, prints default template)
Support for the following mode buttons is limited to placing the map in an appropriate mouse mode:
"Delete Shapes" (Envelope drag support.)
"Edit Shape" (Point click support.)
"Identify" (Point click support.)
"Show Position" (Point click support.)
Extending Functionality
For an existing mode button, you can extend or replace the built-in functionality by extending the
MDNAtlasPage's ProcessMapUnitCoordinates method. This would use code similar to the following
protected override MapClientStateUpdate ProcessMapUnitCoordinates( Multipoint mp, string mode )
{
if (Mcb != null &&
!Mcb.IsSessionTimedOut &&
Mcb.MapNavigatorControl != null &&
mp != null)
{
// use persisted drawing mode if not provided to this web method
if (mode == null || mode.Trim().Length < 1)
{
mode = Mode;
}
if (mode.ToLower() == "my target mode")
{
// user customizable map point preprocessing
// only necessary if you have overridden PreProcessMapUnitCoordinates
mp = PreProcessMapUnitCoordinates(mp);
// get MapNav submitted envelope if available
// only necessary for Envelope drag modes
Envelope env = null;
if (mp.Count > 1)
{
env = new Envelope(mp[0], mp[1]);
}
// do what you need to do
// ...
}
else
{
return base.ProcessMapUnitCoordinates(mp, mode);
}
}
// update mapstate response information
LoadMapClientStateUpdate();
// return response object
return MapClientStateUpdate;
}
For a new mode button or a new or unsupported command button, extend the
MDNAtlasPage's ProcessMapUnitCoordinates method.
[ScriptMethod]
public override MapClientStateUpdate WMMapToolsetButtonClick(string buttonCommandName, string drawMode, MapClientState clientState)
{
if (Mcb != null && !Mcb.IsSessionTimedOut)
{
// an error state, let the base handler deal with it
return base.WMMapToolsetButtonClick(buttonCommandName, drawMode, clientState);
}
if (buttonCommandName == "My Target Mode")
{
// update persisted mode to match the mode button selected
Mcb.MapToolsetControl.TBMode = Mode = buttonCommandName;
// Not case sensitive.
// Valid options are "None", "Envelope", "Polyline", "Polygon", "PointClick", "PanMap", "Circle", "MultiPoint", "SinglePoint".
// Anything else defaults to none.
// Select an appropriate mode.
return WMChangeDrawMode("PointClick");
}
else if (buttonCommandName == "My Target Command")
{
// do what you need to do
// ...
// update mapstate response information
LoadMapClientStateUpdate();
// return response object
return MapClientStateUpdate;
}
else
{
return base.WMMapToolsetButtonClick(buttonCommandName, drawMode, clientState);
}
}
Occasionally you may be able to handle a command button entirely on the client. For instance, you might show or hide an overview map by toggling its container's display between 'none' and 'block' or 'inline'. To do this, set the MapToolset's OnClientButtonClick property to the name of an appropriate function. The
MDNAtlasPage will use this function as a prehandler to its own toolset button click handler and the prehandler can return false to prevent further handling.
function ToolsetButtonClickPreHandler(button)
{
if (button == 'My Target Command')
{
// do what you need to do
// ...
// prevent normal handling
return false;
}
return true;
}