You can think of a toolbar as a collection of tools and commands, divided into categories that perform similar types of actions. When building a Web application, you drag and drop a toolbar into a form, and then select the tools, commands, spaces, and separators you want to add.

You can add both pre-built and custom tools to a toolbar. The pre-built tools are included with the Web ADF and consist of common map navigation tasks such as pan and zoom. They don’t require any coding and can be added to the map with a simple click.

Your toolbar can also include tools that you develop using the Web ADF or other libraries. The code for a custom tool or command should be organized in a class library, which you can create as a separate project in Visual Studio. Once you’ve written the code for the tool, you add the project to your Web application to make use of its functionality. You can then set the tool’s specific properties—such as its icon and client-side action—within the ToolbarItem Collection Editor.

Assembly: ESRI.ArcGIS.ADF.Web.UI.WebControls.dll
Class: ESRI.ArcGIS.ADF.Web.UI.WebControls.Toolbar
JavaScript libraries: display_common.js, display_dotnetadf.js, display_toolbar.js

Using the Toolbar Control

1. Add the control to the page
   
   In order to use the Toolbar control, a number of supporting controls must be available.  Set up a Web application with, at minimum, a  MapResourceManager control and a Map control using their discussion topics as a guide.  Drag and drop a MapResourceManager, Map, and Toolbar control on the Web form.  You should see the following in Visual Studio:
   
   
   
2. Set Properties for the Toolbar control
   1. Before the toolbar will work, you need to set its BuddyControls and ToolbarItems properties.
      
      
                                          
      
   2. Specifying buddy controls
      
      You specify which map or page layout controls a toolbar will work with through the toolbar control’s BuddyControls property. Click the ellipsis button in the BuddyControls property value to display the BuddyControls Collection Editor. Use this dialog to add one or more map or page layout controls the toolbar will operate on. However, a toolbar can only have buddy controls of one type: either map controls or page layout controls, but not both. Use the BuddyControlType property to specify which type the toolbar will work with. 
      
      
      
      
3. Adding toolbar items

   A toolbar control may contain multiple ToolbarItem objects. A ToolbarItem can be one of these types:

   • Tool —A Tool requires interaction from an end user before executing. Tools have a client action and a server action. For example, to use a Zoom In tool, you interact with a map control by dragging a box over it. Client-side JavaScript draws the box on the screen. Then the server action executes when the map zooms in to the specified extent.
   • Command —A Command executes immediately when clicked; therefore it requires no end user interaction. For example, when you click a full extent command, you do not need to interact with the map; it zooms immediately to the full extent. A command may have a client action, a server action, or both.
   • DropDownBox —A DropDownBox allows you to interact with a control by selecting an item from a list—such as layers, data frames, or extent bookmarks—and performing an action based on that selection. You can set the items in the DropDownBox from the ToolbarCollectionEditorForm, or you can do so programmatically.
   • Space —A space allows you to make room on your Toolbar for other HTML controls or Web controls. Using the Size property of a Space object, you can specify how big a space you want on your toolbar. A size of 1 translates to a space of 10 pixels. However, the size of a space can vary with the size of a toolbar control. If you shrink a toolbar control, the size of a space will decrease before other items get truncated. A Space does not execute any action.
   • Separator—A separator is a line between items on the toolbar control that allows you to form groups of related items on the toolbar. For example, you could place a separator on the toolbar to distinguish your geoprocessing tools from your terrain analysis tools. Alternatively, you could create a separate toolbar for each category.

   
   To add an item to your toolbar, follow the steps below:

   1. Click the Toolbar control, then, in the Properties window, click the … button next to the ToolbarItems property. You will see a form with a list of available toolbar items and current toolbar contents.
   2. In the Toolbar Items column, select an item to add. The Web ADF includes a set of common map navigation tools and commands. These tools and commands have pre-configured client and server actions. They are grouped in a Map Navigation category. You can either select the whole category, or expand the category and select individual items. If you have written code for a custom tool or command, select the blank icon next to the word “Tool” or “Command”, respectively.
   3. Click Add.
      
      This graphic shows tools added, and also shows the expanded properties display for tools. These properties are discussed below.
      
       

Members

Properties

  The following table provides a list of properties and events of interest.  For complete reference information, see the Toolbar control in the library reference section.

Property Name	Type	Description
Alignment	Alignment	Alignment of the text and image on a Command or Tool.
BuddyControls	BuddyControlCollection	A set of PageLayout or Map controls that this Toolbar acts on.
BuddyControlType	BuddyControlType	The type of the buddy controls associated with this control. Either a set of Map controls or a set of PageLayout controls can be associated with this control, but not a set of both.
CurrentTool	string	The selected Tool on this Toolbar. There can only be one CurrentTool among a group of Toolbar controls.
Group	string	The group to which this Toolbar belongs. A group of Toolbar controls can have only one CurrentTool among them. The Group property cannot be set to null or or to an empty string.
Orientation	Orientation	The orientation of the Toolbar: horizontal or vertical.
TextPosition	TextPosition	Position of the text with reference to the image on a Command or Tool. Applies only to toolbars with the ImageAndText ToolbarStyle.
ToolbarItemDefaultStyle	Style	The style applied to Commands and Tools when they are not selected, disabled, or hovered upon.
ToolbarItemDisabledStyle	Style	The style applied to Commands and Tools when they are disabled.
ToolbarItemHoverStyle	Style	The style applied to Commands and Tools when they are hovered upon.
ToolbarItems	ToolbarItemCollection	The collection of ToolbarItem objects on this Toolbar. The Tools defined here will override the ToolItems on the Map or PageLayout controls that you set up as this Toolbar's buddy controls.
ToolbarItemSelectedStyle	Style	The style applied to Commands and Tools when they are selected.
ToolbarStyle	ToolbarStyle	The style of the toolbar: whether it displays both text and image for a command or tool, or only one of the two.

Events

Event Type	Description
CommandClick	Raised when a command on the Toolbar has been clicked.  An viable option for handling all commands in one location.
DropDownBoxIndexChange	Raised when the selected index of a select item on the Toolbar has changed. Only fired if AutoPostBack is True on the select item.

Discussion

• Creating a Custom Tool, Command, or DropDown
  
  

  As a Web application developer, you will likely need to manage end user interaction with Web ADF controls in your application.   In most cases, a user will need to interact with a Map control, which involves some action on the client and some action on the server.  The client-side action is what allows you to, for example, draw a box over the control.  The server-side action is what allows you to use the coordinates of the box and, for example, zoom in.  During every interaction with the Map, two things happen:

  • An end user interacts with the Map control on the client
    The 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 within a Cascading Style Sheet (CSS) layer by JavaScript code and displayed on top of the map.  The Web ADF includes a set of prewritten JavaScript libraries to manage client-side interaction with Web ADF controls.  Once the client-side action is completed, the client sends a request to the server to execute server-side actions. 
  • The server executes an action based on the 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 happens 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 your own items to a toolbar, you need to set their properties to specify what will happen on the client and the server when that item is selected. The form you use to add items to your toolbar is the ToolbarCollectionEditorForm. In this dialog, click the button below the Show Properties label to expand the form and show the properties of individual tools and commands.   In particular, you will be concerned with setting the properties associated with the tool or command’s client and server-side actions. The following section contains more detailed information about how to configure custom tools and commands on a toolbar. For an example of adding custom tools and commands to a toolbar.  

  Configuring custom tools

  A Tool requires the user to perform a client-side action by interacting with a map or page layout 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 page layout 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, prior to any requests being sent to the server. The Web ADF includes prewritten JavaScript code for common interactions such as drawing a box. The map and page layout controls each have their own JavaScript functions.

  Use the tool’s ClientAction property to specify the client action. With this property, you’ll see the list of prewritten JavaScript functions and also a custom option that allows you to write your own function.  Choosing the custom JavaScript option displays a dialog box into which you can enter your JavaScript code. You might simply call your own JavaScript function before calling one of the prewritten JavaScript functions. 
  
  Each ClientAction is associated with a JavaScript function that sets the tool mode for interaction with a Map or PageLayout. In general, the name of the JavaScript function is the toolbar 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 table below provides a comprehensive review of the association between out-of-the-box ClientAction settings and the Web ADF JavaScript function called when initializing (clicking on) a tool. 
  
  

  ClientAction	Web ADF JavaScript function
  	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

  
  So if you wanted to enable a tool using 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:

  MapDragRectangle('Map1', '%toolbarItem%', false, 'hand');

  The parameters are map id, toolbar item id, show a loading icon, and cursor type. The show loading icon is not currently implemented and thus not used. In the custom JavaScript dialog, a convenience variable for the id of the toolbar and toolbar item can be defined as %toolbar% and %toolbarItem%, respectively. 
  
  You can then insert additional JavaScript content to work with other elements in the page.  For example, to change properties of a zoom box associated with a custom tool, you may use the following JavaScript code:
  
  

  var dragboxdiv = document.getElementById('DragBoxDiv');
  dragboxdiv.style.borderColor = 'red';
  dragboxdiv.style.borderWidth = '10px';
  dragboxdiv.style.filter = 'alpha(opacity=100)';
  dragboxdiv.style.backgroundColor = ''; 
  
  MapDragRectangle('Map1', '%toolbarItem%', true, 'hand');

  Note, in this example the id ‘DragBoxDiv’ is specified in the DragBoxObject function in display_common.js.   On initial load of the Map, a set of JavaScript code is written to the page that calls the DragBoxObject function to create a div with the id “DragBoxDiv”.  The div maintains properties (i.e. color, size, opacity) of the “dragbox”.
  
  

  In a more complex scenario, you might handle all of the client interaction with your custom JavaScript. In this case, your custom ClientAction JavaScript should set up a function that is called at the onmousedown event of an HTML element on the form. You would use the JavaScriptFile property to embed the JavaScripts required for your custom ClientAction into the page itself. 

  The ServerAction method for a Tool has a single argument of type ToolEventArgs.  The ClientAction property for the Tool (set at design-time in the Toolbar Item Collection Editor), defines how a user will use the tool to interact with the Map, which Web ADF JavaScript functions will 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 will dictate the type of geometry.  For example, if the ClientAction property is set to Point, the ToolEventArgs parameter must be cast to PointEventArgs to access the user-defined point.  Note that the geometry returned is always in screen units.  The table below links a Tool's ClientAction property with the type of ToolEventArgs you can cast to in your custom tool implementation.
  
  

  ClientAction	ToolEventArgs type
  Point	PointEventArgs
  Line	LineEventArgs
  Polyline	VectorEventArgs, PolylineEventArgs
  Polygon	VectorEventArgs, PolygonEventArgs
  DragRectangle	RectangleEventArgs
  Circle	CircleEventArgs
  Oval	OvalEventArgs

  
  Walkthrough #1 in the Working with AJAX capabilities in the Web ADF section discusses creating a custom tool. 

  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. You must 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, you can write your own classes to handle server-side actions.

  Two properties work together to indicate the location of a tool’s server-side code: ServerActionAssembly and ServerActionClass. They indicate the assembly and class which contain the server-side code that your tool will execute. Both of these properties must be satisfied unless you are writing server-side code based on events.

  ServerActionAssembly is the fully qualified display name of the assembly containing the code for the server-side action. This could be the name of a class library that you added to a Visual Studio Solution, or, if you simply added a class to your current project, it is the name of your current project. If you added the code within the App_Code directory of your website, the ServerActionAssembly is App_Code.

  ServerActionClass is the fully qualified name of the class that contains the server-side action code. Once you enter a valid ServerActionAssembly name, all of the available classes in the assembly become available in the ServerActionClass dropdown list. You must then select a class from this list.  You can also manually enter the fully qualified class name.  If the class is in a namespace, the format will be: <namespace>.<classname>

  A class that contains server-side tool code needs to implement a tool action interface. For toolbars with 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 method— ServerAction—which is automatically stubbed out for you when you implement the interface. This is where you write the tool’s server-side code.

  Points to remember when adding your own class:

  • Make sure the class implements IMapServerToolAction or IPageServerToolAction, depending on which buddy control the tool will be used with.
  • Build the solution immediately after adding the class. This ensures that the ServerActionAssembly and ServerActionClass names will be recognized as valid.
  • Refer to the samples Common_AddCustomTool and Common_SelectBufferTool  

  Configuring custom commands

  A command requires no user interaction; it executes immediately when clicked. A command can have a client action, a server action, or both. You set a command’s client and server actions in much the same way explained above for tools; however, a command coded in a class needs to implement a command action interface instead of a tool action interface. These are IMapServerCommandAction and IPageServerCommandAction, depending on the buddy control type of the toolbar that contains the command.

  If you prefer to write the server-side code for your commands directly in 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 property called CommandName through which you can find out which command an end user clicked. You can use a switch or Select Case statement based on CommandName to execute the appropriate server-side action based on the command clicked.
  
  Toolbar control
  
  The Toolbar control provide 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.  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 tap into the Web ADF callback framework, but requires you to work within the Toolbar framework.
  
  The table below lists the toolbar item types and interface to implement:

  Toolbar Item	Interface	Description
  Tool	IMapServerToolAction	Requires user to activate then initiate server-side action by interacting with a Map control
  Command	IMapServerCommandAction	User initiates server-side action on click
  DropDownBox	IMapServerDropDownBoxAction	Requires user to select item to initiate server-side action

  
  All toolbar item interfaces define a ServerAction method, but 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.  Here is an example of how they may be used in code:
   

  [C#]

  public class CustomTool : IMapServerToolAction {
   public void ServerAction(ToolEventArgs args)
    {
     Map map = (Map)args.Control;
     PointEventArgs pea = (PointEventArgs)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 illustrates an example of how to retreive the buddy control of the toolbar and cast the ToolEventArgs to the appropriate type, depending on the client action (see table in the Configuring custom tools section above).   Both the custom command and drop down box illustrate how to retrieve the buddy control of the toolbar.  You can also get a reference to the drop down list and retrieve the value selected.
  
  The toolbar itself has a CommandClick event that can be handled to include all command related code in a single event method.  Here is an example of how the event handler method may be used to work with multiple commands in a toolbar.  Note, you do not need to create a custom class and implement the IMapServerCommandAction interface to create a custom command.  As a result, executing server-side code via a command in a toolbar is much simpler.
  
  

  [C#]

  protected void Toolbar1_CommandClick(object sender, ToolbarCommandClickEventArgs args)
  {
   switch (args.CommandName)
   {
    case ("CustomCommand1"):
    {
      // do something
      break;
    }
    case ("CustomCommand2"):
    {
      // do something
      break;
    }
   }
  }
       

• Controlling the look of the Toolbar
  
  The Orientation property allows you to specify whether the toolbar control is displayed horizontally or vertically. The ToolbarStyle allows you to specify whether or not the toolbar has text and images. You can choose from the following three styles: ImageAndText, TextOnly, and ImageOnly. Use the TextPosition and Alignment properties to position the text relative to the image.
  
  You control the look of the toolbar with the following four properties. Each style property allows you to set up the background color, font, and so on.
  
  ToolbarItemDefaultStyle—the style applied to Commands and Tools when they are not disabled; hovered upon; or, in the case of Tools, selected.
  ToolbarItemHoverStyle—the style applied to Commands and Tools when the mouse is held over them.
  ToolbarItemDisabledStyle—the style applied to Commands and Tools when their Disabled property is set to True.
  ToolbarItemSelectedStyle—the style applied to the CurrentTool of the toolbar. It’s also applied to a Command from the time it gets clicked until the page refreshes.

 

• Grouping Toolbars
  
  At times you may want to have more than one toolbar on your Web form that works with a map or page layout control. For example, you may want to use the toolbar itself as a means 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, along the top and side of a particular map or page layout 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 at a given time.
  
  You organize toolbars into groups by using the same value for the Group property on each toolbar you want to participate in the group. Setting the CurrentTool property on one toolbar will clear the CurrentTool property of the other toolbars in the group. When creating a group, you must 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 of all the toolbars in the group.