Create Menu statement - MapBasic - 2023

Purpose

Creates a new menu, or redefines an existing menu. In MapInfo Pro 64-bit, this command creates a new menu in the Menu ribbbon group under the LEGACY tab. You can issue this statement from the MapBasic window in MapInfo Pro.

Syntax 1

Create Menu newmenuname [ ID menu_id ] [ Context ] As 
	menuitem [ ID menu_item_id ] [ HelpMsg help ] 
	{ Calling handler | As menuname } 
	[ , menuitem ... ] 

Syntax 2

Create Menu newmenuname As Default 

newmenuname is a string representing the name of the menu to define or redefine.

menuitem is a string representing the name of an item to include on the new menu.

Context is reserved for internal use only; not usable in MapBasic programs.

menu_id is a SmallInt ID number from one to fifteen, identifying a standard menu.

menu_item_id is an integer ID number that identifies a custom menu item.

help is a string that appears on the status bar whenever the menu item is highlighted.

handler is the name of a procedure, or a code for a standard menu command, or a special syntax for handling the menu event by calling OLE or DDE; see Calling Clause Options. If you specify a command code for a standard MapInfo Pro Show/Hide command (such as M_WINDOW_STATISTICS), the menuitem string must start with an exclamation point and include a caret (^), to preserve the item's Show/Hide behavior.

menuname is the name of an existing menu to include as a hierarchical submenu.

Description

If the newmenuname parameter matches the name of an existing MapInfo Pro menu (such as File), the statement re-defines that menu. If the newmenuname parameter does not match the name of an existing menu, the Create Menu statement defines an entirely new menu. For a list of the standard MapInfo Pro menu names, see Alter Menu statement.

The Create Menu statement does not automatically display a newly-created menu; a new menu will only display as a result of a subsequent Alter Menu Bar statement or Create Menu Bar statement. However, if a Create Menu statement modifies an existing menu, and if that existing menu is already part of the menu bar, the change will be visible immediately.

The menuitem parameter identifies the name of the menu item. The item's name can contain special control characters to define menu item attributes (for example, whether a menu item is checkable). See tables below for details.

The following characters require special handling: slash (/), back slash(\), and less than (<). If you want to display any of these special characters in the menu or the status bar help, you must include an extra back slash in the menuitem string or the help string. For example, the following statement creates a menu item that reads, "Client/Server."

Create Menu "Data" As
	"Client\/Server" Calling cs_proc 

If a menuitem parameter begins with the character @, the custom menu breaks into two columns. The item whose name starts with @ is the first item in the second column.

Assigning Handlers to Custom Menu Items

Most menu items include the Calling handler clause; where handler is either the name of a MapBasic procedure or a numeric code identifying an MapInfo Pro operation (such as M_FILE_SAVE to specify the Save Table command). If the user chooses a menu item which has a handler, MapBasic automatically calls the handler (whether the handler is a sub procedure or a command code). Your program must Include the file MENU.DEF if you plan to refer to menu codes such as M_FILE_SAVE.

The optional ID clause lets you assign a unique integer ID to each custom menu item. Menu item IDs are useful if you want to allow multiple menu items to call the same handler procedure. Within the handler procedure, you can determine which menu item the user chose by calling CommandInfo(CMD_INFO_MENUITEM). Menu item IDs can also be used by other statements, such as the Alter Menu Item statement. If a menu item has neither a handler nor a menuname associated with it, that menu item is inert. Inert menu items are used for cosmetic purposes, such as displaying horizontal lines which break up a menu.

Creating Hierarchical Menus

To include a hierarchical menu on the new menu, use the As sub-clause instead of the Calling sub-clause. The As sub-clause must specify the name of the existing menu which should be attached to the new menu. The following example creates a custom menu containing one conventional menu item and one hierarchical menu.

Create Menu "Special" As 
	"Configure" Calling config_sub_proc, 
	"Objects" As "Objects" 

When you add a hierarchical menu to the menu, the name of the hierarchical menu appears on the parent menu instead of the menuitem string.

Properties of a Menu Item

Menu items can be enabled or disabled; disabled items appear grayed out. Some menu items are checkable, meaning that the menu can display a check mark next to the item. At any given time, a checkable menu item is either checked or unchecked.

To set the properties of a menu item, include control codes (from the table below) at the start of the menuitem parameter.

(

(-

($ 

(> 

!

! ... ^ ... 

!+

Defining Keyboard Shortcuts

Menu items can have two different types of keyboard shortcuts, which let the user choose menu items through the keyboard rather than by clicking with the mouse.

One type of keyboard shortcut lets the user drop down a menu or choose a menu item by pressing keys. For example, on MapInfo Pro, the user can press Alt+W to show the Window menu, then press M (or Alt-M) to choose New Map Window. To create this type of keyboard shortcut, include the ampersand character (&) in the newmenuname or menuitem string (for example, specify "&Map" as the menuitem parameter in the Create Menu statement). Place the ampersand immediately before the character to be used as the shortcut.

The other type of keyboard shortcut allows the user to activate an option without going through the menu at all. If a menu item has a shortcut key sequence of Alt+F5, the user can activate the menu item by pressing Alt+F5. To create this type of shortcut, use the following key sequences.

/W {letter | %number}

/W# {letter | %number}

/W@ {letter | %number}

/W^ {letter | %number}

To specify a function key as a Windows accelerator, the accelerator code must include a percent sign (%) followed by a number. The number 112 corresponds to F1, 113 corresponds to F2, etc.

After altering a standard MapInfo Pro menu (for example, "File"), you can restore the menu to its original state by issuing a Create Menu menuname As Default statement.

Calling Clause Options

The Calling clause specifies what should happen when the user chooses the custom menu command. 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 Pro). The remainder of the string contains a comma-separated list of the values returned from relevant CommandInfo() function calls. For complete details on the string syntax, see the MapBasic User Guide.

Examples

The following example uses the Create Menu statement to create a custom menu, then adds the custom menu to MapInfo Pro's menu bar. This example removes the Window menu (ID 6) and the Help menu (ID 7), and then adds the custom menu, the Window menu, and the Help menu back to the menu bar. This technique guarantees that the last two menus will always be Window, and Help.

Declare Sub Main 
Declare Sub addsub
Declare Sub editsub
Declare Sub delsub
Sub Main 
	Create Menu "DataEntry" As
		"Add" Calling addsub,
		"Edit" Calling editsub,
		"Delete" Calling delsub

	Alter Menu Bar Remove ID 6, ID 7 
	Alter Menu Bar Add "DataEntry", ID 6, ID 7
End Sub 

The following example creates an abbreviated version of the File menu. The "(" control character specifies that the Close, Save, and Print options will be disabled initially. The Open and Save options have Windows accelerator key sequences (Ctrl+O and Ctrl+S, respectively). Note that both the Open and Save options use the Chr$(9) function to insert a Tab character into the menu item name, so that the remaining text is shifted to the right.

Include "MENU.DEF"

Create Menu "File" As
	"New" Calling M_FILE_NEW,
	"Open" +Chr$(9)+"Ctrl+O/W^O" Calling M_FILE_OPEN,
	"(-",
	"(Close" Calling M_FILE_CLOSE,
	"(Save" +Chr$(9)+"Ctrl+S /W^S" Calling M_FILE_SAVE,
	"(-",
	"(Print" Calling M_FILE_PRINT,
	"(-", 
	"Exit" Calling M_FILE_EXIT 

If you want to prevent the user from having access to MapInfo Pro's shortcut menus, use a Create Menu statement to re-create the appropriate menu, and define the menu as just a separator control code: "(-". The following example uses this technique to disable the Map window's shortcut menu.

Create Menu "MapperShortcut" As "(-" 

See Also: