Operational Tips and Techniques


 
Lock & Unlock
 
This section discusses the essential protocols which Presentation APIs must follow when using UF_UI_lock_ug_access and UF_UI_unlock_ug_access.
 
All Presentation APIs must use the lock/unlock protocol when launching Open C API dialogs and any UIStyler dialogs from a custom dialog not launched via UF_UI_run_dialog. The lock protocol informs NX that your custom application intends to execute a sequence of one or more interactive Open C API routines. NX services a lock request by inhibiting access to the appropriate menubar items and DA1, until the receipt of an unlock request. NX special functions are still available at all times. Each lock request must eventually be paired with a corresponding unlock request. Even if you do not wish to inhibit your DA1, you must still make the lock request, since this is the only way for NX to know you are about to launch a Presentation API from a custom dialog.
 
When calling multiple Open C dialogs or UIStyler dialogs or some such combination one after the other within the same callback then you do not have to wrapper every call with UF_UI_lock_ug_access and UF_UI_unlock_ug_access. Only the first call to an Open C dialog or UIStyler dialog needs to be preceded with UF_UI_lock_ug_access and the last call must be followed with a call to UF_UI_unlock_ug_access.
 
A UIStyler dialog or an  C dialog may not be launched from a custom application when an NX dialog is displayed. What this means is if an NX DA2 is currently displayed, such as the Layer Settings dialog, and you attempt to invoke either a UIStyler dialog or an Open C dialog then you receive an error when you attempt to lock NX. This implies that is it is very important to always check the return status of UF_UI_lock_ug_access. If this is not done and an attempt is made to launch an Open C API when an error has occurred then unpredictable results occur.
 
When you use custom dialogs to launch your UIStyler or Open C dialog then actions must be taken so that the user of the custom dialog does not get NX into an unpredictable state. This can happen when a user has launched a UIStyler or Open C dialog and is able to launch another Open C dialog from the custom dialog. The lock/unlock protocols are the first step towards preventing unwanted behavior, because the user can not launch an unwanted NX dialog. The next step is to do either of the following actions:
 
Either method is valid and up to the dialog designer. Please refer to the section on Change State Callbacks and Cancel vs. Dismiss for more complete details.
 
Figure 1-2 shows the response that occurs when Custom-->Select (from Figure 1-1) is pressed from the customized menu hierarchy. The corresponding callback performs a lock request, displays the Class Selection Dialog until the user closes it, and then performs an unlock request.
 
 

 
Figure 1-1 Sample Customized Menu Hierarchy
 
 

 
Figure 1-2 Locking NX from Custom Application
 
Refer to the descriptions of UF_UI_lock_ug_access() for an example on how to use the lock/unlock protocol with the Presentation APIs.
 
Lock & Unlock Summary