Open C API - MenuScript Functions
 
This section provides an overview of the MenuScript functions of the Open C API along with several abbreviated examples. Additional abbreviated examples are provided in the subsequent sections. However, because detailed examples of locating and modifying menu buttons are provided in the MenuScript User Guide, the same level of detail is not repeated here. The only difference in using the MenuScript API is that actions specified via the ACTIONS menu file statement represent C callbacks registered via UF_MB_add_actions, rather than the names of existing GRIP or Open C API programs, or User Tool Definition (utd) files. Since, from a practical standpoint, the development of a complete application generally includes extensive development of C callbacks.
 
The primary capabilities of the Open C MenuScript functions are the ability to register callbacks, written in C, that open dialogs or perform functions that you have developed using the Open C API and the ability to register a complete application to add to the NX menu bar. UF_MB_add_actions allows you to bind each callback and an associated callback data pointer to an action name defined as a character string. You can then specify an action name on the ACTIONS menu file statement. When a menu file is being read by MenuScript, each time an action is encountered, the action name is located in the action registration table, and the corresponding callback is attached to the menu item.
 

Creating and Adding Actions:
 
You can use MenuScript to add your own functions to extend the capabilities of the Gateway application (i.e. your menu items are present throughout the entire NX session), or to extend the capabilities of a specific application such as Modeling, Drafting, or Manufacturing. In the latter case, your menus items are present only while you are in that application, and are automatically added and removed for you each time you enter and exit the application in the same manner as is done for application-specific standard NX menu items.
 
The registration of your callbacks via UF_MB_add_actions must take place prior to reading the menu file that references these actions. If the functions you are providing extend the capabilities of Gateway and are present on the menu bar throughout the NX session, then this registration should be done in a shared library placed in a directory called "startup". The directory containing this "startup" directory should be placed in the file $UGII_BASE_DIR/ugii/menus/custom_dirs.dat. Shared libraries and menu files placed in these startup directories are automatically loaded during NX startup. For each shared library loaded, the ufsta entry point is executed immediately after loading the shared library. The call to UF_MB_add_actions should be placed in the ufsta routine. Please refer to the Open C MenuScript User Guide for complete information on MenuScript environment variables, directories, and menu files.
 
If the functions you are providing extend the capabilities of an NX application such as Modeling or Drafting, and you want these functions to be available only while you are in a specific application, the shared library should be placed in a directory called "application", and the directory containing the "application" directory placed in the $UGII_BASE_DIR/ugii/menus/custom_dirs.dat file. Your application-specific shared library and application-specific menu file can then be referenced on the application button's LIBRARIES and MENU_FILES statements, respectively, as shown later in a more detailed example. In this case, loading of your shared library and menu file are deferred until you enter the application, and any menu items you add are automatically added and removed from the menu bar each time you enter and exit the application.
 
For example, assume you have used Motif and the Open C API to provide a function that creates a housing from a parametric definition. Your dialog first allows the user to select settings for various parameters and then creates the housing using a number of functions provided by the modeling functions of the Open C API. The code for registering your callback might look like: 
static UF_MB_cb_status_t create_housing_callback(    
    UF_MB_widget_t                     widget,    
    UF_MB_data_t                  client_data,    
    UF_MB_activated_button_p_t call_button );
static UF_MB_action_t actionTable[] = {  
    { "create_housing",create_housing_callback,NULL  },  
    { NULL, NULL, NULL }
};
extern void ufsta( char *param, int *retcod, int param_len )
{        
    int status;    
    UF_initialize();                    
    /*Initialize Open C API */    
    status = UF_MB_add_actions( actionTable );
}

 
The menu file to add this button to the end of the Toolbox menu when you enter modeling would contain:
 
VERSION
EDIT UG_GATEWAY_MAIN_MENUBAR
MENU UG_MODELING
BUTTON CREATE_HOUSING
LABEL Create Housing...
ACTIONS create_housing  
END_OF_MENU  
 
Use of the menu file commands, BEFORE or AFTER, described in the MenuScript User Guide, provide additional alternatives for more precisely controlling the placement of this menu item. Note that for this example a second menu file is required to add your shared library and menu file to the Modeling application button.
 

Adding Pre and Post Actions to NX Functions
 
In addition to creating your own menu items, you can also add actions to existing NX functions. Each standard NX menu items has the keyword "STANDARD" on its ACTIONS statement in the NX menu file. You can add your own pre action to a menu item. For example:
 
BUTTON UG_LAYER_SETTINGS
 
Label Layer Settings...
 
ACTIONS/PRE my_layer_settings
 
The ACTIONS statement has three modifiers: PRE, POST, and
 
REPLACE. An equivalent specification of the above pre action would be:
 
ACTIONS/REPLACE my_layer_settings STANDARD
 
Complete information on the menu file statements is included in the MenuScript User Guide.
 
Using both a pre and post action can provide a means of providing a logical extension of an NX tool palette. For example:   
BEFORE UG_MODELING_TOOLBOX_FREEFRM                         
    BUTTON UG_MODELING_TOOLBOX_FEATURE 
 
                       
   LABEL Feature...                      
    ACTIONS/REPLACE open_my_features STANDARD
close_my_features
END_OF_BEFORE  

 
In this example the "open_my_features" action would display a Motif dialog that would provide an auxiliary palette buttons each of which opens a dialog for creating a proprietary feature you have developed using the Open C API. The standard NX Feature palette would then be displayed. Note that since NX feature palette has no navigation buttons and remains open until replaced by another tool palette or DA1 dialog, execution of the "close_my_features" actions is deferred. The "close_my_features" action is executed when the NX Feature palette is being replaced by another palette or DA1 dialog. The callback for the "close_my_features' action should simply close (i.e. unmanage) your auxiliary feature palette. In this way your feature palette functions as an extension of the NX feature palette.
 
Also note that in this example, the BEFORE statement is used to maintain to position of the Feature palette on the Toolbox menu. Each specification of a button also implies the ability to relocate the button. In this example, if MENU UG_MODELING_TOOLBOX was specified instead of BEFORE UG_MODELING_TOOLBOX_FREEFRM, the specification would have also had the effect of relocating the Feature palette at the bottom of the Toolbox menu.
 
Each of your actions must return a value from the UF_MB_cb_status_t enumerated type defined in uf_mb.h. At this time, the semantics for all of these return values have not been fully defined. A return value of UF_MB_CB_CONTINUE causes execution of the next callback to continue; any of the other values causes processing of the subsequent callbacks to be inhibited. You might use this capability, for example, to provide your own custom dialog for part file selection on File->Open. If a part file was selected and opened using the custom dialog, a return value of UF_MB_CB_OVERRIDE_STANDARD could be used to inhibit display of the NX file selection dialog. Some other option on your custom dialog could result in a return value of UF_MB_CB_CONTINUE, resulting in the subsequent display of the standard NX File Open dialog
 
Multiple pre and/or post actions can also be specified.
 

Adding a Complete Application
 
Using MenuScript a complete application can be added to NX. An application button is defined and added to the Application pulldown menu at NX startup. When the application button is selected after opening or creating a part, the shared library specified by the application button's LIBRARIES statement is located in the application subdirectory of directory specified in the file $UGII_BASE_DIR/ugii/menus/custom_dirs.dat, the library is loaded, and its ufsta entry point is called.
 
The ufsta entry point registers the application's callbacks using UF_MB_add_actions. It then must declare and initialize a UF_MB_application_t data structure that defines the characteristics and methods for the application. A pointer to this structure is then passed to UF_MB_register_application which registers the application and assigns it an internal id which is returned in the application data structure's id field.
 
After returning from the ufsta entry point, the NX Change Application manager automatically loads the menu file specified on the application button's MENU_FILES statement. The buttons defined in the menu file are created and the callbacks for their actions are assigned using the information that was provided on the call to UF_MB_add_actions. These menu items are automatically removed when a different application is entered, and are added again the next time the application is entered. If there are standard NX menus or menu items that are not useful while in your application, they can be removed for the duration of your application by using the menu file HIDE command (see the MenuScript User Guide). Any buttons you hide using your application's menu file are automatically replaced when you choose another application, and are hidden again when you re-enter your application.