Adding An Application to NX

sample_app.c can be used as a template for adding an application you have developed using the Open C API to NX. The steps in adding your application are outlined below.

In the example below, it is assumed that the directory /user_directory has been added to the file $UGII_BASE_DIR/ugii/menus/custom_dirs.dat file. This file contains user defined directories that NX should search for applications to add to NX. If you are an NX Alliance partner, your release procedures should add the directory where your product is installed to the customers custom_dirs.dat file. This will allow your product to coexist with other products that the user may have purchased or developed themselves. All directories added to the custom_dirs.dat file specify an identically structured set of directories. See the Open C MenuScript User Guide for a detailed description and the search algorithms used to traverse them during your session.

Beginning in NX Version 12.0 a User Defined Object capability allows you to define your own object classes and provide methods for rendering, selecting them, etc. Please see the uf_udo.h chapter of the Open C API Programmer's Guide for further information.

Copy The Template To Define Your Application

Copy the sample_app.c template from UGII_BASE_DIR/sample_app.c and rename it for your application. Replace all occurrences of "sample" in these files with your application name and make the changes corresponding to those in each of the steps below. In each step containing code fragments from the sample template, the specific changes to be replaced with those for your application are shown in bold.

Fill In The Application Registration Template

The ufsta routine in the sample_app.c template initializes Open C API, fills in the UF_MB_application_t application data template with the characteristics of the application and registers the application with NX. Note that the name of the application button must match the name assigned to the application button.

extern void ufsta( char *param, int *retcod, int param_len )
{    
    UF_MB_application_t appData;    
    char name[] = "SAMPLE_APP";    
    int status;    

    /* Initialize Open C API */
    UF_initialize(); 
  
    status = UF_MB_add_actions( actionTable );    
    print_error( "UF_MB_add_actions", status );           
 
    /* Initialize application data */    
    appData.name       = name;    
    appData.id         = 0;    
    appData.init_proc  = SAMPLE_APP__init;    
    appData.exit_proc  = SAMPLE_APP__exit;    
    appData.enter_proc = SAMPLE_APP__enter;            

    /* Initialize application support flags */    
    appData.drawings_supported          = TRUE;    
    appData.design_in_context_supported = TRUE;            

    /* Register the application with NX */    
    status = UF_MB_register_application( &appData );    
    print_error( "UF_MB_register_application", status );    
    app_id = appData.id;

Create The Action Registration Table

Replace the actions in the action registration table at the beginning of the sample application template with the actions for your application. The first field in each entry is the action name that you specify for a button in your application's menu file. The second field is the callback routine to be executed when the button is activated. The third field is a pointer to an application data structure containing data required by the callback, or NULL if no data is required by the function. The variable length array of actions must be terminated by a null record as shown in the template.

static UF_MB_cb_status_t SAMPLE_APP__action1(    
    UF_MB_widget_t                     widget,    
    UF_MB_data_t                  client_data,    
    UF_MB_activated_button_p_t call_button );

static UF_MB_cb_status_t SAMPLE_APP__action2(    
    UF_MB_widget_t                     widget,    
    UF_MB_data_t                  client_data,    
    UF_MB_activated_button_p_t call_button );

static UF_MB_cb_status_t SAMPLE_APP__action3(    
    UF_MB_widget_t                     widget,    
    UF_MB_data_t                  client_data,   
    UF_MB_activated_button_p_t call_button );

static UF_MB_cb_status_t SAMPLE_APP__action4(    
    UF_MB_widget_t                     widget,    
    UF_MB_data_t                  client_data,    
    UF_MB_activated_button_p_t call_button );

static int app_id = 0; static UF_MB_action_t actionTable[] = {  
    { "SAMPLE_APP__action1",  SAMPLE_APP__action1, NULL},  
    { "SAMPLE_APP__action2",  SAMPLE_APP__action2, NULL},
    { "SAMPLE_APP__action3",  SAMPLE_APP__action3, &app_id},
    { "SAMPLE_APP__action4",  SAMPLE_APP__action4, NULL},  
    { NULL, NULL, NULL}
};

As shown in the ANSI C callback prototypes above, the callbacks for each of your actions receive three arguments:

UF_MB_widget_t w- This is the Motif widget ID of the button that triggered the callback. Normally, you should not need to use this argument.
UF_MB_data_t client_data - This is a pointer to your application-specific data registered along with the callback in each UF_MB_action_t action table entry.
UF_MB_activated_button_p_t call_button - This is a pointer to a data structure, defined in uf_mb.h, that provides information about the button that triggered the callback including the button id, button type, button name, button ancestors, the menubar to which the button is attached, and the application id of the application to which the button belongs. The return value from the callback is required and should normally be UF_MB_CB_CONTINUE. A more complete synopsis of a NX MenuScript callback, including details of the activated button data structure and the use of alternative return codes is provided in " Define Application Button " below

The callbacks in the sample_app.c template provide examples of the usage of the callback arguments and return values. SAMPLE_APP__action4 illustrates the contents of the call_button argument by formatting and printing its contents to the NX Information window.

Define Initialization, Enter, and Exit Methods

Fill in the init, enter, and exit routines in the template with code for your application.

The init routine can be used to perform any initialization for your application that needs to be done each time your application is activated. If you do not need to do anything in the init routine you can delete it from the template and use NULL in its place when filling out the application registration data.

static void SAMPLE_APP__init( void )
{    
    printf( "Initializing application\n" );    
    /* Place code to initialize application here */
}

The enter routine is required. Most applications display a default dialog or Tool Palette. The enter routine should be used to create and manage your application's default tool palette

static void SAMPLE_APP__enter( void)
{    
    printf( "Entering application\n" );    
    /* Place code here to build your application's default tool palette.*/
}

The exit routine is required and is called when another application is chosen. The exit routine should be used to close any of your application dialogs that are currently open and perform any required "housekeeping" on your application's data structures. Note that you do not have to do anything about any buttons your application has added to the NX menubar or view popup menu. These buttons are automatically "hidden" (i.e. unmanaged) for you until the next time the application is entered at which time they are automatically "shown" (i.e. managed) again.

static void SAMPLE_APP__exit( void)
{    
   printf( "Exiting application\n" );
   /* Place code to cleanup for application and exit here */
}

Define Application Button

In order to have your application appear on the NX Application menu when you start NX, you need to define an Application Button that specifies your application's shared library and menu file. You can copy the sample application button menu file, sample_app_button.men, from UGII_BASE_DIR/ugsamples and modify it for your application by replacing the library name and menu file name shown in bold. Once you have created your application button menu file, place it in /user_directory/startup, so that your button gets added to the Application menu at NX startup.

VERSION 120
EDIT UG_GATEWAY_MAIN_MENUBAR
MENU UG_APPLICATION
! ***NOTE button name must match the name you registered for your
!  application in the UF_MB_register_application call
   APPLICATION_BUTTON SAMPLE_APP
   LABEL Sample Application...
   LIBRARIES sample_app.sl
   MENU_FILES sample_app.men
END_OF_MENU

The specification of application button location in the template causes it to be appended to the bottom of the Application menu. You can optionally specify the location of your application button more explicitly using additional menu statements documented in the NX MenuScript User's Guide. For example, to add your application button after the Drafting button on the Application menu, simply replace the statements MENU UG_APPLICATION and END_OF_MENU in the above example with AFTER UG_DRAFTING and END_OF_AFTER, respectively.

If you are performing extensive customization of the standard NX menus, and are, therefore, running with a copy of ug_main.men (pointed to by the UGII_MAIN_MENU_FILE environment variable), you can simply skip the use of the startup menu file, and instead add your application button definition directly into the desired location in your NX main menu file.

Define Application Menu File

In addition to the startup menu file you created in the previous step to add your application to the menubar, you need an application-specific menu file that defines all of the menu items for your application. You need to define a menu button for each action that you defined in the action registration table in your copy of sample_app.c. The definition of each menu item specifies the button name, its label, and the action to be performed. You can copy the sample application menu file, sample_app.men, from UGII_BASE_DIR/ugsamples, and replace the sample menu items with your own. Make sure that the name of your menu file matches the name on the MENU_FILES statement for your application button definition created in the previous step. Once you have created your application menu file, place it in /user_directory/application, so that loading of the menu file is deferred until you choose your application from the Application menu.

VERSION 120
EDIT UG_GATEWAY_MAIN_MENUBAR
TOP_MENU
CASCADE_BUTTON SAMPLE_APP_MENU
LABEL Sample
END_OF_TOP_MENU
MENU SAMPLE_APP_MENU
BUTTON SAMPLE_APP_BUTTON1
LABEL Print Button ID
ACTIONS SAMPLE_APP__action1
BUTTON SAMPLE_APP_BUTTON2
LABEL Test Callback Returns
ACTIONS SAMPLE_APP__action2
BUTTON SAMPLE_APP_BUTTON3
LABEL Print Application ID
ACTIONS SAMPLE_APP__action3
END_OF_MENU

The sample menu file creates a single menu, whose label is "Sample", that is added to the end of the main menubar. The Sample menu contains four action buttons. Each action button when activated, executes the callback that was registered for the action named on the ACTIONS statement. For your application, you are not restricted to a creating a single menu. You can create one or more menus, and add menu items to existing NX menus. For example you might wish to a add one or more buttons to the NX Preferences menu that display dialogs that allow you to set preferences that are specific to your application. See the Open C MenuScript User Guide for complete information on adding menus, menu items, etc.

In addition to adding buttons you can temporarily remove menus or menu items that are not useful while in your application. For example, adding the statement, HIDE UG_LAYOUT, to your menu file causes the NX Layout menu to disappear from the menubar upon entry to your application. When you change to another application, the Layout menu is automatically restored to the menubar.

Build Shared Library
Compile and link your application's shared library as you would any other Internal Open C API Shared Library. The shared library should include the object file containing your ufsta entry point and init, enter, and exit methods, and any additional objects you created containing the callbacks that implement the dialogs and functions provided by your application. See the Open C API Manual for any assistance you need in building your shared library.

After you have successfully created your shared library, place it in the /user_directory/application directory. Make sure the name you give the shared library matches the name you specified on the LIBRARIES statement of your application button definition. Note that the default platform extension is required on the shared library file, but that specifying this extension on the LIBRARIES statement is optionally. The default extensions for the currently supported NX platforms are:

.    Linux - .so

.    Windows - .dll

.    MacOS - .dylib

Application Check List

Before starting your application, please use the following checklist to verify that your files are correctly named and correctly placed.

Check that you have added /my_directory to the $UGII_BASE_DIR/ugii/menus/custom_dirs.dat file. This is the directory that will be searched for a startup, application and udo directory for customizations.
Check that your application button menu file is in /my_directory/startup and that the APPLICATION_BUTTON name in this file matches the name registered for the application on the call to UF_MB_register_application in your application's ufsta entry.
Check that the application menu file is in /my_directory/application and that the file name matches the name specified on the MENU_FILES statement on the APPLICATION_BUTTON definition in the application button menu file in the /my_directory/startup directory.
Check that your application shared library is in the /my_directory/application directory and has the correct extension for the platform you are working on.
Check that the shared library name matches the name specified on the LIBRARIES statement on the APPLICATION_BUTTON definition in the application button menu file in the /my_directory/startup directory.

Test Application

Start NX, open a part file, choose your application from the Application menu, and test your application's functions. If you encounter any problems with the placement or actions of menu items, the Menubar Report Tool (see the Open C MenuScript User Guide) may be helpful in diagnosing any problem encountered with access to your new functions. The Open C MenuScript User Guide also provides more complete information on environment variable settings, directories used for NX MenuScript, menu file options and syntax, alternative customization strategies, and diagnosing problems you may encounter.