FWD » Core Development » User Interface

Replace the help viewer with one that can be rendered as HTML for AJAX and in Swing for GUI. Best if it just renders in HTML in both cases and then the Swing implementation uses an embedded HTML widget to display the content. It then gets invoked in response to the use of the 4GL HELP callouts (SYSTEM-HELP). The backing support for the display of URLs can potentially be reused here (see #1815).

Windows .hlp files are unsupported in recent releases of Windows. Starting in Vista, the help viewer has to be manually installed. Starting in Windows 10 and Windows Server 2012, the viewer is not even supported at all (not sure if it works or not). Microsoft recommends shifting away to HTML.

https://support.microsoft.com/en-us/help/917607/error-opening-help-in-windows-based-programs-feature-not-included-or-help-not-supported
https://msdn.microsoft.com/en-us/library/windows/desktop/ms728460(v=vs.85).aspx

https://en.wikipedia.org/wiki/WinHelp has some good context and resources. The conversion utilities should be investigated.

Apparently the HEIGHT is interpreted as KW_HEIGHT_C, instead as KW_HEIGHT, as the parser expects. The WIDTH seems to be handles correctly. To test it, I did the following change in progress.g:
...
and the result was fine: it converted successfully (with addition of new code from task branch 1830a, revision 11159).

However, this does not seem the correct thing. Which is the correct fix here?

Actually, it IS the correct change. In the 4GL, in all places they treat HEIGHT as the abbreviation of HEIGHT-CHARS. You will find that:

SYSTEM-HELP "helpfile6" POSITION X 1 + 1 Y 1 + 2 WIDTH 100 + 200 HEIGHT-CHARS 100 + 200.

is valid 4GL code.

This was a latent bug in which I coded it incorrectly as the otherwise non-existent KW_HEIGHT. ANTLR just silently creates a new token in such a case, which is not correct and will not work with our implementation.

Ovidiu's proposal for this code:

SYSTEM-HELP "helpfile1"  WINDOW-NAME CURRENT-WINDOW CONTENTS.
SYSTEM-HELP "helpfile2"  CONTEXT 1 + 0.
SYSTEM-HELP "helpfile3"  HELP-TOPIC "topic-string".
SYSTEM-HELP "helpfile4"  KEY "key-string".
SYSTEM-HELP "helpfile5"  ALTERNATE-KEY "alt-key-string".
SYSTEM-HELP "helpfile6"  POSITION X 1 + 1 Y 1 + 2 WIDTH 100 + 200 HEIGHT 100 + 200.
SYSTEM-HELP "helpfile7"  POSITION MAXIMIZE.
SYSTEM-HELP "helpfile8"  QUIT.
SYSTEM-HELP "helpfile9"  SET-CONTENTS 0 + 1.
SYSTEM-HELP "helpfile10" CONTEXT-POPUP 0 + 2.
SYSTEM-HELP "helpfile11" PARTIAL-KEY "partial-key-string".
SYSTEM-HELP "helpfile12" MULTIPLE-KEY "c" TEXT "multiple-key-string".
SYSTEM-HELP "helpfile13" COMMAND "command-string".
SYSTEM-HELP "helpfile14" FINDER.
SYSTEM-HELP "helpfile15" FORCE-FILE.
SYSTEM-HELP "helpfile16" HELP.

would be converted to this:

HelpService.prepare("helpfile1").setWindow(currentWindow()).contents().show();
HelpService.prepare("helpfile2").setContext(plus(1, 0)).show();
HelpService.prepare("helpfile3").setTopic("topic-string").show();
HelpService.prepare("helpfile4").setKey("key-string").show();
HelpService.prepare("helpfile5").setAlternateKey("alt-key-string").show();
HelpService.prepare("helpfile6")
           .setPosition(plus(1, 1), plus(1, 2), plus(100, 200), plus(100, 200))
           .show();
HelpService.prepare("helpfile7").maximized().show();
HelpService.prepare("helpfile8").quit().show();
HelpService.prepare("helpfile9").setContents(plus(0, 1)).show();
HelpService.prepare("helpfile10").setContextPopup(plus(0, 2)).show();
HelpService.prepare("helpfile11").setPartialKey("partial-key-string").show();
HelpService.prepare("helpfile12").setMultipleKey("c", "multiple-key-string").show();
HelpService.prepare("helpfile13").setCommand("command-string").show();
HelpService.prepare("helpfile14").finder().show();
HelpService.prepare("helpfile15").forceFile().show();
HelpService.prepare("helpfile16").help().show();

I'm generally OK with this approach. The code currently has a partially stubbed conversion that is not as good as your proposed approach. The only thing is that quit() is itself an action that would not need show().

I did not post the content from note 7 because it seems that all options are in fact some kind of primitives to communicate with the help window. It might need to rethink it a bit. As one can QUIT the help window, he can also move/reposition the window - using one of the POSITION form, or navigate to a desired location inside the already open help file. In consequence, I chose to replace show with execute, for the moment.

In ABL, the options are all (except for WINDOW-NAME) mutually exclusive, and they cannot be combined. If you want to display a certain help topic in a maximized help window, you need to issue two SYSTEM-HELP statements. With 1830a, revision 11159, in FWD this would be possible, using the implemented option-chaining mechanism, but this would not be fully compatible with ABL.

For the moment I don't know how the help system will be implemented in FWD, but the conversion implementation from 1830a should be capable to support any ulterior decision.