LoadPanelEx
- Updated2023-02-21
- 5 minute(s) read
LoadPanelEx
int LoadPanelEx (int parentPanelHandle, char filename[], int panelResourceID, void *callingModuleHandle);
Purpose
Loads a panel into memory from a user interface resource (.uir) file or text user interface (.tui) file created in the User Interface Editor. LoadPanelEx is similar to LoadPanel, except that the callback functions you reference in your .uir file can be defined in the DLL that contains the call to LoadPanelEx.
When you call LoadPanel, LabWindows/CVI attempts to find the callback functions referenced in the .uir file. LabWindows/CVI 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 panel in a DLL that defines, but does not export, the panel callback functions, use LoadPanelEx. 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 LoadPanel.
LoadPanelEx 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 LoadPanel.
LoadPanelEx expects the DLL to contain a table of the callback functions referenced by the .uir files the DLL loads. If you create the DLL in LabWindows/CVI, LabWindows/CVI includes the table 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 option in the in the Workspace window. You must have a LabWindows/CVI project that lists all the .uir files that 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, LoadPanel returns an error if LabWindows/CVI cannot find in the project any of the callback functions referenced in the .uir for the panel. If you want to allow a panel 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 |
| parentPanelHandle | int | Handle of the panel into which to load the panel as a child panel. Pass 0 to load the panel as a top-level window. You can obtain this handle from functions such as LoadPanel and NewPanel. |
| filename | char [] | Name of the .uir or .tui that contains the panel. You can use a complete pathname or a simple filename for filename. If the name is a simple filename that contains no directory path, the file is loaded from the directory that contains the executable or DLL specified by the callingModuleHandle parameter. You must call LoadPanelEx with a valid calling module handle to load an embedded .uir file from a DLL if you enable the Embed project .UIRs option in the Target SettingsTarget Settings dialog box. |
| panelResourceID | int | Defined constant that you assigned to the panel in the User Interface Editor. The panelResourceID is found in the .uir header file and you use it only to load the panel into memory. You use the panel handle this function returns to refer to the panel in subsequent function calls. When you load a panel from a text user interface (.tui) file, the panelResourceID parameter must be the header number of the .tui file section that defines the panel. For example, if the section header for the panel is [Panel003], pass 3 as the panelResourceID. This function loads all of the controls in the .tui file whose section headers take the form [PanelNNN_ControlYYY], where NNN is the panelResourceID and YYY is 001 or greater. The control numbers must be consecutive and start at 001. To specify the control in calls to other User Interface Library functions, pass YYY + 1 as the controlID. For example, if the section header for the control is [Panel003_Control001], pass 2 as the controlID parameter. 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 panel and control 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 LoadPanelEx is compiled. Use the default parameter, __CVIUserHInst, to specify the handle of the module that contains the call to LoadPanelEx. A value of 0 indicates your executable. If you pass 0, the function behaves identically to LoadPanel. |
Return Value
| Name | Type | Description |
| panelHandle | int | Value you can use in subsequent function calls to specify this panel. Negative values indicate that an error occurred. Zero is not a valid panel handle. |
Additional Information
Library: User Interface Library
Include file: userint.h
LabWindows/CVI compatibility: LabWindows/CVI 4.0 and later
Examples
Refer to the following examples that use the LoadPanelEx function:
- dll\gui\guidll.cws
Open example - utility\threading\ThreadPool\MultiPanel\MultiPanel.cws
Open example