Change State Callback


 
When creating a custom dialog that has multiple items that can launch either an Open C dialog or a UIStyler dialog then it is necessary to take preventative steps to ensure that NX does not get into an unpredictable state. This can happen if the user has already launched an Open C dialog or UIStyler dialog from the custom dialog and then decides they want to launch another Open C dialog or UIStyler dialog from the custom dialog. As mentioned in the lock/unlock section there are two steps that can be taken to prevent any unwanted behavior. These include:
 
This section discusses the first solution. The other solution can be found in the Cancel vs. Dismiss section.
 
The state change callback is called by NX when the main menu bar is locked or unlocked due to a user operation. The purpose of the callback registered with this function is to handle the greying and ungreying of the appropriate items on the custom dialog which call either an Open C API dialog or a UIStyler dialog call. Besides greying out individual items you may wish to just unmanage the custom dialog while a Presentation API dialog is up.
 
To register a change state function you call UF_UI_register_change_state_fn passing in as one of its parameters the function that should be called when NX goes into either a lock or unlock state. It is important that once you register a change state function that you unregister the same function when your custom dialog is cancelled. To do this you pass in a NULL for the function name. An example of how to register and unregister a change state function is shown in the reference page on UF_UI_register_change_state_fn.
 
It is important to note that a change state callback is not called every time the user goes into a new dialog. Only going into or out of a particular dialog causes NX to go into or out of a lock or unlock state. It is not very easy to determine what is and isn't a lock state in a regular NX session. It is easier to see this behavior with the use of UF_UI_lock_ug_access and UF_UI_unlock_ug_access.
 
Lets discuss an example to illustrate this behavior. Lets say that you are currently running a regular NX session with Modeling's main Feature Creation dialog currently displayed. Attached to the menubar is your own custom item that launches a custom dialog. The user launches this item and the custom dialog appears. In this custom dialog are buttons that, when selected, launch Open C API dialogs. The user selects one of these buttons. At this point the first thing the callback performs is a call to UF_UI_lock_ug_access, locking out various functions in NX's main menubar along with greying out Modeling's Feature Creation dialog. The NX state is going from an "unlock" state to a "lock" state. This means that the registered change state function is called and the instructions within this function are executed.
 
Reviewing the current state of NX - the Modeling dialog is greyed out; a custom dialog is visible, but any items that launch Presentation APIs are greyed out; an Open C API dialog is currently up and available; and many of the items in NX's main menubar are greyed out. Now lets say that the user decides to select one of the available items in NX's main menubar - Layer Settings. This action launches the Layer Settings dialog, temporarily changing the Open C API dialog. This does NOT mean that NX has gone into a different state. NX still is in a lock state. To verify this, notice that even more items in NX's main menubar are no longer available. In fact, it is not possible to launch another dialog from the menubar at this point in time.
 
Now dismiss the Layer Settings dialog with the Cancel button and review the menubar states. Once again you are able to select special function dialogs from NX's main menubar, but many of the items in the main menubar are still unavailable. This is because NX still remains in a "lock" state. The state does not change until we exit the Open C dialog and call UF_UI_unlock_ug_access. Lets do this. Dismiss the Open C dialog by selecting the Cancel button. This cleanly dismisses the Open C dialog, and the call to UF_UI_unlock_ug_access occurs from within the Open C program. This in turn makes the Modeling Feature Creation dialog available again, and provides access to NX's main menubar. By calling UF_UI_unlock_ug_access the change state function is also called; which, because of code the Open C API developer has written, causes items to become available within the custom dialog that launches Presentation APIs.
 
An Open C dialog or UIStyler dialog launched from a custom dialog may not cancel a currently displayed DA2 that has been launched from NX. Therefore, because of this restriction, when a DA2 has been launched from NX a change state message of UF_UI_LOCK is sent to your change state function. However, this does not mean that NX's main menubar is disabled, only that you want to grey out any items that can invoke an Open C dialog or UIStyler dialog in order to prevent the user of your custom dialog from getting an error message warning them they are not allowed to cancel the NX dialog..
 
The example in Figure 1-3 demonstrates the response handled by the state change protocol. Before the user pressed Block, all push buttons in the custom persistent dialogs were ungreyed. When the user pressed Block, the state change callbacks were called for each persistent dialog, indicating that they must grey the appropriate buttons in the persistent dialogs. When the Block dialog is dismissed, the state change callbacks are called again indicating that the persistent dialogs should ungrey the same buttons.
 
Refer to the description of UF_UI_register_change_state_fn() for an example of creating, registering, and unregistering a state change callback for a persistent dialog. This functionality is also demonstrated in mult_ufsta.c and ufsta.c, which are provided in the ugsamples kit.
 
 

 
Figure  Locking a Custom Application from NX. This is the result from running the ugsamples program mult_ufsta.c