/********************************************************************************************/
//
//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 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抳e 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抯 specific properties梥uch as its icon and client-side action梬ithin the ToolbarItem Collection Editor.
你可以将Toolbar当一个工具或者命令的集合，然后将那些功能类似的动作分到一组里面。 当创建一个web application的时候，你拖拽一个工具条到一个表格里面，然后选择你想添加的工具，命令，空格，以及分离器。/
你可以添加内置或者自定义工具到一个工具条，内置的工具包含在Web ADF里面并且包含通用的地图导航工具，比如：平移、缩放。他们不需要进行任何编程，只需要单击一下就可以添加到地地图。
你的工具条也可以包含你使用web ADF或者其他的类库开发的工具，为自定义工具或者命令写的代码应该在一个类库里面组织，你可以在VS里面以创建一个单独的工程的方法创建一个类库。一旦你为一个工具写代码，你就可以把那个工程添加到你的Web 应用程序中力，然后使用类的功能。
Assembly: ESRI.ArcGIS.ADF.Web.UI.WebControls.dll
Class: ESRI.ArcGIS.ADF.Web.UI.WebControls.Toolbar
Using the Toolbar Control
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控件，一系列支持作用的控件必须是可以使用的。创立一个Web 应用程序，最低情况下，需要添加一个MapResourceManager控件和一个地图控件。 向页面的表格中拖拽一个MapResourceManager控件，一个地图控件，一个toolbar控件。 你的程序在VS里面应该如下所示：
Set Properties for the Toolbar control
Before the toolbar will work, you need to set its BuddyControls and ToolbarItems properties.
为toolbar控件设置属性
在toolbar能够工作之前，你需要设置它的BuddyControls控件，她的ToolbarItems属性。
Specifying buddy controls
指定Buddy控件
You specify which map or page layout controls a toolbar will work with through the toolbar control抯 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.
通过toolbar控件的BuddyControls属性指定同toolbar控件一起工作的的地图控件或者pagelayout孔家。 单击BuddyControls属性值后面你的省略号弹出BuddyControls控件集合编辑对话框，使用这个对话框添加一个或者多个被用来操作的地图控件或者pagelayout控件。尽管如此，一个toolbar控件仅仅能绑定一种控件的类型：map控件或者pagelayout控件而不能两者都是。 使用BuddyControlType属性指定和toolbar一起工作的控件类型。
Adding toolbar items
A toolbar control may contain multiple ToolbarItem objects. A ToolbarItem can be one of these types:
添加toolbar items
一个toolbar控件也许包含多个toolbaritem对象，一个toolbaritem 可能是下面的控件种类之一
Tool 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.
工具：tool 要求在它执行前需要和用户进行一个交互。Tools有一个客户端的动作和一个服务器端的动作。 比如：使用缩放动作，你通过在map地图克控件上方拖动一个框来实现和地图的交互。客户端的JavaScript函数在屏幕上画一个箱。然后服务器端执行这个动作，地图缩放到指定显示的范围。
Command 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.
命令： 单击后，命令就会立即被执行。因此，它不需要一个用户动作结束的交互。 比如：当你单击一个Fll extent 命令，你不需要和地图进行一个交互，地图就会立刻缩放到全图显示的范围。一个命令可能含有一个客户端的动作、一个服务器端的动作、或者客户端和服务器端的动作都有。
DropDownBox 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.
下拉框：DropDownBox 允许你通过从一个下俩列表里面选择一个Item和一个控件进行交互，这个列表可是：图层列表，数据框架，或者显示范围标记或者一个基于选择的动作。你可以在ToolbarCollectionEditorForm对话框里面设置显示在下拉框中的选项，你也可以通过编码来实现这个操作
Space 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
空格：space 允许你在你的toolbar中为其他的HTML控件或者web控件添加间隔的控件。使用一个Space对象的Size属性，你可以设置在你的toolbar控件里面你想要的空间的大小。是一个1到10像素大小的距离。 尽管如此，这个控件大小能够随着toolbar控件大小的改变而改变。 如果你缩小一个toolbar控件，sapce的大小将会在其他控件缩放之前减少，一个space不能让你执行任何的动作。
.
Separator 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（类别）.
分割符: separator是加载在toolbar中两个工具之间的一条线，它允许你将一些相关的items组成一组。比如：你可以在工具条中添加一个分割符号来区分（辨别）你的地理处理工具和地形（地势）分析工具。二者选择一个，你可以为每一种类别创建一个分割工具。
To add an item to your toolbar, follow the steps below:
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.
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 espectively.
Click Add.
为来向工具条中添加一个工具，请根据下面的步骤：
单击toolbar控件，然后在属性窗口，单击ToolbarItems属性后面的省略号，你将会看到一个含有一系列可以得到的toolbar items以及当前工具条所含工具的对话框。
在 toolbar items 列中，选择一个项添加。 Web adf 包含一系列通用的地图导航工具和命令。 这些工具和命令包含事前配置好的客户端和服务器端动作。他们被分在地图导航类别里面。你既可以选择整个的类别，或者站看类别，然后选择单独的items项。 如果你为来一个自定义工具或者命令写了代码，那么选择那些没有图标的工具或则命令工具。
单击“Add”
This graphic shows tools added, and also shows the expanded properties display for tools. These properties are discussed below.
下面的图表显示了你添加的tools。并且展示所选中的工具的属性项。 这些属性将会在下面讨论
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
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，服务器端的动作允许你使用box的坐标放大地图。在每个和地图的交互中，发生两件事情：
讨论
创建一个自定义工具，命令，或者下拉框控件
作为一个web应用程序的开发者，你可能需管理和你的应用程序中的web adf 控件之间的交互。 在多数情况下，一个用户需要和一个地图控件进行交互，地图控件包含一些客户端的动作和一些服务器端的动作。 客户端的动作，比如，允许你在地图控件的上方画一个方框。
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.
客户端的动作由一系列的客户端的JavaScript动作来控制。比如：缩放的box是一个客户端的图形，它是由JavaScript函数在一个CSS图层中创建。一旦客户端的动作完成，客户端就像服务器端发送一个请求来执行服务器端的动作。
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.
服务器端执行一个基于客户端的交互的动作。
当服务器端接受一个来自于客户端的请求的时候，它执行一个服务器端的动作。比如:如果服务器端是放大，服务器就计算基于用户定义的BOX的地图显示范围，指示一个地图服务去绘制新的显示范围。 这些都发生在服务器端，因为服务器端有访问map控件的权限，和一系列支持和地图内容进行交互的类。
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 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.
当你向一个toolbar控件中添加你自己的items，你需要设置他们的属性，来指定当items被选中的时候，在客户端将会发生什么，在服务器端将会发生什么。你用来向你的toolbar添加items的form是ToolbarCollectionEditorForm。 在这个对话框里面，单击show properties 图标下面的按钮，展开表格并显示独立的工具和命令的属性。 尤其，你需要注意设置和工具和命令相关的客户端和服务器端的动作的的属性。下面的部分包含更多和如何在一个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 client action
配置客户端工具：
一个工具要求用户执行一个客户端的动作和一个地图控件或者一个pagelayout控件进行交互，一旦用户完成了客户端的动作，一个服务器端的控件就会在控件上执行。比如：使用一个放大的工具，用户过在一个地图控件或者pagelayout控件上画一个box来开始一个客户端的动作，一旦用户完成了box的绘制，一个服务器端动作就会执行，然后改变视图的显示范围。
这是工具的客户端动作，
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 ClientAction property to specify the client action. With this property, you 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.
客户端动作是由javascript函数控制的在客户端执行的动作。这个动作在任何发送到服务器端的请求中是优先的。Web ADF控件包含事先定义JavaScript代码，这些代码用于普通的交互比如：绘制一个box。地图控件和pagelayout控件，每一个都包含他们自己的JavaScript函数。
使用一个工具，ClientAction属性来指定客户端的动作。 在这个属性里面，你看到一系列的事前写好的JavaScript函数和一个用户选项，它可以允许你用代码写你自己的功能。选择custom JavaScript选项将会出现一个对话框，在里面你可以输入你的JavaScript代码。 你可以在你调用预写的JavaScript函数之前调用你自己的JavaScript功能。
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.
每一个客户端动作是和一个JavaScript函数想关联的， 这个函数设置了用于和地图或者pagelayout控件进行交互的tool模型。一般来说，JavaScript函数的名称是toolbar buddy类型，地图或者页面(pagelayout)，加上ClientAction。 比如：客户端的DragRectangle是和MapDragRectangle JavaScript功能相关联的。下面的表格提供了一个综合的全面的out-of-the-box ClientAction settings 和 the Web ADF JavaScript 函数之间的联系，并且当单击一个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');
如果你想使一个tool能够使用， 那么就使用和out-of-the-box 客户端动作一样的JavaScript功能，调用与你相初始化的客户端动作相关联的函数。比如：
定义out-of-the-box 放大工具的初始化，设置ClicentAction为custom并定义下面的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.
这些参数分别是：map id，toolbar项的ID，显示一个加载的图标和光标的类型。 显示加载图标不是目前已经实施的所以他没有使用。在自定义JavaScript对话框中，用于toolbar和toolbar item 的一个比较方便的变量可以对其进行如下格式的定义：%toolbar% and %toolbarItem%。
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:
你可以添加用于页面中其他要素的JavaScript的内容。比如：可以使用下面的JavaScript代码改变和一个自定义tool想关联的缩放box的属性：
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 initial load. You can modify them via 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.
ClientToolGraphicsColor and ClientToolGraphicsWidth的属性在初始化加载的时候设置地图控件。你可以通过JavaScript重定义他们，改变zoom box的颜和边框的宽度。变量ESRI.ADF.MapTools.fillColor 定义填充的颜色
在一个更加复杂的场景里面，你可能通过影响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 this example the getGeometry function on the Map client control dictates that an action on the map will generate an envelope, and defines the graphic feature properties (e.g. color) and mouse cursor during the action. When the action is complete, the map will zoom to the envelope.
在这个例子中，应用在map上的客户端控件的getGeometry函数指定了地图上的动作将会生成一个envelope，并且定义几何要素的属性和动作执行过程中的光标的样式。当动作完成后，地图将会缩放指定的envelope。
You may also want to add tool JavaScript to separate JavaScript file. In this case, the 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 JavaScript file required for your custom ClientAction into the page itself.
【You may also want to add tool JavaScript to separate JavaScript file.】在这种情况下，客户端的javascript函数，应该设置一个函数，在表格里面的一个HTML元素的ONMOUSEDOWN事件中调用这个函数。你可能使用JavaScriptFile属将你的应用程序中需要的JavaScript文件其嵌入到页面本身
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 MapPointEventArgs to access the user-defined point. Note that the geometry is returned in both map and 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.
服务器端的用于一个tool的方法有一个单独的参数ToolEventArgs，工具的客户端属性定义了，一个用户如何使用这个tool和地图控件进行交互，web adf 的JavaScript将会处理这个交互以及有ToolEventArgs参数包含的信息类型。 客户端的交互为你处理。服务器端的实施必须定义并且通常和通过ToolEventArgs提供的信息一起工作。ToolEventArgs 包含由用户和地图交互产生geometry。 客户端的类型将会指定geometry的类型。比如：如果客户端的属性为point ，ToolEventArgs变量必须转换为MapPointEventArgs来访问用户定义的点。既然geomtry返回的是地图和显示器的单位。下面的表格连接了ClientAction属性和ToolEventArgs属性，你可以投射到你的自定义工具实施中。
|
ClientAction |
ToolEventArgs type |
|
Point |
MapPointEventArgs |
|
Line |
MapLineEventArgs |
|
Polyline |
MapVectorEventArgs, MapPolylineEventArgs |
|
Polygon |
MapVectorEventArgs, MapPolygonEventArgs |
|
DragRectangle |
MapRectangleEventArgs |
|
Circle |
MapCircleEventArgs |
|
Oval |
MapOvalEventArgs |
Setting a tool server action
A tool 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.
设置工具的服务器端动作
一个工具的server-side动作在客户端的JavaScript回发到buddy控件或者toolbar控件后就开始执行。你必须为你添加到toolbar的每一个工具提供一个服务器端的动作。命名空间ESRI.ArcGIS.Server.WebControls.Tools包含了一些通过用用于工具上的服务器端的动作。 比如：ZOOMIN，ZOOMOUT,PAN，对于扩展的功能，你可以写你自己的类来处理服务器端的动作。
Two properties work together to indicate the location of a tool 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.
两个属性在一起工作来指定server-side:代码的位置：ServerActijonAssembly和ServerActionClass。他指定了集合和类，他们包含着你的工具将要执行的服务器端的代码。这两个属性都需要指定，除非你正在写基于事件的服务器端代码。