Alter ButtonPad statement - MapBasic - 2023

Purpose

Displays / hides a ButtonPad (toolbar), or adds / removes buttons. In the 64-bit version, does the same with ribbon groups. Also allows to modify an already created button pad, if the ButtonPad does not exist then MIPro would automatically create that ButtonPad. In the 64-bit version, does the same with ribbon groups.

Syntax

Alter ButtonPad { current_title | ID pad_num }
	[ Add button_definition [ button_definition ... ] ] 
	[ Remove { handler_num | ID button_id } [ , ... ] ]
	[ Title new_title ]
	[ Tab tab_name | tab_caption ]
	[ Width width ] 
	[ Position ( x, y ) [ Units unit_name ] ]
	[ ToolbarPosition ( row, column ) ]
	[ { Show | Hide } ] 
	[ { Fixed | Float | Top | Left | Right | Bottom } ] 
	[ Destroy ]

current_title is the toolbar's title string (e.g., "Main").

pad_num is the ID number for a standard toolbar:

• 1 for Main
• 2 for Drawing
• 3 for Tools
• 4 for Standard
• 5 for Database Management System (DBMS)
• 6 Web Services
• 7 Reserved

handler_num is an integer handler code, such as M_TOOLS_RULER (1710), from MENU.DEF.

button_id is a custom button's unique identification number.

new_title is a string that becomes the toolbar's new title; visible when toolbar is floating. In MapInfo Pro 64-bit, this is the caption of the ribbon group.

width is the pad width, in terms of the number of buttons across. Not suppported in the 64-bit version of MapInfo Pro.

x, y specify the toolbar's position when floating; specified in paper units. For details about paper units, see Set Paper Units statement. Not suppported in the 64-bit version of MapInfo Pro.

unit_name is a string paper unit name (e.g., "in" for inches, "cm" for centimeters). Not suppported in the 64-bit version of MapInfo Pro.

row, column specify the toolbar's position when docked (e.g., 0, 0 places the pad at the left edge of the top row of toolbars, and 0, 1 represents the second toolbar on the top row). Not suppported in the 64-bit version of MapInfo Pro.

• row position starts at the top and increases in value going to the bottom. It is a relative value to the rows existing in the same position (top or bottom). When there is a menu bar in the same position, then the numbers become relative to the menu bar. When a toolbar is just below the menu bar, its row value is 0. If it is directly above the menu bar, then its row value is -1.
• column position starts at the left and increases in value going to the right. It is a relative value to the columns existing in the same position (left or right). For example, if a toolbar is docked to the left and the menu bar is docked to the left position, then the column number for the column left of the menu bar is -1. The column number for the column to the right of the menu bar is 0.

Each button_definition clause can consist of the keyword Separator, or it can have the following syntax:

{ PushButton | ToggleButton | ToolButton } 
	Calling { procedure | menu_code | OLE methodname | DDE server, topic } 
	[ ID button_id ]
	[ Small | ExtraSmall | Large Icon icon_code [ File file_spec ] ] 
	[ Cursor cursor_code [ File file_spec ] ] 
	[ DrawMode dm_code ] 
	[ HelpMsg msg ]
	[ ModifierKeys { On | Off } ] 
	[ { Enable | Disable } ] 
	[ { Check | Uncheck } ]

procedure is the handler procedure to call when a button is used.

menu_code is a standard MapInfo Pro menu code from MENU.DEF, such as M_FILE_OPEN (102); MapInfo Pro runs the menu command when the user uses the button.

methodname is a string specifying an OLE method name. For details on the Calling OLE clause syntax, see Create ButtonPad statement.

server and topic are strings specifying a DDE server and topic name. For details on the Calling DDE clause syntax, see Create ButtonPad statement.

button_id specifies the unique button number. This number can be used: as a tag in help; as a parameter to allow the handler to determine which button is in use (in situations where different buttons call the same handler); or as a parameter to be used with the Alter Button statement.

Icon icon_code specifies the icon to appear on the button; icon_code can be one of the standard MapInfo icon codes listed in ICONS.DEF, such as MI_ICON_RULER (11). If the File sub-clause specifies the name of a file containing icon resources, icon_code is an integer resource ID identifying a resource in the file. The size of the button can be defined with resource file id of icon_code for small and icon_code+1 for large sized buttons, with resource file ids of icon_code and icon_code+1 respectively.

Small | ExtraSmall | Large specifies the size of the Icons.

Cursor cursor_code specifies the shape the mouse cursor should adopt whenever the user chooses a ToolButton tool; cursor_code is a code, such as MI_CURSOR_ARROW (0), from ICONS.DEF. This clause applies only to ToolButtons. If the File sub-clause specifies the name of a file containing icon resources, cursor_code is an integer resource ID identifying a resource in the file.

dm_code specifies whether the user can click and drag, or only click with the tool; dm_code is a code, such as DM_CUSTOM_LINE (33), from ICONS.DEF. Applies only to ToolButtons.

msg is a string that specifies the button's status bar help and, optionally, ToolTip help. The first part of msg is the status bar help message. If the msg string includes the letters \n then the text following the \n is used as the button's ToolTip help.

The ModifierKeys clause applies only to ToolButtons; it controls whether the Shift and control (Ctrl) keys affect "rubber-band" drawing if the user drags the mouse while using a ToolButton. Default is Off (modifier keys have no effect).

Description

Use the Alter ButtonPad statement to show, hide, modify, or destroy an existing ButtonPad. For an introduction to ButtonPads, see the MapBasic User Guide.

To show or hide a ButtonPad, include the Show or Hide keyword; see example below.

To set whether the pad is fixed to the top of the screen ("docked") or floating like a window, include the Fixed or the Float keyword. The user can also control whether the pad is docked or not by dragging the pad to or from the top of the screen. For more control over the location on the screen that the pad is docked to, use the Top (which is the same as using Fixed), Left, Right, or Bottom keywords.

When a pad is floating, its position is controlled by the Position clause; when a pad is docked, its position is controlled by the ToolbarPosition clause.

To destroy a ButtonPad, include the Destroy keyword. Once a ButtonPad is destroyed, it no longer appears in the Toolbars dialog box.

The Alter ButtonPad statement can add buttons to existing ButtonPads, such as Main and Drawing. There are three types of button controls you can add: PushButton controls (which the user can click and release-for example, to display a dialog box); ToggleButton controls (which the user can select by clicking, then deselect by clicking again); and ToolButton controls (which the user can select, and then use for clicking on a Map window or layout).

If you include the optional Disable keyword when adding a button, the button is disabled (grayed out) when it appears. Subsequent Alter Button statements can enable the button. However, if the button's handler is a standard MapInfo Pro command, MapInfo Pro automatically enables or disables the button depending on whether the command is currently enabled.

If you include the optional Check keyword when adding a ToggleButton or a ToolButton, the button is automatically selected ("checked") when it first appears.

If the user clicks while using a custom ToolButton tool, MapInfo Pro automatically calls the tool's handler, unless the user cancels (e.g., by pressing the Esc key while dragging the mouse). A handler procedure can call CommandInfo() to determine where the user clicked. If two or more tools call the same handler procedure, the procedure can call CommandInfo() to determine the ID of the button currently in use.

Alter ButtonPad "PushButtons" Add PushButton small

When altering a ButtonPad to remove a button, you must specify the name of the Tab where ButtonPad exists in order to remove it. For example,

alter buttonpad "MapFile" add pushbutton calling HelloRibbon Small icon 46 Title "Hello" helpmsg "help on hello" Tab "TabMap"

Custom Icons and Cursors

The Icon clause specifies the icon that appears on the button. If you omit the File clause, then the parameter n must refer to one of the icon codes listed in ICONS.DEF, such as MI_ICON_RULER (11).

The File file_spec sub-clause refers to a DLL file that contains bitmap resources; the n parameter refers to the ID of a bitmap resource. For more information on creating Windows icons, see the MapBasic User Guide.

A ToolButton definition also can include a Cursor clause, which controls the appearance of the mouse cursor while the user is using the custom tool. Available cursor codes are listed in ICONS.DEF, such as MI_CURSOR_CROSSHAIR (138) or MI_CURSOR_ARROW (0). The procedure for specifying a custom cursor is similar to the procedure for specifying a custom icon.

For custom icon size requirements for different MapInfo Pro versions, see Create ButtonPad statement About Icon Size.

Custom Drawing Modes

A ToolButton definition can include a DrawMode clause, which controls whether the user can drag with the tool (e.g., to draw a line) or only click (e.g., to draw a point). The following table lists the available drawing modes. Codes in the left column are defined in ICONS.DEF.

All of the draw modes except for DM_CUSTOM_POINT (34) support the Autoscroll feature, which allows the user to scroll a Map or layout by clicking and dragging to the edge of the window. To disable autoscroll, see Set Window statement.

Legacy behavior no longer supported with ButtonPads

Alter Button { handler | ID button_id }
[ { Enable | Disable } ][ { Check | Uncheck } ]

Alter ButtonPad command allows you to enable/disable or check/uncheck a control added to button pad group.

If you execute a check/uncheck on a MapInfo Pro run menu command then we will only check/uncheck controls which have an IsChecked property binding.

Example:

Alter ButtonPad ID 1 Add PushButton ID 23002 HelpMsg "Open Table" calling 102
Alter Button ID 23002 Enable
Alter Button ID 23002 Disable
Alter Button ID 23002 Check
Alter Button ID 23002 Uncheck 

Examples

The following example shows the Main ButtonPad and hides the Drawing ButtonPad:

Alter ButtonPad "Main" Show 
Alter ButtonPad "Drawing" Hide 

The next example docks the Main ButtonPad and sets its docked position to 0,0 (upper left):

Alter ButtonPad "Main" Fixed ToolbarPosition(0,0) 

The next example moves the Main ButtonPad so that it is floating instead of docked, and sets its floating position to half an inch inside the upper-left corner of the screen.

Alter ButtonPad "Main" Float Position(0.5,0.5) Units "in" 

The sample program, ScaleBar, contains the following Alter ButtonPad statement, which adds a custom ToolButton to the Tools ButtonPad. (Note that "ID 3" identifies the Tools ButtonPad.)

Alter ButtonPad ID 3
	Add 
		Separator
		ToolButton 
			Icon MI_ICON_CROSSHAIR 
			HelpMsg "Draw a distance scale on a map\nScale Bar" 
			Cursor MI_CURSOR_CROSSHAIR
			DrawMode DM_CUSTOM_POINT 
			Calling custom_tool_routine 
	Show 

See Also:

Alter Button statement, ButtonPadInfo() function, Create ButtonPad statement, Set Window statement