Invoking Presentation APIs
There are various ways to invoke Presentation APIs:
-
You can attach an item to NX's main menubar via MenuScript, which invokes
Presentation APIs when selected.
-
You can launch Presentation APIs from most User Exits, such as USER_STARTUP.
-
You can launch Presentation APIs from either a UIStyler dialog or a Custom
dialog.
-
You can launch an Open C program which uses the Presentation APIs from a User
Tools palette.
-
You can use File-->Execute -->NX Open.
All three types of Presentation APIs may be launched from any of these methods,
however, there are certain rules that must be obeyed, which are discussed
briefly below.
Menubar
As long as the correct MenuScript protocol has been used you may launch any form
of Presentation APIs (Please refer to the MenuScript documentation to determine
these protocols). It should be noted that a UIStyler DA1 can only be launched
from the menubar. This means that you are not allowed to launch a UIStyler DA1
from any other method of invoking dialogs.
UIStyler Dialogs
UIStyler dialogs may invoke another UIStyler dialog or an Open C dialog from a
callback. No lock/unlock protocol is needed.
User Exits
User Exits may launch either a UIStyler dialog or an Open C dialog. It is
recommended that the two most appropriate user exits to use are ufusr or ufsta.
As mentioned above you may not launch a UIStyler DA1 from a User Exit, and we
strongly recommend that you launch UIStyler dialogs from the menubar, since
this provides a seamless integration of your Open C program with NX.
User Tools
An Open C program that uses the Presentation APIs may be launched from a User
Tools palette item. As mentioned before no UIStyler DA1 dialogs may be launched
from here.
Custom Dialogs
Prior to calling either a UIStyler dialog or an Open C dialog you must call
UF_UI_lock_ug_access. After the call to either Presentation APIs you then must
call UF_UI_unlock_ug_access. It is very important that you check the return
status of UF_UI_lock_ug_access. If it is not UI_SET_LOCK then you must not call
the Presentation APIs. This is discussed in greater detail under Lock &
Unlock Protocol.
Any items within the custom dialog that launch another Open C dialog or a
UIStyler dialog must either be disabled via the change state function
(UF_UI_register_change_state_fn) or cancelled via the cancel function
(UF_UI_cancel_uf_dialog). Both of these are discussed in greater detail under
the Change State and Cancel vs. Dismiss sections.
File->Execute
Open C and UIStyler dialogs launched directly from File-->Execute do
not require any special UF wrappers (lock & unlock). Just the required
initialization of User Function is all that is necessary prior to calling one
of the Presentation APIs. However, if you wish to lock out access to NX you may
call the lock & unlock protocols.