Alter Menu Item statement - MapBasic - 2023

Purpose

Alters the status of a specific menu item.

Syntax

Alter Menu Item { handler | ID menu_item_id } 
	{ [ Check | Uncheck ] | 
	 [ Enable | Disable ] | 
	 [ Text itemname ] | 
	 [ Calling handler | As menuname ] } 

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

menu_item_id is an integer that identifies a menu item; this corresponds to the menu_item_id parameter specified in the statement that created the menu item (Create Menu statement or Alter Menu statement).

itemname is the new text for the menu item (may contain embedded codes).

menuname is the name of an existing menu.

Description

The Alter Menu Item statement alters one or more of the items that make up the available menus. For example, you could use the Alter Menu Item statement to check or disable (gray out) a menu item.

The statement must either specify a handler (e.g., the name of a procedure in the same program), or an ID clause to indicate which menu item(s) to modify. Note that it is possible for multiple, separate menu items to call the same handler procedure. If the Alter Menu Item statement includes the name of a handler procedure, MapInfo Pro alters all menu items that call that handler. If the statement includes an ID clause, MapInfo Pro alters only the menu item that was defined with that ID.

The Alter Menu Item statement can only refer to a menu item ID if the statement which defined the menu item included an ID clause. A MapBasic application cannot refer to menu item IDs created by other MapBasic applications.

The Check clause and the Uncheck clause affect whether the item appears with a checkmark on the menu. Note that a menu item may only be checked if it was defined as "checkable" (for example, if the Create Map statement included a "!" as the first character of the menu item name).

The Disable clause and the Enable clause control whether the item is disabled (grayed out) or enabled. Note that MapInfo Pro automatically enables and disables various menu items based on the current circumstances. For example, the Close command is disabled whenever there are no tables open. Therefore, MapBasic applications should not attempt to enable or disable standard MapInfo Pro menu items. Similarly, although you can treat specific tools as menu items (by referencing defines from MENU.DEF, such as M_TOOLS_RULER), you should not attempt to enable or disable tools through the Alter Menu Item statement.

The Text clause allows you to rename a menu item.

The Calling clause specifies a handler for the menu item. If the user chooses the menu item, MapInfo Pro calls the item's handler.

Examples

The following example creates a custom "DataEntry" menu.

Declare Sub addsub
Declare Sub editsub
Declare Sub delsub
Create Menu "DataEntry" As 
	"Add" Calling addsub,
	"Edit" Calling editsub,
	"Delete" ID 100 Calling delsub, 
	"Delete All" ID 101 Calling delsub 
'Remove the Help menu
Alter Menu Bar Remove ID 7
'Add both the new menu and the Help menu 
Alter Menu Bar Add "DataEntry" , ID 7 

The following Alter Menu Item statement renames the "Edit" item to read "Edit..."

Alter Menu Item editsub Text "Edit..." 

The following statement disables the "Delete All" menu item.

Alter Menu Item ID 101 Disable 

The following statement disables both the "Delete" and the "Delete All" items, because it identifies the handler procedure delsub, which is the handler for both menu items.

Alter Menu Item delsub Disable

See Also:

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