LoadMenuBarEx
int LoadMenuBarEx (int destinationPanelHandle, char filename[], int menuBarResourceID, void *callingModuleHandle);
Purpose
Loads a menu bar into memory from a user interface resource (.uir) file or text user interface (.tui) file you created in the User Interface Editor. LoadMenuBarEx is similar to LoadMenuBar, except that the callback functions you reference in your .uir file can be defined in the DLL that contains the call to LoadMenuBarEx.
When you call LoadMenuBar, the User Interface Library attempts to find the callback functions referenced in the .uir file. It searches the symbols you define in the project or in object or library modules. It does not search symbols that you define in, but do not export from, a DLL.
If you want to load a menu bar in a DLL that defines, but does not export, the menu callback functions, use LoadMenuBarEx. You must specify the module handle of the DLL in the callingModuleHandle parameter. You can do this by using the predefined variable __CVIUserHInst. If you pass zero for the callingModuleHandle, the function behaves identically to LoadMenuBar.
LoadMenuBarEx first searches the DLL symbols to find the callback functions referenced in the .uir. If any callback functions exist that it cannot find, it then searches for them in the same manner as LoadMenuBar.
LoadMenuBarEx expects the DLL to contain a table of the callback functions referenced by the .uir files that the DLL loads. If you create the DLL in LabWindows/CVI, LabWindows/CVI includes the table for you automatically. If you create the DLL using an external compilerexternal compiler, you must arrange for this table to be included in the DLL. You can do this by using the Build»External Compiler Support command in the Workspace window. You must have a LabWindows/CVI project that lists all the .uir files the DLL loads. In the External Compiler Support dialog box, specify the name of an object file to contain the table of callback function names. Then click the Create button to create the object file. You must include the object file in the external compiler project you use to create the DLL.
The External Compiler Support information is contained in the LabWindows/CVI project file. If that project file is loaded and you modify and save any of the .uir files, LabWindows/CVI automatically regenerates the object file.
The ATTR_REPORT_LOAD_FAILURE and ATTR_ALLOW_MISSING_CALLBACKS system attributes affect how this function behaves when it encounters an error. When you run a program in LabWindows/CVI and you enable debugging and the Run»Break on»Library Errors option, a message appears when a LabWindows/CVI function returns an error. In general, this feature is not available when debugging is disabled. However, there is a special system attribute to enable error messages for LoadPanel, LoadPanelEx, LoadMenuBar, and LoadMenuBarEx. By default, the attribute is enabled.
By default, LoadMenuBar returns an error if any of the callback functions referenced in the .uir for the menu bar cannot be found in the project. If you want to allow a menu bar to be loaded in this case, enable the ATTR_ALLOW_MISSING_CALLBACKS attribute using the SetSystemAttribute function.
Refer to the list of system attributes for more information.
Parameters
| Input | ||
| Name | Type | Description |
| destinationPanelHandle | int | |
| filename | char [] | Name of the .uir or .tui that contains the menu bar. You can use a complete pathname or a simple filename. If the name is a simple filename that contains no directory path, the file is loaded from the directory containing the executable or DLL specified by the callingModuleHandle parameter. If you enable the Embed project .UIRs option in the Target SettingsTarget Settings dialog box, you must use a simple pathname. If you use a complete pathname, the project will always look for the .uir file on disk, even if the file is embedded in the project. You must call LoadMenuBarEx with a valid calling module handle to load an embedded .uir file from a DLL. |
| menuBarResourceID | int | Defined constant you assigned to the menu bar in the User Interface Editor. The menuBarResourceID is in the .uir header file, and you use it only to load the menu bar into memory. You use the menu bar handle that this function returns to refer to the menu bar in subsequent function calls. When you load a menu bar from a .tui file, the menuBarResourceID parameter must be the header number of the .tui file section that defines the panel. For example, if the section header for the desired menubar is [MenuBar003], pass 3 as the Menu Bar Resource ID. This function loads all of the menus and menu items in the .tui file whose section headers take the form [MenuBarNNN_...], where NNN is the menuBarIDResourceID. The menu ID or menu item ID that you pass to User Interface Library functions is based on a depth-first traversal of all of the items in the menu tree, starting at 2. For submenu items, the submenu has an ID that is one greater than the item ID of the submenu entry in the parent menu. If you save a .tui file in the User Interface Editor in LabWindows/CVI 5.0 or later, and you have an up-to-date include file (.h) that the User Interface Editor generated, you can use the menu bar, menu, submenu, and menu item constants in the include file as parameters to User Interface Library functions. |
| callingModuleHandle | void * | The handle of the DLL in which to search for the callback functions referenced in the .uir. In almost all cases, this is the handle of the DLL in which the call to LoadMenuBarEx is compiled. Use the default parameter, __CVIUserHInst, to specify the handle of the module that contains the call to LoadMenuBarEx. A value of 0 indicates your executable. If you pass 0, the function behaves identically to LoadMenuBar. |
Return Value
| Name | Type | Description |
| menuBarHandle | int | The handle you can use in subsequent function calls to specify this menu bar. Negative values indicate that an error occurred. Zero is not a valid handle. |
Additional Information
Library: User Interface Library
Include file: userint.h
LabWindows/CVI compatibility: LabWindows/CVI 4.0 and later