|
WSupported on Windows
|
|
|
|
result = %U_HTMLHELP(subfunction[, arg, ...])
or
xcall U_HTMLHELP(subfunction[, arg, ...])
Return value
result
On Windows, a value specific to the subfunction. (For most subfunctions, this is the handle for the outermost Help window.) On Unix and OpenVMS, always returns 0. (^VAL)
Arguments
subfunction
The operation to perform (defined in tools.def):
Look up topics for specified Alink names.
Close all Help windows associated with application.
Display the Index tab.
Display the Search tab.
Display text in a pop-up Help window.
Display the Contents tab.
Open a Help topic.
Return the handle for the window created for a specified window type.
Display the Help topic for a given context ID.
Look up topics for specified keywords.
arg
(optional) One or more arguments if required for the subfunction. (a or n)
Discussion
%U_HTMLHELP wraps much of Microsoft’s HTML Help API to enable you to access HTML Help (.chm files) from a Toolkit application. Each subfunction corresponds to an HTML Help API command. See the Microsoft documentation for the HTML Help API for more information.
result = %U_HTMLHELP(D_HH_ALINK_LOOKUP, help_file, alinks, [window], fail_action)
or
xcall U_HTMLHELP(D_HH_ALINK_LOOKUP, help_file, alinks, [window], fail_action)
Return value
result
On Windows, the handle (D_ADDR) of the outermost Help window. (^VAL)
Arguments
help_file
The path and filename for the HTML Help file. The default extension is .chm. (a)
alinks
One or more associative keywords (Alink names) that will be used to look up topics. You can search for multiple Alink names by passing them in a semicolon-delimited string. (a)
window
(optional) The name of the window type to use to display a looked-up topic or a topic specified for D_HH_KEYWORD_FAIL_PATH. (a)
fail_action
One of the following to specify how a failure to find any of the alinks values should be handled: (n)
Display the Index tab and populate its field with the keywords.
Pop up a message box, where text is the text for the pop-up message and title is an optional title for the message box. (a)
Display a topic, where path is the path and filename for a topic in the HTML Help file. (a)
The D_HH_ALINK_LOOKUP subfunction of %U_HTMLHELP looks up topics for alinks for the specified Help file (help_file), opening the Help file if necessary. Alink names (sometimes called bookmarks) mark locations within topics, so when a looked-up topic is opened, the topic is scrolled down to the location marked by the alinks value.
For help_file, you can use an environment variable to specify the path, part of the path, or the full path and filename. If the specified file does not exist, a catchable runtime error ($ERR_FNF) is generated. You cannot use an xfServer path (e.g., myhelpfile.chm@myserver) to access an HTML Help file on a remote machine. (Because of a Microsoft security feature, you may not be able to access an HTML help file on a remote machine in any case. See Synergex KnowledgeBase article 1779 for information.)
If you don’t pass window, if window is not in the file specified by help_file, or if you pass an empty string for window, the default window type for the Help file is used to display the topic.
For path, pass the path and filename used in the HTML Help file structure. For example, to specify the topic my_topic.html in the /my_folder/my_subfolder directory, pass /my_folder/my_subfolder/my_topic.html (including the first slash) for path. Note that if the topic specified by path cannot be found, Hhctrl.ocx, the ActiveX control for HTML Help, determines the result. This is generally a message such as “The page cannot be displayed.”
Examples
The following example looks up topics associated with the Alink name “orders”. If there are no topics for this, it displays a pop-up message box with the title “Error” and the text “No topic found.”
.define D_HELPFILE, "MYAPPDIR:bin\myhelp.chm" . . . help_handle = %u_htmhelp(D_HH_ALINK_LOOKUP, D_HELPFILE, "orders", mywin, & D_HH_KEYWORD_FAIL_MSG, "No topic found", "Error")
xcall U_HTMLHELP(D_HH_CLOSE_ALL)
Discussion
The D_HH_CLOSE_ALL subfunction of %U_HTMLHELP closes all Help windows associated with the application. If this is called as a function, it always returns zero.
If D_HH_CLOSE_ALL has not been called when the application shuts down, it is automatically invoked, unless the program is in a chain.
result = %U_HTMLHELP(D_HH_DISPLAY_INDEX, help_file[, keyword])
or
xcall U_HTMLHELP(D_HH_DISPLAY_INDEX, help_file[, keyword])
Return value
result
On Windows, the handle (D_ADDR) of the outermost Help window. (^VAL)
Arguments
help_file
The path and filename for the HTML Help file. For information, see the D_HH_ALINK_LOOKUP Discussion. (a)
keyword
(optional) A keyword (index entry) to highlight on the Index tab. (a)
Discussion
The D_HH_DISPLAY_INDEX subfunction of %U_HTMLHELP displays the Index tab for the specified Help file (help_file), opening the Help file if necessary. If you pass a valid keyword, the keyword is highlighted on the Index tab.
Examples
The following example displays the Index tab with the keyword “vendors” highlighted on the tab:
.define D_HELPFILE, "MYAPPDIR:bin\myhelp.chm" . . . help_handle = %u_htmhelp(D_HH_DISPLAY_INDEX, D_HELPFILE, "vendors")
result = %U_HTMLHELP(D_HH_DISPLAY_SEARCH, help_file)
or
xcall U_HTMLHELP(D_HH_DISPLAY_SEARCH, help_file)
Return value
result
On Windows, the handle (D_ADDR) of the outermost Help window. (^VAL)
Arguments
help_file
The path and filename for the HTML Help file. For information, see the D_HH_ALINK_LOOKUP Discussion. (a)
Discussion
The D_HH_DISPLAY_SEARCH subfunction of %U_HTMLHELP displays the Search tab for the specified Help file (help_file), opening the Help file if necessary.
Examples
The following example displays the Search tab:
.define D_HELPFILE, "MYAPPDIR:bin\myhelp.chm" . . . help_handle = %u_htmhelp(D_HH_DISPLAY_SEARCH, D_HELPFILE)
result = %U_HTMLHELP(D_HH_DISPLAY_TEXT_POPUP, text_string|text_id, x, y, & [foreground],[background],[left], [top], [right], [bottom][, font])
or
xcall U_HTMLHELP(D_HH_DISPLAY_TEXT_POPUP, text_string|text_id, x, y, & [foreground], [background], [left], [top], [right], [bottom][, font])
Return value
result
On Windows, the handle (D_ADDR) of the outermost Help window. (^VAL)
Arguments
text_string
The text to be displayed. (a)
text_id
A series of three arguments, id, help_file, path, where
id is the map ID of a text string within help_file. (n)
help_file is the path and filename for an HTML Help file. (For information, see the D_HH_ALINK_LOOKUP Discussion.) (a)
path is the path within the help_file to the text file that contains the text string. (For information, see the D_HH_ALINK_LOOKUP Discussion.) (a)
x
The screen-relative x-axis pixel coordinate for the top-center of the pop-up window. (n)
y
The screen-relative y-axis pixel coordinate for the top-center of the pop-up window. (n)
foreground
(optional) An RGB value for the text color. See GetCellColor for information on the format of this value. (n)
background
(optional) An RGB value for the pop-up window’s background color. See GetCellColor for information on the format of this value. (n)
left
(optional) The width in pixels of the margin between the text and the pop-up window’s left edge. (n)
top
(optional) The width in pixels of the margin between the text and the pop-up window’s top edge. (n)
right
(optional) The width in pixels of the margin between the text and the pop-up window’s right edge. (n)
bottom
(optional) The width in pixels of the margin between the text and the pop-up window’s bottom edge. (n)
font
(optional) A string with the following format:
"[facename], [point_size], [charset][, BOLD ITALIC UNDERLINE]"
where
facename is the name of the type face. (a)
point_size is the font size in points. (n)
charset is the character set. (n)
Discussion
The D_HH_DISPLAY_TEXT_POPUP subfunction of %U_HTMLHELP displays text in a pop-up Help window. The text is taken from one of the following, depending on the data type of the second argument (the argument that follows D_HH_DISPLAY_TEXT_POPUP):
- If you pass text_string (in other words, if the second argument is an alpha value), the text is taken from the specified text string.
- If you pass text_id (in other words, if the second argument is a numeric value), the text is taken from a text file included in the HTML Help file.
If you omit foreground, background, left, top, right, or bottom, or pass -1 for any of these, the system default is used.
If you don’t pass font or one or more of its components, the omitted font characteristics are determined by system defaults. For example, if you omit point_size, the text in the pop-up window will have the default point size for the user’s system.
For font, you can pass one, two, or all of the following: BOLD, ITALIC, and UNDERLINE. Use spaces to separate them. See example below.
The following example displays a pop-up Help window with the text “Text to display” in 14 point bold and underlined Courier:
help_handle = %u_htmhelp(D_HH_DISPLAY_TEXT_POPUP, "Text to display", & 100, 100,,,,,,, "Courier, 14,, BOLD UNDERLINE")
The next example displays a pop-up Help window with text from the text file /info.txt, which is contained in D_HELPFILE. System defaults are used for all optional settings.
.define D_HELPFILE, "MYAPPDIR:bin\myhelp.chm" . . . help_handle = %u_htmhelp(D_HH_DISPLAY_TEXT_POPUP, 61288, D_HELPFILE, & "/info.txt", 100, 100)
result = %U_HTMLHELP(D_HH_DISPLAY_TOC, help_file[, path])
or
xcall U_HTMLHELP(D_HH_DISPLAY_TOC, help_file[, path])
Return value
result
On Windows, the handle (D_ADDR) of the outermost Help window. (^VAL)
Arguments
help_file
The path and filename for the HTML Help file. For information, see the D_HH_ALINK_LOOKUP Discussion. (a)
path
(optional) The path within the HTML Help file to the topic whose Contents entry you want highlighted. For information, see the D_HH_ALINK_LOOKUP Discussion. (a)
The D_HH_DISPLAY_TOC subfunction of %U_HTMLHELP displays the Contents tab for the specified Help file (help_file), opening the Help file if necessary. Passing a valid path may cause D_HH_DISPLAY_TOC to highlight the Contents entry for the topic specified by path and to display the topic. For example, this will occur if D_HH_DISPLAY_TOC opens the Help file, but it may not occur if the Help file is already open in a window that displays the navigation pane (the pane that displays the Contents, Index, and Search tabs).
Examples
The following example displays the Contents tab but does not change highlighting on the tab or the displayed topic because path is omitted.
help_handle = %u_htmhelp(D_HH_DISPLAY_TOC, "MYAPPDIR:bin\myhelp.chm")
result = %U_HTMLHELP(D_HH_DISPLAY_TOPIC, help_file, path[, window])
or
xcall U_HTMLHELP(D_HH_DISPLAY_TOPIC, help_file, path[, window])
Return value
result
On Windows, the handle (D_ADDR) of the outermost Help window. (^VAL)
Arguments
help_file
The path and filename for the HTML Help file you want to open. For information, see the D_HH_ALINK_LOOKUP Discussion. (a)
path
The path within the HTML Help file to the topic you want displayed. For information, see the D_HH_ALINK_LOOKUP Discussion. (a)
window
(optional) The name of the window type to use to display the topic. (a)
The D_HH_DISPLAY_TOPIC subfunction of %U_HTMLHELP opens a specified Help topic (path) in the default window or in a specified window (window).
If you don’t pass window, if window is not in the file specified by help_file, or if you pass an empty string for window, the default window type for the Help file is used to display the topic.
Examples
The following example displays the /entry/orders.htm topic with the mywin window type.
.define D_HELPFILE, "MYAPPDIR:bin\myhelp.chm" . . . help_handle = %u_htmhelp(D_HH_DISPLAY_TOPIC, D_HELPFILE, & "/entry/orders.htm", mywin)
result = %U_HTMLHELP(D_HH_GET_WIN_HANDLE, help_file, window)
or
xcall U_HTMLHELP(D_HH_GET_WIN_HANDLE, help_file, window)
Return value
result
On Windows, the handle (D_ADDR) of the window for the specified window type, or 0 if there is no such window. (^VAL)
Arguments
help_file
The path and filename for the HTML Help file. For information, see the D_HH_ALINK_LOOKUP Discussion. (a)
window
The name of the window type whose handle you want to retrieve. (a)
Discussion
The D_HH_GET_WIN_HANDLE subfunction of %U_HTMLHELP returns (in result) the handle for the window of the type specified in window. If no window has yet been created for the specified window type (i.e., if no topic has been displayed using the specified type), result is returned with a value of 0.
Examples
The following example returns the handle for the Help window of type mywin, or it returns a value of 0 if no Help window of that type has been created.
.define D_HELPFILE, "MYAPPDIR:bin\myhelp.chm" . . . help_handle = %u_htmhelp(D_HH_GET_WIN_HANDLE, D_HELPFILE, mywin)
result = %U_HTMLHELP(D_HH_HELP_CONTEXT, help_file, context_id[, window])
or
xcall U_HTMLHELP(D_HH_HELP_CONTEXT, help_file, context_id[, window])
Return value
result
On Windows, the handle (D_ADDR) of the outermost Help window. (^VAL)
Arguments
help_file
The path and filename for the HTML Help file. For information, see the D_HH_ALINK_LOOKUP Discussion. (a)
context_id
A context ID mapped to a topic in the HTML Help file. (n)
window
(optional) The name of the window type to use to display the topic. (a)
Discussion
The D_HH_HELP_CONTEXT subfunction of %U_HTMLHELP displays the topic specified by context_id, which is a numeric ID that maps to a topic in help_file, opening the Help file if necessary.
If you don’t pass window, if window is not in the file specified by help_file, or if you pass an empty string for window, the default window type for the Help file is used to display the topic.
Examples
The following example displays the Help topic with the context ID of 102 in a mywin type window:
.define D_HELPFILE, "MYAPPDIR:bin\myhelp.chm" . . . help_handle = %u_htmhelp(D_HH_HELP_CONTEXT, D_HELPFILE, 102, "mywin")
result = %U_HTMLHELP(D_HH_KEYWORD_LOOKUP, help_file, keywords, [window], & fail_action)
or
xcall U_HTMLHELP(D_HH_KEYWORD_LOOKUP, help_file, keywords, [window], & fail_action)
Return value
result
On Windows, the handle (D_ADDR) of the outermost Help window. (^VAL)
Arguments
help_file
The path and filename for the HTML Help file. For information, see the D_HH_ALINK_LOOKUP Discussion. (a)
keywords
The keyword(s) whose topic(s) will be looked up. You can search for multiple keywords by passing them in a semicolon-delimited string. (a)
window
(optional) The name of the window type to use to display a looked-up topic or a topic specified for D_HH_KEYWORD_FAIL_PATH. (a)
fail_action
One of the following to specify how a failure to find any of the keywords should be handled: (n)
Display the Index tab and populate its field with the keywords.
Pop up a message box, where text is the text for the pop-up message and title is an optional title for the message box. (a)
Display a topic, where path specifies the path and filename for a topic in the HTML Help file. For information, see the D_HH_ALINK_LOOKUP Discussion. (a)
Discussion
The D_HH_KEYWORD_LOOKUP subfunction of %U_HTMLHELP looks up topics for keywords in the specified Help file (help_file), opening the Help file if necessary.
If you don’t pass window, if window is not in the file specified by help_file, or if you pass an empty string for window, the default window type for the Help file is used to display the topic.
Examples
The following example looks up topics associated with the keyword “accounts.” If there are topics for this, it displays a pop-up message box with the title “Error” and the text “No topic found.”
.define D_HELPFILE, "MYAPPDIR:bin\myhelp.chm" . . . help_handle = %u_htmhelp(D_HH_KEYWORD_LOOKUP, D_HELPFILE, "accounts", & mywin, D_HH_KEYWORD_FAIL_MSG, "No topic found", "Error")
The next example does the same, but instead of displaying a pop-up message box if no topics are found, it displays the Index tab, populating the field on the tab with the keyword “accounts.”
.define D_HELPFILE, "MYAPPDIR:bin\myhelp.chm" . . . help_handle = %u_htmhelp(D_HH_KEYWORD_LOOKUP, D_HELPFILE, "accounts", & mywin, D_HH_KEYWORD_FAIL_INDEX)
