hiHelp

hiHelp( 
s_objType
S_objName 
[ g_objDetail ]
[ g_moreDetail ]
)
=> t / nil 

Description

Constructs a help symbol from its arguments and invokes the Doc Assistant API to display the help document associated with the help symbol. If the hiHelpAction property is set, hiHelp executes the callback associated with the property, instead of calling the Doc Assistant API. hiHelp is the main service routine for the online help system.

Clicking on a help button in a Virtuoso application invokes a call to hiHelp(). You can also execute hiHelp() from the CIW, as a callback from a form selection menu, or as a call from any SKILL procedure.

Arguments

s_objType	Symbol that identifies the category of the help request. s_objType is one of the following: ‘form, ‘menu, ‘command, ‘window, ‘dbox, ‘helpError.
S_objName | g_objDetail | g_moreDetail	The meanings of these arguments depend upon the value of objType as defined below:

objType	objName	objDetail	moreDetail
‘form	form name	nil	Returns nil if the Help button is clicked. Displays symbol name of the field if the Help or F1 key is pressed when the cursor is over a field. ‘hiFormNoField if the Help or F1 key is pressed when the cursor is not over a field.
‘menu	menu name	nil	NA
‘command	command name	command argument	NA
‘window	help string set on the window or the application name set on the window	window ID	Displays the current command name.
‘dbox	dialog box name	NA	Returns nil if the Help button is clicked. Displays the symbol name of the field if the Help or F1 key is pressed when the cursor is over a field. Returns ‘hiFormNoField if the Help or F1 key is pressed when the cursor is not over a field
‘helpError	error name	NA	NA

Values Returned

t	The function is successful.
nil	There was an error.

Examples

In the following menu, myMenu:

the HELP menu item is programmed with the following callback:

hiHelp( ’menu "myMenu")

When a user selects HELP, the request generates the help symbol myMenu. If the application ID is exampleApp, then the Doc Assistant API looks for the help symbol myMenu in exampleApp.tgf and displays the document associated with it.

Additional Information

At first, hiHelp() checks the hiHelpAsstTool and hiHelpAsstTag properties of objName. properties. If valid values are found for these properties, hiHelp() uses these values to reference a .tgf file and displays the help document in Task Assistant.

If these properties are not set or are set to invalid values, hiHelp() proceeds as explained below:

• Uses the objName and, in some cases, the objDetail to identify the help symbol and appID that are used to reference a .tgf file.
• Checks the objName for the hiHelpSymName property. If the property is set, hiHelp() uses its value as the help symbol. Applications can set this property on the symbol that is passed as the objName. If it is not set, hiHelp() constructs the help symbol. This feature is useful for those forms and windows that are defined dynamically and where the name of the form or window is not known until run time.
• Checks the objName for the hiHelpAppName property. Applications can control the name of their own application-specific .tgf file by setting this property on the object that is passed as the objName. If this property is set and its value is not nil, hiHelp uses its value as the appID.
  If hiHelpAppName is not set, hiHelp() gets the appID by calling hiGetAppType() on the current window, which returns the application name of the current window.
  When multiple applications share forms and dialog boxes or when applications are encapsulated, you cannot rely on hiGetAppType() to return the correct application name. Therefore, you should set hiHelpAppName for all forms and dialog boxes. If one application sets this property, all the other applications that share the form or dialog box should also set this property or assign it to nil before displaying the form or dialog box.
• Converts the appID to lowercase, removes leading and trailing spaces, and changes any spaces within it to underscores.
• Determines the name of the .tgf file by appending the .tgf suffix to the appID.

Related Topics

Online Help Functions

Return to top