Developing applications using the Web ADF—Web controls  

Toolbar control


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

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:

    Toolbar when first added to page
  2. Set Properties for the Toolbar control
    1. Before the toolbar will work, you need to set its BuddyControls and ToolbarItems properties.

      Toolbar when first added to page
                                           down arrow
      Toolbar with properties set
    2. Specifying buddy controls Toolbar control properties

      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.

      Toolbar item collection editor  



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 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