Programming with Menu Bars

You can use menu bar functions to create and interact with menu bars programmatically.

Creating a Menu Bar

NewMenuBar creates a new menu bar during program execution and returns a handle that you can use to reference the menu bar in subsequent operations. Use the destinationPanelHandle parameter to specify a panel on which to locate the menu bar. Use NewMenu, NewSubMenu, and NewMenuItem to construct the pull-down menu system.

Adding a Menu Bar to a User Interface

LoadMenuBar loads into memory a menu bar you created in the User Interface Editor using the Edit Menu BarEdit Menu Bar dialog box and saved in a .uir file. When you call LoadMenuBar, refer to the menu bar using the constant name that you assigned to the menu bar in the Edit Menu Bar dialog box. LoadMenuBar returns a handle that you can use to refer to the menu bar in subsequent calls to User Interface Library functions. Use LoadMenuBarEx instead of LoadMenuBar to load a menu bar from a DLL if the DLL contains the callback functions for the menu callbacks. After you load a menu bar, it generates user events when the user selects menu bar commands.

SetPanelMenuBar assigns a menu bar to a panel. You can assign a panel only one menu bar at a time. Multiple panels can share the same menu bar.

GetPanelMenuBar gets the menu bar handle associated with a panel.

GetSharedMenuBarEventPanel gets the handle of the panel on which a menu bar event occurred. This action is useful when multiple panels share a menu bar. You need this function only when using GetUserEvent; menu callback functions receive the panel handle as a parameter.

Customizing a Menu Bar

You can use SetMenuBarAttribute to customize the appearance of a menu bar, menu, submenu, or menu item. Specify a font to use for the menu system with the ATTR_MENU_BAR_FONT attribute. Set shortcut keys for menu items with the ATTR_SHORTCUT_KEY attribute. Use the ATTR_DIMMED attribute to specify which menu bars, menus, submenus, and menu items appear dimmed. You also can associate images with menu items. First, use the ATTR_SHOW_IMAGES attribute to add a column in the menu in which images can be placed. Then use the ATTR_ITEM_BITMAP attribute to specify an image to use for a submenu or menu item.

GetMenuBarAttribute obtains a particular menu bar, menu, submenu, or menu item attribute.

InsertSeparator programmatically places a dividing line between menu items.

By default, immediate action menus contain an exclamation mark following the menu name. You can use the SetMenuBarAttribute function and set the ATTR_SHOW_IMMEDIATE_ACTION_SYMBOL attribute to false to hide the exclamation mark.

Removing a Menu Bar

Use EmptyMenu to remove the contents of a particular menu or submenu. EmptyMenuBar removes the menu bar from the screen and destroys its contents but does not destroy the menu bar handle.

Use DiscardMenuItem and DiscardSubMenu to remove menu items and submenu items from the menu bar and from memory. DiscardMenuBar removes the menu bar from the screen and frees its handle from memory.

Processing Menu Bar Events

You can process menu bar events in the following ways:

• Assign callback functions to menu items and immediate action menus. When a commit event is generated, the appropriate callback function executes.
• Use an event loop that includes a call to GetUserEvent. When a commit event is generated, GetUserEvent returns the appropriate menu bar handle and menu item ID, and the program conditionally executes portions of code. Commit events are generated when the user selects a menu item or immediate action menu.

Note  Menu items and immediate action menus do not cause GetUserEvent to return with status information if they have a callback defined. If you want the callback to run and GetUserEvent to return, you must use QueueUserEvent in the menu callback with the appropriate handle and menu item information.

Using Callback Functions

If you create a menu bar in the User Interface Editor, you can assign callback function names to menu items and immediate action menus from within the editor. When LoadMenuBar loads the menu bar, LabWindows/CVI automatically installs your callback functions and calls them whenever commit events are generated on menu items and immediate action menus.

If you use NewMenuBar to create your menu bar programmatically, you can use InstallMenuCallback to install callback functions for immediate action menus. Menu item callbacks are installed as a parameter to NewMenuItem. Your callback functions are then called whenever commit events are generated on menu items or immediate action menus. Use the MenuCallbackPtr typedef from userint.h as a model to declare your menu callback functions in your program.

You also can use InstallMenuDimmerCallback to install a callback function that is called just before a pull-down menu appears when the user clicks a menu bar or presses a menu shortcut key. In this callback function, you can update the state of menu items before the pull-down menu appears. You can add or delete menu items, dim or undim menu items, add or remove checkmarks next to menu items, or change the names of menu items. Use the MenuDimmerCallbackPtr typedef from userint.h as a model to declare this callback function in your program.

Initiate the callback mechanism by calling RunUserInterface or by starting a GetUserEvent loop.

Using Event Loops

When the user generates a commit event on a menu item or immediate action menu, GetUserEvent returns the appropriate menu bar handle and menu ID. GetUserEvent can operate in one of the following ways:

• Waits for the user to generate an event before returning to the calling program.
• Returns immediately whether or not an event has occurred. If a menu event occurred, GetUserEvent returns a valid menu or menu item ID.