%U_HTMLHELP

Invoke HTML Help

WTSupported in traditional Synergy 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):

D_HH_ALINK_LOOKUP

Look up topics for specified Alink names.

D_HH_CLOSE_ALL

Close all Help windows associated with application.

D_HH_DISPLAY_INDEX

Display the Index tab.

D_HH_DISPLAY_SEARCH

Display the Search tab.

D_HH_DISPLAY_TEXT_POPUP

Display text in a pop‑up Help window.

D_HH_DISPLAY_TOC

Display the Contents tab.

D_HH_DISPLAY_TOPIC

Open a Help topic.

D_HH_GET_WIN_HANDLE

Return the handle for the window created for a specified window type.

D_HH_HELP_CONTEXT

Display the Help topic for a given context ID.

D_HH_KEYWORD_LOOKUP

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.

D_HH_ALINK_LOOKUP

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)

D_HH_KEYWORD_FAIL_INDEX

Display the Index tab and populate its field with the keywords.

D_HH_KEYWORD_FAIL_MSG, text[, title]

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)

D_HH_KEYWORD_FAIL_PATH, path

Display a topic, where path is the path and filename for a topic in the HTML Help file. (a)

Discussion

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 100001779 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")

D_HH_CLOSE_ALL

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.

D_HH_DISPLAY_INDEX

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")

D_HH_DISPLAY_SEARCH

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)

D_HH_DISPLAY_TEXT_POPUP

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 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.

Examples

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)

D_HH_DISPLAY_TOC

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)

Discussion

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")

D_HH_DISPLAY_TOPIC

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)

Discussion

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)

D_HH_GET_WIN_HANDLE

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)

D_HH_HELP_CONTEXT

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")

D_HH_KEYWORD_LOOKUP

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)

D_HH_KEYWORD_FAIL_INDEX

Display the Index tab and populate its field with the keywords.

D_HH_KEYWORD_FAIL_MSG, text[, title]

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)

D_HH_KEYWORD_FAIL_PATH, path

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)