Create ButtonPad statement - MapBasic - 2023

Purpose

In MapInfo Pro 64-bit, this command creates new tabs or tab groups on existing ribbon tabs. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax

Create ButtonPad { title_string | ID pad_num } As
 button_definition [ button_definition ... ] 
	[ Title title_string ]
	[ Tab tab_name | tab_caption ]
	[ Width width ]
	[ Position ( x, y ) [ Units unit_name ] ]
	[ ToolbarPosition ( row, column ) ]
	[ { Show | Hide } ] 
	[ { Fixed | Float | Top | Left | Right | Bottom } ] 

title_string is the ButtonPad title (for example, "Drawing"). Any whitespaces in the title would be stripped and any special characters masked.

pad_num is the ID number for the standard toolbar you want to re-define:

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

tab_name, tab_caption. When creating a new Tab, you can specify both the Tab Name and its Caption by separating them with the pipe symbol. For example, "MyNewTab | MyNewCaption"

To get the NAMES of existing Ribbon controls, build and run the ProSampleAddin provided with MapBasic and use its Dump Object Model tool.

(\MapBasic\Samples\RIBBONINTERFACE\DotNet\ProSampleAddIn)

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 pad's position when it is 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 representing paper units name (for example, "in" for inches, "cm" for centimeters). Not suppported in the 64-bit version of MapInfo Pro.

row, column specify the pad's position when it is docked as a toolbar (for example, 0, 0 places the pad at the left edge of the top row of toolbars, and 0, 1 represents the second pad 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 (for example, M_FILE_OPEN); MapInfo Pro runs the menu command when the user uses the button.

methodname is a string specifying an OLE method name.

server, topic are strings specifying a DDE server and topic name.

ID button_id specifies a unique button number. This number can be used as a parameter to allow a 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.

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.

DrawMode dm_code specifies whether the user can click and drag, or only click with the tool; dm_code is a code (for example, DM_CUSTOM_LINE) from ICONS.DEF. The DrawMode clause applies only to ToolButtons.

HelpMsg msg specifies the button's status bar help and, optionally, ToolTip help. The first part of the msg string 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.

ModifierKeys clause 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, meaning that the Shift and control (Ctrl) keys have no effect.

Description

Use the Create ButtonPad statement to create a custom ButtonPad. Once you have created a custom ButtonPad, you can modify it using Alter Button statement and Alter ButtonPad statement.

Each toolbar can be hidden. To create a toolbar in the hidden state, include the Hide keyword.

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 toolbar is floating, its position is controlled by the Position clause; when it is docked, its position is controlled by the ToolbarPosition clause.

For more information on ButtonPads, see the MapBasic User Guide. For additional information about the capabilities of ToolButtons, see Alter ButtonPad statement.

About Icon Size

Before MapInfo Pro 10.0, custom icons were rectangular in size: 18x16 for small icons and 26x24 for large icons. Toolbar and menu features introduced in MapInfo Pro 10.0 require square icons: 16x16 for small icons and 24x24 for large icons. MapInfo Pro 10.0 and later display custom icons in the square size distorting how they display. To correct the distortion MapInfo Pro removes the first and last column of pixels to not display them (cropping the image). As a result, there may be some loss of information in the icon image.

For best results, create your icons to 16x16 for small icons and 24x24 for large icons. Icons at these sizes are not compatible with versions before 10.0.1 and generate an error message in these versions.

For compatibility with versions before 10.0.1, use 18x16 for small icons and 26x24 for large icons. These icons appear distorted in version 10.0 and appear cropped in versions after 10.0.

About Icons for Menu Items

The following describe how MapInfo Pro 10.0 handles icons for menu items:

• Icons for menu items are dynamic based on icons in toolbars.
• If a toolbar button has an icon it may be used for a menu item if it meets one of the following requirements:
  • Toolbar button and menu item must be within the same MBX file.
  • The same handler/userId combination; any menu item that calls the same handler/userid from the same MBX file is assigned that icon).
  • The same userId calling different handlers.
  • The same handler, no userID.
  • ID must be <= 32767.
• For built in handlers, priority is given to find an icon from a built in toolbar. If none is found, then there is a search through the toolbar icons from the MBX files for a match.
• Small icons are shown next to menu items.
• When an MBX unloads, any of its associated icons are unloaded and are no longer in use for menu items.

The following describe how MapInfo Pro handles icons for menu items:

• Menu items can show an icon if a MapBasic application creates a toolbar button and menu item that meet the previously listed requirements for menu item icons.

Calling Clause Options

The Calling clause specifies what should happen when the user acts on the custom button. The following table describes the available syntax.

Calling M_FILE_NEW

Calling my_procedure

Calling OLE "methodname"

Calling DDE "server","topic"

In the last two cases, the string sent to OLE or DDE starts with the three letters "MI:" so that the server can detect that the message came from MapInfo. The remainder of the string contains a comma-separated list of the values returned from the function calls CommandInfo(1) through CommandInfo(8). For complete details on the string syntax, see the MapBasic User Guide.

Legacy Tab behavior when custom Tab or group name is not provided

Each new button pad would create a new ribbon group in LEGACY tab with all its button definitions in that newly created ribbon group with size form as large.

Each below predefined button pads ID would map to a ribbon group in LEGACY tab.

Other Legacy behavior changes

Examples

Create a button pad of utilities:

Create ButtonPad "Utils" As 
	PushButton 
		HelpMsg "Choose this button to display query dialog" 
		Calling button_sub_proc 
		Icon MI_ICON_ZOOM_QUESTION 
	ToolButton 
		HelpMsg "Use this tool to draw a new route" 
		Calling tool_sub_proc 
		Icon MI_ICON_CROSSHAIR 
		DrawMode DM_CUSTOM_LINE 
	ToggleButton
		HelpMsg "Turn proximity checking on/off" 
		Calling toggle_prox_check 
		Icon MI_ICON_RULER 
		Check 
	Title "Utilities" 
	Width 3
	Show 

Create a toolbar button that launches the Browser Preferences dialog, which has a menu command ID of 222:

Create ButtonPad "Prefs" As 
	PushButton 
		HelpMsg "Browser Preferences.\nBrowser Prefs"
		Calling 222 
		Icon 99 

See Also:

Alter Button statement, Alter ButtonPad statement, ButtonPadInfo() function