The <tool> element defines a tool in the toolbar above the map. A tool sets a mode that causes something to happen when the user clicks on the map, as opposed to a button that causes something to happen immediately when the user clicks the button. Tools, buttons, and spaces are displayed in the order that they appear within the <tools> element.

Note: At v4.0.6, buttons and spaces are defined with separate elements, not the <tool> element.

There are some special tool names that are known to the application, such as "Zoom In", "Identify", etc., with built-in handlers that perform the special action of the tool. IMF makes it easy to define new tools that interact with the map through the use of custom handlers that you develop. Any tool with a name that is not a special predefined tool is automatically a custom tool.

See also: tool examples and tool image gallery.

Frequency Parent Elements (the <tool> element is valid within): PO+ <tools>

Frequency Description (in this context) PO+ The <tool> element may appear zero or more times within the <tools> element.

Attributes Description active-graphic The URL of the image for the tool when the tool is active. This is used for tools only, not buttons. Required for tools, ignored for buttons and spaces. The URL can contain the special variable $FRAMEWORK to specify that the document is relative to the IMF installation directory. Absolute URLs may also be used. URLs that don't start with http: or $FRAMEWORK are resolved relative to the location of the XML file. Required. graphic The URL of the image for the tool. The URL can contain the special variable $FRAMEWORK to specify that the document is relative to the IMF installation directory. Absolute URLs may also be used. URLs that don't start with http: or $FRAMEWORK are resolved relative to the location of the XML file. Required. handler The URL to a script that will be executed when the map is clicked. Used by custom tools only (tools unknown by name to the framework). The URL can contain the special variable $FRAMEWORK to specify that the document is relative to the IMF installation directory. Absolute URLs may also be used. URLs that don't start with http: or $FRAMEWORK are resolved relative to the location of the XML file. Required for custom tools only. height The height of the tool image, in pixels. Required. help The URL to a text file (some HTML permitted) that contains help for this tool to be included on the auto-generated help page. The URL can contain the special variable $FRAMEWORK to specify that the document is relative to the IMF installation directory. Absolute URLs may also be used. URLs that don't start with http: or $FRAMEWORK are resolved relative to the location of the XML file. Optional. Help text is generated from other attributes if this attribute is missing. hint The pop-up tip that will appear when the user moves the mouse over the tool. Required. name The name of the tool. All tools in a toolset must have a unique name. Required. options This value can be used with some internal JavaScript managed tools. Optional. popup Used to indicate that a custom tool should open in a popup window. Optional, defaults to "false". shape The data collection shape type. Valid values are "point", "box", "line" and "polygon". For custom tools, the handler script will be executed in the dataFrame each time the user clicks the map. Tip: Use $FRAMEWORK/imfArgs.jsp for the handler script to understand what arguments the handler script is being called with. Optional, default is "point". status The message that will appear in the browser's status area when the user moves the mouse over the tool. Required. visible Used to set the visibility of a tool to invisible for use in designing user interfaces with active tools set from outside the toolbar. Optional, default is "true". width The width of the tool image, in pixels. Required.

Examples:

<!-- A built-in IMF tool -->
<tool name="Measure"
      shape="line"
      options="units=feet"
      hint="Measure Distance"
      status="Measures the distance between points where you click."
      help="$FRAMEWORK/help/measureTool.txt"
      graphic="$FRAMEWORK/tools/measure_1.gif"
      active-graphic="$FRAMEWORK/tools/measure_2.gif"
      width="16" height="16"/>

<!-- A custom tool -->
<tool name="Line Markup"
      shape="line"
      handler="$FRAMEWORK/imfMarkupToolLine.jsp"
      hint="Line Markup"
      status="Adds user-defined lines to the map."
      help="$FRAMEWORK/help/markupLineTool.txt" 
      graphic="$FRAMEWORK/tools/markup_line1.gif"
      active-graphic="$FRAMEWORK/tools/markup_line2.gif"
      width="18" height="18" />