Context Sensitive Help Terminology

The Context Sensitive Help Mechanism

Context Sensitive Help Preparation

 

• Unique naming conventions.
• Creation of help files. These can be HTML help files, with optionally embedded positioning anchors or simple text help files containing properly positioned locator tags.
• Creation of a translation table.
• Translation table syntax rules.

 
<Vendor_Name>_<Function_name>

 
For example, a vendor application with a DA1 could use the following (assume the vendor name is "vnd"):

 
vnd_import
vnd_export
vnd_plot
vnd_fileUtilites
vnd_objectDisplay . .

 
For help based on text or HTML files the mappings consist of individual document ids. For HTML mappings you can optionally include anchor locations.

HTML Based Help


 
Context sensitive help supports the use of HTML help files. All you need to do is create the HTML files containing your help text, and then add entries to the translation table that maps them for NX.
 
When you request HTML based context sensitive help from NX, the system checks the mapping specified for the application context in the translation table, and then displays the help using the web browser startup script specified by the UGII_CSHELP_BROWSER environment variable.
 
These are the details on the translation table. These are the details on inserting HTML document tags in the translation table.
 

Text File Based Help


 
Context sensitive help supports the use of help files composed of plain text. As with HTML help files, all you need to do is create your help text in plain text files, and then add entries to the translation table that maps them to NX.
 
When you request text based context sensitive help from NX, the system checks the mapping specified for the application context in the translation table, and then displays the text in the Information window.
 
These are the details on the translation table. These are the details on inserting text document tags in the translation table.
 

Creating The Translation Table


 
The translation table contains a mapping from the application context to the actual document and page that contains the help information. The translation table also contains information about the type of display program to call in order to display the help file.
 
The translation table itself is a plain ascii text file that contains some header information along with ordered pairs of application contexts and document tags.
 

Translation Table Syntax Rules


 
The syntax for the translation table is as follows.

 
<app_context> = <display_method> <document_tag>

 
Where:
 
<app_context> is the context used with UF_HELP_push_context.
 
<display_method> is the display method string. You can choose from one of three methods:

 
HTML for HTML format
text for plain text format


 
<document_tag> is information necessary for the help display method application to find the actual document to display.

 
For HTML this is the URL for the help file, and an optional anchor location.
For text this is the full pathname for the plain text help file.


 
The following rules are used to parse the translation table.

 
1. Leading and trailing blanks are ignored.
2. If the first nonblank character is a # sign, the line is ignored.
3. Blanks before or after the "=" sign separator are ignored.
4. Multiple blanks for the document tag are compressed to a single blank.
5. Spaces with the braces for an environment variable are ignored.
6. The <app context> and <document_tag> fields are case sensitive.
7. The <display_method> field is case insensitive.
8. For the HTML display method, a pound sign with trailing text (e.g., #info1) appended at the end of a document tag specifies the name of a destination anchor location.

 
An example of entries in a translation table using all three display methods is shown below:

 
#
# Vendor Apps Translation Table
#
vnd_ugphoto=HTML http://www.vendor.com/helpfiles/ug_photo.html#info1 vnd_displaypref=HTML http://www.vendor.com/helpfiles/displayprefs/disp.html vnd_viewopt=HTML file:/helpfiles/viewoptions/viewopt.html#viewopt1
vnd_fileopen=text /proj/inter45/vnd_fopen.txt
vnd_partpolicy=text ${VND_HELP_LOCATION}/vnd_policy.txt


 
The entries on the left side of the translation table contain both the application context for NX and the display method. The right side specifies the document tag.
 
For the HTML display method the document tag consists of the URL and any optional location anchors (e.g., #info1). For the text display method the document tag consists of the full pathname for the help text file. For further details on document tags for the two display methods, see HTML Document Tags and Text Document Tags .
 
The parser for the translation table uses the space between the map file name and the locator name as the separator. The directory name must not contain a space for proper parsing.
 
As shown above, you may use application contexts that differ from the corresponding HTML filenames, i.e. the application contexts on the left hand side do not have to be the same as the locators on the right hand side. We recommend, however, that for simplicity you make them the same, as in the case of vnd_plot above.

HTML Document Tags


 
The HTML display method specifies HTML document tags that consist of the full URL (Uniform Resource Locator), and which begin with "http://" or "file:/". For example:

 
vnd_layer=HTML http://www.vendr.com/help/vnd_layer.html

 
In this example, vnd_layer is the application context, HTML is the display method and http://www.vendor.com/help/vmd_layer.html is the document tag.
 
You can add a specific anchor location to the HTML document tag by including a pound sign (#) at the end, followed by the name of the desired anchor. (The name will correspond with the NAME attribute for the anchor tag in the HTML file.) For example:
 
vnd_layer=HTML http://www.vendr.com/help/vnd_layer.html#info1
 
To create a named anchor in an HTML document, use the NAME attribute of the anchor description (<A NAME="info1">). Place this anchor in the HTML document at the location you want to be the top of the page.
 

Text Document Tags


 
The text display method contains the full pathname for the ASCII help file. No positioning information is needed, because the whole file is always displayed in the Information window. For example:

 
vnd_layer=text /directory/help/vnd_layer.txt

 
In this example, vnd_layer is the application context, text is the display method and /direcotry/help/vnd_layer.txt is the document tag.
 

Environment Variables


 
There are three environment variables that specify the directory paths to the startup script for customer help and translation tables for NX documentation.
 
UGII_CSHELP - Points to the startup script for customer site help. The default setting is as follows.

 
$UGII_CSHELP=${UGII_BASE_DIR}/ugdoc/cshelp.ksh

 
UGII_CSHELP_MAPS - Points to the directory containing the translation table (i.e. "*.tbl") files. The default setting is as follows.

 
$UGII_CSHELP_MAPS=${UGII_BASE_DIR}/ugii/docmaps

 
$UGII_CSHELP_DOCS=${UGII_BASE_DIR}/ugdoc/pl_files

 
UGII_CSHELP_BROWSER - Sets the default web browser for the HTML display method (HTML file format). The default setting is as follows.

 
$UGII_CSHELP_BROWSER=${UGII_BASE_DIR}/ughelp/cshelp_html.ksh
 

Programming Context Sensitive Help


 
For context sensitive help, the NX dialogs are broken down into two categories, one for DA1 dialogs, and one for all other dialogs.
 

Load The Translation Table


 
The translation table is used to isolate the application code from changes, to help locations or help mechanisms by providing one level of indirection between the application context and the actual data needed to invoke the help file.
 
The translation table needs to be loaded by the application prior to using the application contexts. The translation table is loaded by calling:

 


 
UF_HELP_load_map_file( char *map_file_name);

 
The translation files can be specified either with a full path name, or by just using the file name. If the file name is used, the program first looks for the translation table in the working directory and then in a directory specified by the environment variable, UGII_HELP_DIR.
 
Once a translation table has been loaded, subsequent calls to load the same translation table are ignored. Translation tables can be unloaded by calling UF_HELP_unload_map_file, or can be reloaded during debugging of the translation table by calling the function UF_HELP_reload_map_file.
 

Add Application Contexts


 
The help mechanism uses a stack to keep track of the application contexts, so that immediate help can be offered on the current context. The 3rd party developer places a procedure call before the display of a dialog and after the operation of the function in order to add and remove application contexts from the context sensitive help system.
 

Add DA1 Dialog Contexts


 
For a DA1 dialog the programmer calls UF_HELP_push_primary_context to place an application context on the help stack. Consider the following example:

 


 


void fcn_DA1() 
{ 
   UF_HELP_push_primary_context("FCN1_MAIN"); 
   while (!done) 
   { 
      switch( response ) 
      {
         case MATERIAL_ITEM: 
            do_materials(...); 
            break; 
         case TEXTURE_ITEM: 
            do_textures(...); 
            break; 
         case ...; 
      }
   }
}


 
In the example above a call has been made to push a primary (DA1) context onto the stack somewhere near the top of the function. This is the only change required in this function.
 

Add Other Dialog Contexts


 
When adding application contexts to other dialogs you need to use the calls UF_HELP_push_context and UF_HELP_pop_context. The push call needs to be placed before the call to mtDialogExtended, and the pop call needs to occur just before the function exits. There are two methods that could be used to implement adding application contexts. For example:

 


 


void do_materials( ...) 
{ 
   UF_HELP_push_context( "FCN1_MATERIALS"); 
   response=mtDialogExtended(...);
   switch (response) 
   { 
      case ...; 
         break; 
      case BACK: 
         UF_HELP_pop_context(); 
         return; 
         break; 
   } 
   ... 
   UF_HELP_pop_context();

}


 
In the example above the DA1 dialog in section "Add DA1 Dialog Contexts" invoked a second dialog in the function "do_materials". Before the dialog in do_materials is started, the call to UF_HELP_push_context has been added. This adds the context sensitive help context for this dialog to the stack.
 
The UF_HELP_pop_context call needs to be placed such that it is always invoked when the function which controls the dialog returns. In the example function above, two calls to UF_HELP_pop_context have been inserted. One call before the forced return in the "BACK" case, and one just before the normal end of the function. In a "normal" case, for functions with a single point of entry and exit, you would place UF_HELP_push_context right at the start of the function and UF_HELP_pop_context just before the end of the function.
 
Another method of adding help for a DA2 dialog is shown below.

 


 


void fcn_DA1() 
{ 
   UF_HELP_push_primary_context("FCN1_MAIN"); 
   while (!done) 
   { 
      response = mtDialogExtended(...); 
      switch( response ) 
      {
         case MATERIAL_ITEM: 
            do_materials(...); 
            break; 
         case TEXTURE_ITEM: 
            UF_HELP_push_context("FCN1_TEXTURES"); 
            do_textures(...); 
            UF_HELP_pop_context(); 
            break; 
         case ...; 
      } 
   } 
}


 
In the example above the push and pop of a context was placed directly around the call to the function.
 

Error Handling


 
The UF_HELP Open C API routines all return zero (0) for success, and a error return code (non zero) for failure. It is up to the user to display any error messages to the user in the event of a nonzero return code.
 
A trace facility is available by calling UF_HELP_set_context_debug(). Activating the trace facility prints status and error messages to standard out and can be useful in tracking down problems with context sensitive help.
 

How To Display Help


 
Two routines are provided to assist you in displaying the context sensitive help information. If this is an internal Open C API program that can take advantage of the NX menu bar, you can display context sensitive help via the menu bar "HELP->On Context" menu item. If that function is not available then you need to implement your own function to activate context sensitive help. The three display functions are:

 

• UF_HELP_display_current_context(void) display current app context
• UF_HELP_display_context( char *context); display specified context

 
UF_HELP_display_current_context() is used to display the current application context from the context stack. This is the normal routine used to implement context sensitive help for applications using the UF_HELP_push_context and UF_HELP_pop_context routines.
 
UF_HELP_display_context() is used to display a particular application context. This routine does not use or change any of the data in the application context stack. The context parameter is translated using the loaded translation table in order to find the document to display for help.