ToolHandler procedure - MapBasic - 2023

Purpose

A reserved procedure name; works in conjunction with a special ToolButton (the MapBasic tool).

Syntax

Declare Sub ToolHandler 
Sub ToolHandler 
	 statement_list 
End Sub 

statement_list is a list of statements to execute when the user clicks with the MapBasic tool.

Description

ToolHandler is a special-purpose MapBasic procedure name, which operates in conjunction with the MapBasic tool.

Defining a ToolHandler procedure is a simple way to add a custom button to MapInfo Pro's Main ButtonPad. However, the button associated with a ToolHandler procedure is restricted; you cannot use custom icons or drawing modes with the ToolHandler's button. To create a custom button which has no restrictions, use the Alter ButtonPad statement and Create ButtonPad statement statements.

If the user runs an application which contains a procedure named ToolHandler, a plus-shaped tool (the MapBasic tool) appears on the Main ButtonPad. The MapBasic tool is enabled whenever a Browser, Map, or Layout window is the active window. If the user selects the MapBasic tool and clicks in the Browser, Map, or Layout window, MapBasic automatically calls the ToolHandler procedure.

A ToolHandler procedure can use the CommandInfo() function to determine where the user clicked. If the user clicked in a Browser, the CommandInfo() function returns the row and column where the user clicked. If the user clicked in a Map, the CommandInfo() function returns the map coordinates of the location where the user clicked; these coordinates are in MapBasic's current coordinate system (see Set CoordSys statement).

If the user clicked in a Layout window, the CommandInfo() function returns the layout coordinates (for example, distance from the upper left corner of the page) where the user clicked; these coordinates are in MapBasic's current paper units (see Set Paper Units statement).

By calling the CommandInfo() function, you can also detect whether the user held down the Shift key and/or the Ctrl key while clicking. This allows you to write applications which react differently to click events than to Shift+click events.

To make the MapBasic tool the active tool, issue the statement:

Run Menu Command M_TOOLS_MAPBASIC 

For a ToolHandler procedure to take effect, the user must run the application. If an application contains a special procedure name―such as ToolHandler―the application "goes to sleep" when the Main procedure runs out of statements to execute.

The Main procedure may be explicit or implied. The application is said to be "sleeping" because the ToolHandler procedure is still in memory, although it may be inactive. If the user selects the MapBasic tool and clicks with it, MapBasic automatically calls the ToolHandler procedure, so that the procedure may react to the click event.

When any procedure in an application executes the End Program statement, the application is completely removed from memory. That is, a program which executes an End Program statement is no longer sleeping-it is terminated altogether. So, you can use the End Program statement to terminate a ToolHandler procedure once it is no longer wanted. Conversely, you should be careful not to issue an End Program statement while the ToolHandler procedure is still needed.

Depending on the circumstances, a ToolHandler procedure may need to issue a Set CoordSys statement before determining the coordinates of where the user clicked. If the ToolHandler procedure is called because the user clicked in a Browser, no Set CoordSys statement is necessary. If the user clicks in a Layout window, the ToolHandler procedure may need to issue a Set CoordSys Layout statement before determining where the user clicked in the layout. If the user clicks in a Map window, and the application's current coordinate system does not match the coordinate system of the Map (because the application has issued a Set CoordSys statement), the ToolHandler procedure may need to issue a Set CoordSys statement before determining where the user clicked in the map.

Example

The following program sets up a ToolHandler procedure that will be called if the user selects the MapBasic tool, then clicks on a Map, Browser, or Layout window. In this example, the ToolHandler simply displays the location where the user clicked.

Include "mapbasic.def" 
Declare Sub ToolHandler
Note "Ready to test the MapBasic tool." 

Sub ToolHandler 
	Note "x:" + Round(CommandInfo(CMD_INFO_X), 0.1) + Chr$(10) +
		" y:" + Round(CommandInfo(CMD_INFO_Y), 0.1) 
End Sub

See Also:

CommandInfo() function