Tool Items

A tool item is an item that a user can highlight and use to interact with a map. The format of a tool item definition is:

Tool {"item name"} hpos, vpos {options}

Icons: list_of_icons

{do

endItem}

When the user clicks on a tool item, it becomes the active tool and the previously active tool becomes inactive. There is only one active tool in the system at a time. You can get and set the current Tool item:

GISDK Function	Summary
GetTool()	Gets the name of the active tool item
SetTool()	Sets the active tool item

If the do ... endItem section of the tool definition is included, the statements are executed when the user clicks on the active map window while the tool is the active tool. The statements are not executed when the user clicks on the tool. The width and height of the tool are automatically determined from the icons.

Tool Options	Description
Disabled	The tool is initially disabled.
Hidden	The tool is initially hidden.
Help: help_specs	Help information displayed in a popup window and the status bar. Help strings can be string expressions.
Icon: icon	icon specifies the location of the button graphic, and can be a string constant or a string expression. If the string specifying the icon is of the format filename.bmp\|i, where i is an integer, the bitmap file is assumed to contain a row of square icons, with no gaps between the icons, and the ith icon in the row will be displayed. The graphic of the icon should not contain borders, as any outlining of the button is now handled automatically.
Cursor: cursor_name	Allows a cursor style to be specified, from the list below. If it is not specified, the default "Crosshair" style will be used.

The cursor_name is specified as one of the following strings:

Name	Maptitude Tool
Arrow	Select by Pointing
Center	Pan
Circle	Freehand Circle
Curve	Freehand Curve
Line	Freehand Line
Poly	Freehand Shape
Rectangle	Freehand Rectangle
Info	Info
Label-one	Manual Labels
Text	Freehand Text
Zoom-in	Zoom In
Zoom-out	Zoom Out

Once the user has clicked on the active map window, the GISDK functions called in the do ... endItem section of the tool definition determine the type of interaction with the map. For example, ClickCoord() allows the user to click a single point and returns the coordinate where the user clicked:

Tool 25, 2 Icon: "buttons.bmp|10" do

location = ClickCoord()

RunMacro("Update info", location)

endItem

There are a variety of GISDK functions allowing different types of interaction:

GISDK Function	Summary
ClickCoord()	Awaits user input from the system pointer and returns a coordinate
ClickLine()	Awaits user input from the system pointer and returns two coordinates that define a line
ClickPolyline()	Awaits user input from the system pointer and returns an array of coordinates that define a line
ClickRect()	Awaits user input from the system pointer and return two coordinates that define a rectangle
ClickEllipse()	Awaits user input from the system pointer and returns coordinates that define an ellipse
ClickCircle()	Awaits user input from the system pointer and returns a circle
ClickCurve()	Awaits user input of control points from the system pointer and returns an array of coordinates that define a curve
ClickShape()	Awaits user input from the system pointer and returns an array of coordinates that define a closed polygon
ClickScope()	Awaits user input from the system pointer, accepts a rectangle, and returns a scope
ClickRectScope()	Awaits user input from the system pointer, accepts a rectangle whose center is a valid world point, and returns a scope
ClickEllipseScope()	Awaits user input from the system pointer, accepts an ellipse, and returns a scope
ClickDragAndShow()	Allows a user to pan a map by dragging it to a new position
ClickLayout()	Allows user to edit annotations in the current map or layout

When a tool item has been given the Cursor option and it is the current tool being used, the system pointer will have this as its default cursor style while it is over the map (or layout), unless the cursor style is temporarily changed by a call to SetCursor().

Here is an example:

Tool 25, 2 Icons: "zoom1.bmp", "zoom2.bmp" Cursor: "Zoom-in"do

location = ClickCoord()

ZoomAndCenterMap(null, 0.5, location)

endItem