Reusing a Help window opened via hh.exe

Question

I'm opening a .chm Help file from within Lua by executing hh.exe via a shell command; the user clicks one of a number Help buttons within the Lua application and is directed to a topic within the Help file that depends on the context of the Help button used.

local HelpFile = strDir.."\\"..strName.." "..strVersion..".chm"
--strDir ,strName, strVersion all identify the help file to be used
local topicpath = "options" --an example; will differ according to application context
local helpexecutable = "C:\\windows\\hh.exe"
local helpparms = "::/"..string.lower(string.gsub(topicpath..".htm", "")
local bOK, intErrorCode, strErrortext = 
    fhShellExecute(helpexecutable, HelpFile..helpparms)
    -- open the help file at a specified location

This code works fine to open the Help file at the topic I want.

Note fhShellExecute is a programme-host specific API that is equivalent to os.execute

PARAMETERS:

strFileName: string: the full path to the file. Remember that slashes in Lua must be doubled (e.g "C:\MyDocuments\My Program.exe").

strParams: string: parameters. If strFileName is an executable file, strParams holds the parameters to be passed to it. Should be empty, or not supplied, if strFileName is a document file.

strDirectory: string: specifies the default (working) directory for the action. If not supplied, the current working directory is used.

strOperation: string: specifies the action to be performed. The set of available actions depends on the particular file or folder. Generally, the actions available from an object's shortcut menu are available actions.

iShowCmd: integer: Specifies how an application is to be displayed when it is opened. If not supplied, the value defaults to 1. The following values are defined:

0 Hides the window and activates another window

1 Activates and displays a window. If the window is minimized or maximized, Windows restores it toits original size and position. An application should specify this flag when displaying the window forthe first time.

2 Activates the window and displays it as a minimized window.

3 Activates the window and displays it as a maximized window.

4 Displays a window in its most recent size and position. The active window remains active.

5 Activates the window and displays it in its current size and position.

6 Minimizes the specified window and activates the next top-level window in the Z order.

7 Displays the window as a minimized window. The active window remains active.

8 Displays the window in its current state. The active window remains active.

9 Activates and displays the window. If the window is minimized or maximized, Windows restores it toits original size and position. An application should specify this flag when restoring a minimizedwindow.

Because I'm using hh.exe, every time the user clicks a Help button a new instance of Help appears, which is not what I (or the user) wants. It isn't acceptable for opening the Help window to block the operation of the application.

Adapting the approach shown here How to have only one instance of the CHM file opened? (test if the Help file is renameable -- if it isn't, then it's in use) I can prevent a second Help window being opened. However, I can't see any way of instructing the Help window that is open to navigate to the topic for the new context.

I have access to a very limited set of Lua libraries, so I need a solution I can execute via a shell command. My thinking is either:

• To move position within the existing Help window
• To close the existing Help window and open a new one at the correct position

but I can't work out how to do either of these things.

Answer 1

I have not installed a LUA development environment on my machine with Windows10 Version 1903 at this stage. Therefore I describe the answer using the example of PowerShell with some hints for LUA. A conversion should not be a problem.

As I remenber and mentioned earlier KeyHH.exe is a program that augments HTML Help. It can be used in addition to or as a complete replacement for HH.EXE. KeyHH provides all of the functionality of HH.EXE, offers solutions for some known bugs in HTML Help, and provides additional functionality as well.

But, please note, this was really a long time ago (about 12 years) and maybe you need to be warned here for today's Windows operating system. But I was surprised it's working on my machine.

The old website keyworks.net is no longer available. As a retired Microsoft Help MVP I have copied the content some years ago to http://keyworks.help-info.de.

So, nevertheless give it a try. I'd recommend to follow the steps below first and adapt it later for your needs in LUA. As I can see without experience

• Download Keyhh.zip
• Unzip KeyHH.exe to a temp folder e.g. D:/_working
• Cut and paste KeyHH.exe to C:/Windows where hh.exe also resides (with administrator rights)
• Download a sample CHM file from my site to a temp folder e.g. D:/_working. To open this CHM file right-click the saved file, click Properties, and then click Unblock. This is for test case only (see below).

Execute following hh.exe commands using PowerShell:

hh.exe D:/_working/CHM-example.chm
hh.exe D:/_working/CHM-example.chm::/Garden/flowers.htm
hh.exe D:/_working/CHM-example.chm::/Garden/tree.htm
hh.exe -mapid 10010 D:/_working/CHM-example.chm 

You know this is resulting in four help windows:

You can use KeyHH to create a standalone HTML Help window. This window remains open until the user closes it. Once this window is created, you can open new topics in the window without creating a new window, just as you can with WinHelp. You can use this functionality from an HTML Help window, a program, or a WinHelp file.

You create a unique KeyHH window by specifying a dash (-) followed by an identifying name and the name of the CHM file. KeyHH will then check to see if an HTML Help window is already open that uses this identifying name. If so, the HTML Help window will simply be updated with the new CHM file or topic. If it is not open, KeyHH will create a new HTML Help window.

You can use any identifier that you want, as long as the first character does not begin with the pound (#) character.

From example above, to open a topic called flowers.htm in the CHM-example.chm file, you would use this command:

KeyHH.exe -MyID D:/_working/CHM-example.chm::/Garden/flowers.htm

Suppose you then wanted to open another topic called tree.htm you would then use this command:

KeyHH.exe -MyID D:/_working/CHM-example.chm::/Garden/tree.htm

or another topic by mapid

KeyHH.exe -MyID -#mapid 10010 D:/_working/CHM-example.chm   

All these commands resulting in one help window only:

Please note that there was a warning Don't use filenames with hyphens (e.g., new-topic.htm) when working with KeyHH.. You may have to rename your files.

I think you only need to adjust a few lines of code:

local KeyHHParam = " -MyID "
local HelpFile = strDir.."\\"..strName.." "..strVersion..".chm"
local topicpath = "options" 
local helpexecutable = "C:\\windows\\KeyHH.exe"
local helpparms = "::/"..string.lower(string.gsub(topicpath..".htm", "")
local bOK, intErrorCode, strErrortext = 
    fhShellExecute(helpexecutable, KeyHHParam..HelpFile..helpparms)