NewCtrlMenuItem

int NewCtrlMenuItem (int panelHandle, int controlID, char itemLabel[], int beforeMenuItemID, CtrlMenuCallbackPtr eventFunction, void *eventCallbackData);

Purpose

Adds a new menu item to the menu owned by the specified control and returns the new menu item ID that you can use in subsequent calls to specify the menu item.

Only table and tree controls own menus.

Parameters

Input
Name Type Description
panelHandle integer Specifier for a particular panel that is currently in memory. You obtain this handle from LoadPanel, NewPanel, or DuplicatePanel.
controlID integer The defined constant, located in the .uir header file, that you assigned to the control in the User Interface Editor, or the ID returned by NewCtrl or DuplicateCtrl.
itemLabel char [] The name of the new menu item.

To add an underline accelerator to an item name, precede the letter to be underlined with two underscores; for example __Open.
beforeMenuItemID integer The menu item ID above which to insert the new menu item.

You obtain the menuItemID from NewCtrlMenuItem or NewCtrlMenuSeparator, or the menuItemID is a constant that identifies one of the built-in control menu items. The following lists the built-in menu item constants:

Constant Name Constant Value Control Type
VAL_GOTO –2 Table
VAL_SEARCH –3 Table, Tree
VAL_SORT –4 Table, Tree
VAL_EXPAND_SUBTREE –5 Tree
VAL_COLLAPSE_SUBTREE –6 Tree
VAL_EXPAND_ALL –7 Tree
VAL_COLLAPSE_ALL –8 Tree
To place the new menu item at the end (bottom) of the menu item list, pass –1.
eventFunction CtrlMenuCallbackPtr The name of the function that processes the menu callback. This event function, type CtrlMenuCallbackPtr, takes the following form:

void CVICALLBACK FunctionName (int panelHandle, int controlID, int MenuItemID, void *callbackData);

When a menu selection generates a commit event, this function receives the panelHandle and controlID of the control that owns the menu generating the event and the Menu Item ID corresponding to the menu item selected. This function also receives the value you pass to eventCallbackData.
eventCallbackData void * Points to data that you define. The callback function receives the pointer.

If you do not need to pass user-defined data to the callback function, or if you are not using a callback function to process the menu item event, you can use a value of zero.

Return Value

Name Type Description
menuItemID integer Returns the ID that you use to specify this menu item in subsequent function calls. Negative values indicate that an error occurred. Zero is not a valid ID.

Code Error Message String
xx (Menu item ID) Success