Alter Menu statement - MapBasic - 2023

Purpose

Adds or removes items from an existing menu.

Syntax 1

Alter Menu { menuname | ID menu_id } 
	Add menudef [ , menudef... ] 

Where each menudef defines a menu item, according to the syntax:

	newmenuitem 
	[ ID menu_item_id ] 
	[ HelpMsg help ] 
	[ { Calling handler | As menuname } ] 

menuname is the name of an existing menu (for example, "File").

menu_id is a standard integer menu ID from 1 to 64; 1 represents the File menu.

newmenuitem is a string, the name of an item to add to the specified menu.

menu_item_id is a custom integer menu item identifier, which can be used in subsequent Alter Menu Item statements.

help is a string that will appear on the status bar while the menu item is highlighted.

handler is the name of a procedure, or a code for a standard menu command (e.g., M_FILE_NEW), or a special syntax for handling the menu event by calling OLE or DDE. If you specify a command code for a standard MapInfo Pro Show/Hide command (such as M_WINDOW_STATISTICS), the newmenuitem string must start with an exclamation point and include a caret (^), to preserve the item's Show/Hide behavior. For more details on the different types of handler syntax, see the Create Menu statement.

Syntax 2

Alter Menu { menuname | ID menu_id }
	Remove { handler | submenuname | ID menu_item_id } 
		[ , { handler | submenuname | ID menu_item_id } ... ] 

menuname is the name of an existing menu.

menu_id is an integer menu ID from 1 to 64; 1 represents the File menu.

handler is either the name of a sub procedure or the code for a standard MapInfo Pro command.

submenuname is the name of a hierarchical submenu to remove from the specified menu.

menu_item_id is a custom integer menu item identifier.

Description

The Alter Menu statement adds menu items to an existing menu or removes menu items from an existing menu.

The statement can identify the menu to be modified by specifying the name of the menu (e.g., "File") through the menuname parameter.

If the menu to be modified is one of the standard MapInfo Pro menus, the Alter Menu statement can identify which menu to alter by using the ID clause. The ID clause identifies the menu by a number from 1 to 64. The following table lists the names and ID numbers of all standard MapInfo Pro menus.

The following are shortcut menus, which appear when the user clicks with the right mouse button.

When altering a Custom menu (even if you create it with an Custom ID, such as 999), you are required to use the Custom menuname, not the Custom ID, to alter it.

Examples

The following statement adds an item to the File menu.

Alter Menu "File" Add 
	"Special" Calling sub_procedure_name

In the following example, the menu to be modified is identified by its number.

Alter Menu ID 1 Add 
	"Special" Calling sub_procedure_name

In the following example, the menu item that is added contains an ID clause. The ID number (300) can be used in subsequent Alter Menu Item statements.

Alter Menu ID 1 Add 
	"Special" ID 300 Calling sub_procedure_name

The following example removes the custom item from the File menu.

Alter Menu ID 1 Remove sub_procedure_name

The sample program, TextBox, uses a Create Menu statement to create a menu called "TextBox," and then issues the following Alter Menu statement to add the TextBox menu as a hierarchical menu located on the Tools menu:

Alter Menu "Tools" Add 
	"(-", 
	"TextBox" As "TextBox" 

The following example adds a custom command to the Map window's shortcut menu (the menu that appears when an MapInfo Pro user right-clicks on a Map window).

Alter Menu ID 17 Add
	"Find Nearest Site" Calling sub_procedure_name

See Also:

Alter Menu Bar statement, Alter Menu Item statement, Create Menu statement, Create Menu Bar statement