Working with the Toolbar control

In this topic

Creating and configuring custom tools, commands, and drop-down items

As a Web application developer, you can manage end-user interaction with Web Application Developer Framework (ADF) controls. In most cases, a user needs to interact with a Map control, which involves action on the client and action on the server. The client-side action allows you to, for example, draw a box over the control. The server-side action allows you to use the coordinates of the box and, for example, zoom in. 
The following occurs during every interaction with the Map control:
  • End-user interacts with the Map control on the client—Client-side action is controlled by a set of JavaScript functions on the client. For example, the zoom box is a client-side graphic created in a Cascading Style Sheets (CSS) layer by JavaScript code and displayed on the map. The Web ADF includes a set of prewritten JavaScript libraries to manage client-side interaction with Web ADF controls. When the client-side action is completed, the client sends a request to the server to execute server-side actions. 
  • Server executes an action based on client interaction—When the server receives a request from the client, it executes a server-side action. For example, if the server-side action is to zoom in, the server calculates the new extent for a map based on the user-defined box and instructs a map service to draw using the new extent. This occurs on the server because it has access to the Map control and a set of classes that support interaction with map contents. 
When you add items to a toolbar, set their properties to specify what occurs on the client and server when that item is selected. The ToolbarCollectionEditorForm dialog box is used to add items to the toolbar. On this dialog box, click the button below the Show Properties label to expand the form and show the properties of individual tools and commands, then set the properties associated with the tool or command's client and server-side actions. See the Configuring custom tools section for more information on how to configure custom tools and commands on a toolbar. For steps on how to use the Toolbar control, see Toolbar control.

Configuring custom tools

A tool requires the user to perform a client-side action by interacting with a Map or PageLayout control. Once the user completes the client action, a server-side action executes on the control. For example, to use a Zoom In tool, the user initiates a client action by drawing a box on a Map or PageLayout control. Once the user finishes drawing the box, a server action executes and the view extent changes.

Setting a tool's client action

Client-side actions are controlled by JavaScript functions that execute on the client before any requests are sent to the server. The Web ADF includes prewritten JavaScript code for common interactions, such as drawing a box. Map and PageLayout controls each have their own JavaScript functions.
Use the tool's ClientAction property to specify the client action. With this property, you can see the list of prewritten JavaScript functions and a custom option that allows you to write your function. Choosing the custom JavaScript option displays a dialog box where you can add your JavaScript code. You can call your JavaScript function before calling one of the prewritten JavaScript functions.
Each ClientAction property is associated with a JavaScript function that sets the tool's mode for interaction with a Map or PageLayout control. The name of the JavaScript function is the toolbar's buddy type, Map or Page (PageLayout), plus the ClientAction. For example, a ClientAction of DragRectangle is associated with the MapDragRectangle JavaScript function (in display_map.js). 
The following table shows the association between out-of-the-box ClientAction settings and the Web ADF JavaScript function called when initializing (clicking) a tool:
 
Web ADF JavaScript function
ClientAction
Map
PageLayout
Point
MapPoint
PagePoint
Line
MapLine
Not applicable
Polyline
MapPolyline
Not applicable
Polygon
MapPolygon
Not applicable
DragRectangle
MapDragRectangle
PageDragRectangle
DragImage
MapDragImage
PageDragImage
Circle
MapCircle
Not applicable
Oval
MapOval
Not applicable
MapDragImage
Not applicable
PageMapDragImage
MapDragRectangle
Not applicable
PageMapDragRectangle
MapPoint
Not applicable
PageMapPoint
To enable a tool with the same JavaScript function used by an out-of-the-box ClientAction, call the associated function for the ClientAction you want to initialize. For example, to customize the initialization of the out-of-the-box ZoomIn tool, set the ClientAction to "custom" and define the following JavaScript code example:
[JavaScript] 
MapDragRectangle('Map1', '%toolbarItem%', false, 'hand');
The parameters are map ID, toolbar item ID, show a loading icon, and cursor type. Currently, the show loading icon is not implemented and cannot be used. On the custom JavaScript dialog box, a convenience variable for the ID of the toolbar and toolbar item can be defined as %toolbar% and %toolbarItem%, respectively. 
Insert additional JavaScript content to work with other elements on the page. For example, to change properties of a zoom box associated with a custom tool, you can use the following JavaScript code example:
[JavaScript] 
var map = $find('Map1');
map.set_clientToolGraphicsColor('red');
map.set_clientToolGraphicsWidth('3px');
ESRI.ADF.MapTools.fillColor = 'green';
MapDragRectangle('Map1', '%toolbarItem%', true, 'hand');
The ClientToolGraphicsColor and ClientToolGraphicsWidth properties are set on the Map control during the initial load. Modify the properties using JavaScript to change the zoom box color and width. The static variable ESRI.ADF.MapTools.fillColor defines the fill color.
In a more complex scenario, you might handle all of the client interaction by leveraging the ADF JavaScript library. See the following code example:
[JavaScript] 
var map = $find('Map1');
var onComplete = Function.createDelegate(map, function(geom){
    var env = new ESRI.ADF.Geometries.Envelope(geom.get_xmin(), geom.get_ymin(),
        geom.get_xmax(), geom.get_ymax()); map.zoomToBox(env); 
}

);
map.set_mouseMode(ESRI.ADF.UI.MouseMode.Custom);
map.getGeometry(ESRI.ADF.Graphics.ShapeType.Envelope, onComplete, null, 'green',
    'red', 'crosshair', true);
In the preceding code example, the getGeometry function on the Map client control dictates that an action on the map generates an envelope and defines the graphic feature properties (for example, color) and mouse cursor during the action. When the action is complete, the map zooms to the envelope. 
You can also add a Tool to a separate JavaScript file. In this case, the ClientAction JavaScript sets up a function that is called at the onmousedown event of a Hypertext Markup Language (HTML) element on the form. Use the JavaScriptFile property to embed the required JavaScript file for your custom ClientAction onto the page. 
The ServerAction method for a Tool has a single argument of type ToolEventArgs. The ClientAction property for the Tool (set at design time on the Toolbar Item Collection Editor dialog box), defines how you use the tool to interact with the Map, which Web ADF JavaScript functions process the interaction, and the type of information contained by the ToolEventArgs. 
The client-side interaction (JavaScript) is handled for you. The server-side implementation must be customized and usually involves working with user provided information via the ToolEventArgs. ToolEventArgs contains the geometry generated by a user interacting with the Map. The type of ClientAction dictates the type of geometry. For example, if the ClientAction property is set to Point, the ToolEventArgs parameter must be cast to MapPointEventArgs to access the user-defined point. 
The geometry is returned in map and screen units. The following table links a tool's ClientAction property with the type of ToolEventArgs you can cast to in your custom tool implementation:
ClientAction
ToolEventArgs type
Point
MapPointEventArgs
Line
MapLineEventArgs
Polyline
MapVectorEventArgs, MapPolylineEventArgs
Polygon
MapVectorEventArgs, MapPolygonEventArgs
DragRectangle
MapRectangleEventArgs
Circle
MapCircleEventArgs
Oval
MapOvalEventArgs

Setting a tool's server action

A tool's server-side action executes after the client-side JavaScript has posted back to the buddy control or Toolbar control. Provide a server-side action for each tool you add to a toolbar. The ESRI.ArcGIS.Server.WebControls.Tools namespace includes a few common server-side actions for tools, such as Zoom In, Zoom Out, and Pan. For extended functionality, write your classes to handle server-side actions.
The ServerActionAssembly and ServerActionClass properties work together and indicate the location of a tool's server-side code. The properties indicate the assembly and class that contains the server-side code your tool executes. Both of these properties must be satisfied unless you are writing server-side code based on events.
  • ServerActionAssembly—Fully qualified display name of the assembly containing the code for the server-side action. This can be the name of a class library that you added to a Visual Studio solution or if you added a class to your current project, it is the name of your current project. If you added the code in the App_Code directory of your Web site, the ServerActionAssembly is App_Code.
  • ServerActionClass—Fully qualified name of the class that contains the server-side action code. When you add a valid ServerActionAssembly name, all of the available classes in the assembly become available in the ServerActionClass drop-down list (select a class from this list). You can manually add the fully qualified class name. If the class is in a namespace, <namespace>.<classname> is the format.
A class that contains server-side tool code needs to implement a tool action interface. For toolbars with the BuddyControlType set to Map, the class must implement IMapServerToolAction. For toolbars with BuddyControlType set to PageLayout, the class must implement IPageServerToolAction. These interfaces each contain one ServerAction method, which is automatically stubbed out when you implement the interface (where you write the tool's server-side code).
Remember the following when adding your class:

Configuring custom commands

Commands require no user interaction (executes immediately when clicked). Commands can have a client action, a server action, or both. You set a command's client and server actions as previously explained for tools; however, a command coded in a class needs to implement a command action interface instead of a tool action interface. The command action interfaces are IMapServerCommandAction and IPageServerCommandAction, depending on the buddy control type of the toolbar that contains the command.
If you want to write the server-side code for your commands directly on the page, you can use the Toolbar control's CommandClick event. The argument passed into the event handler is of type ToolbarCommandClickEventArgs. This argument has a CommandName property to determine how an end-user clicked. You can use a switch or Select Case statement based on the CommandName property to start the appropriate server-side action based on the clicked command.

Toolbar control

The Toolbar control provides a prepackaged framework for adding client-side tools to interact with Web ADF controls. The callback framework is managed for you. You only need to create a class on the server that implements the appropriate interface (depending on the type of toolbar item) and add that class to the Toolbar control. Implementation code in the toolbar item class can interact and change any server-side resource, and the callback response is managed for you. This is the easiest way to access the Web ADF callback framework, but requires you to work within the Toolbar framework.
The following table shows the toolbar item types and interfaces to implement:
Toolbar item
Interface
Description
Tool
IMapServerToolAction
Requires you to activate and initiate server-side action by interacting with a Map control.
Command
IMapServerCommandAction
You initiate server-side action by clicking.
DropDownBox
IMapServerDropDownBoxAction
Requires you to select an item to initiate server-side action.
All toolbar item interfaces define a ServerAction method and different argument types. The ServerAction method for Command and DropDownBox items has a single argument of type ToolbarItemInfo. For a tool, it is always a type of ToolEventArgs. See the following code example that shows how these items can be used:
[C#] 
public class CustomTool: IMapServerToolAction
{
    public void ServerAction(ToolEventArgs args)
    {
        Map map = (Map)args.Control;
        MapPointEventArgs pea = (MapPointEventArgs)args;
    }
}

public class CustomCommand: IMapServerCommandAction
{
    public void ServerAction(ToolbarItemInfo info)
    {
        Map map = (Map)info.BuddyControls[0];
    }
}

public class CustomDropDownBox: IMapServerDropDownBoxAction
{
    public void ServerAction(ToolbarItemInfo info)
    {
        DropDownBox dropDownBox = (DropDownBox)info.Toolbar.ToolbarItems.Find(
            "DropDownBoxId");
        string dropDownBoxValue = dropDownBox.SelectedValue;
    }
}
The custom tool shows an example of how to retrieve the buddy control of the toolbar and cast the ToolEventArgs to the appropriate type, depending on the client action (see the table in the Toolbar control section). The custom command and drop-down box shows how to retrieve the buddy control of the toolbar. You can also get a reference to the drop-down list and retrieve the selected value.
The toolbar has a CommandClick event that can be handled to include all command related code in a single event method. The following code example shows how the event handler method can be used to work with multiple commands in a toolbar. You do not have to create a custom class and implement the IMapServerCommandAction interface to create a custom command. As a result, executing server-side code through a command in a toolbar is easier.
[C#] 
[C 
# ]
protected void Toolbar1_CommandClick(object sender, ToolbarCommandClickEventArgs
    args)
{
    switch (args.CommandName)
    {
        case ("CustomCommand1"): 
        {
            // Do something.
            break;
        }
        case ("CustomCommand2"): 
        {
            // Do something.
            break;
        }
    }
}

Controlling the toolbar's appearance

Use the Orientation property to specify whether the Toolbar control shows horizontally or vertically. The ToolbarStyle allows you to specify whether or not the toolbar has text and images. Use the TextPosition and Alignment properties to position the text relative to the image. You can choose from the following styles:
  • ImageAndText
  • TextOnly
  • ImageOnly
Each style property allows you to define the background color, font, and so on. You control the look of the toolbar with the following properties:
  • ToolbarItemDefaultStyle—Style applied to commands and tools when they are not disabled, hovered upon, or in the case of tools, selected.
  • ToolbarItemHoverStyle—Style applied to commands and tools when hovered over.
  • ToolbarItemDisabledStyle—Style applied to commands and tools when the Disabled property is set to true.
  • ToolbarItemSelectedStyle—Style applied to the CurrentTool of the toolbar. It is also applied to a command when clicked and until the page refreshes.  

Grouping toolbars

You might want more than one toolbar on your Web form that works with a Map or PageLayout control, for example, to use the toolbar for organizing related functions, such as having all the map navigation tools on one toolbar. You might also want to place toolbars in different locations on your Web form, for example, at the top and side of a Map or PageLayout control. In both cases, you want the set of toolbars you define to work with the same control. The Group property allows one or more toolbars to work together and essentially function as one. With this property enabled, only one tool is active on the set of grouped toolbars.
Organize toolbars into groups by using the same value for the Group property on each toolbar in the group. Setting the CurrentTool property on one toolbar clears the CurrentTool property of the other toolbars in the group. When creating a group, ensure that you provide a unique name for each ToolBarItem across all the grouped toolbars. You are also responsible for ensuring that the BuddyControls property is the same for all toolbars in the group.


See Also:

Toolbar control
Sample: Common Add custom tool
Sample: Common Select Buffer tool
Using the common data source API in a Web application
Web controls