Invoking Presentation APIs

For invoking Presentation APIs please refer to this section in the uf_ui.h section.
 

Operational Tips and Techniques
 

Run & Exit Dialog
 
UF_UI_run_dialog is used to launch a custom dialog and place it into NX's event loop. To terminate your custom dialog you must use UF_UI_exit_dialog. This will remove your dialog from NX's event loop and unmanage your custom dialog. There are certain rules and protocols that need to be followed when using these two functions, otherwise, NX might end up in an unpredictable state.
 
UF_UI_run_dialog will inhibit access to the appropriate items on NX's main menubar. Visually this is similar behavior to UF_UI_lock_ug_access, however, when UF_UI_run_dialog is invoked NX does not consider itself in a "lock" state. Also, if a DA1 is up when the custom dialog is launched then access to this dialog may not necessarily be inhibited as is always the case with UF_UI_lock_ug_access. (NOTE: DA1s will vary in this behavior; not all DA1s remain available.) In fact if the user selects an item from a DA1 that launches an NX DA2 then this will cause the custom application and any Open C dialogs it has launched to be cancelled.
 
If you would like your custom dialog launched via UF_UI_run_dialog to be in a "lock-->state inhibiting access to any DA1s that happen to be up when the custom dialog is launched then it is advised that you call UF_UI_lock_ug_access just prior to UF_UI_run_dialog and UF_UI_unlock_ug_access just afterwards. This will ensure that your custom dialog is always in a "lock" state.
 
 
NOTE:
You may also launch a custom dialog via XtManageChild and destroy it with XtDestroyWidget. Using this mechanism does not require the use of UF_UI_run_dialog and UF_UI_exit_dialog. It also allows NX's main menubar to remain active until the lock/unlock protocols have been called.
 
You should only call UF_UI_run_dialog once per custom dialog. If it is called more than once then unpredictable behavior will occur.
 
Custom dialogs launched via UF_UI_run_dialog may be used to launch either Open C dialogs or UIStyler dialogs. When launching a Presentation API the lock and unlock protocol do not have to be used, however, you may not call UF_UI_cancel_uf_dialog without using the lock and unlock protocols. Please refer to the section on Lock & Unlock in the uf_ui.h chapter for complete details on these APIs. Open C dialogs launched from within a custom dialog may require the use of the the cancel and dismiss protocols. A complete discussion on how and when to use UF_UI_cancel_uf_dialog and UF_UI_dismiss_dialog_area_2 is covered in the section called Dismiss v.s. Cancel in the uf_ui.h chapter.
 
When the custom dialog is displayed and the user launches a Presentation APIs from the custom dialog there is still some functionality within NX that is available despite the inhibiting of some menu items. The functions that are available are known as "Special Function" dialogs, which are all purpose functions that are available at nearly anytime during an NX session. These are functions that do not affect a part, but perform some global purpose, such as getting information about a part, setting the layer, or zooming in on a part.
 
If the user selects a Special Function dialog when they have a Presentation API dialog displayed then this Special Function dialog will replace the Presentation API dialog. If at this point the user decides to cancel the custom dialog without cancelling first the special function dialog then the user's request to cancel the custom dialog will be ignored, and a warning will be displayed As a custom dialog writer it is recommended to document this behavior for your users.
 
Another scenario that may cause some confusion among the custom dialog user is when the custom dialog is displayed and then the user launches a special function dialog. NOTE: This is different than the above example because the user has not launched a Presentation API from the custom dialog. If the user at this point decides to cancel the custom dialog then both the presentation dialog and the custom dialog will be cancelled. This behavior should also be noted for any users of your custom dialog.
 
Run & Exit Summary           UF_UI_exit dialog.           want to inhibit access to all DA1s and call UF_UI_cancel_uf_dialog then these protocols must be used.           run dialog application is running then unpredictable results may occur.           UF_UI_run_dialog when an NX's special function dialog is displayed then both the custom application dialog and the special
          function dialog will be dismissed.           and UF_UI_exit_dialog.           not immediately after the call to UF_UI_exit_dialog.
 
In the following table shows the behavior for UF_UI_exit_dialog when various types of DA2 are displayed.
 
DA2 Type Currently Displayed  Result from Cancel of Custom Application 
No DA2  Exit is successful and UF_UI_run_dialog returns. 
Open C DA2  Exit is not successful and the user is not allowed to cancel the custom application until the Open C dia log is cancelled.* 
Open C DA2 which is temporarily replaced with a Special Function dialog  The exit is not successful and both dialogs need to be cancelled. 
Special Function dialog only  The exit will be successful, the Special Function dia log will be cancelled by NX, and UF_UI_run_dialog will return. 
* If the lock/unlock protocols are used then the Open C DA2 can be cancelled with a call to UF_UI_cancel_uf_dialog prior to calling UF_UI_exit_dialog. However, if you do not wish to use the lock/unlock protocols it is recommended to inhibit functions that call UF_UI_exit_dialog, while there is a DA2 displayed.