[lmi] help implementation

[Vaclav Slavik]

Hi,

[replying to off-list mail and quoting relevant parts in full]

Greg Chicares wrote:
>  (A) F1 does the right thing. So does the Help menu. (I just
>      wouldn't know which lmi files to change, or how.)
>  (B) Write a help file with only a couple of items:
>      (1) Something generic in "Contents", with minimal text like
>          "This is a placeholder for a general overview". Maybe
>          another one or two items just as an example of how the
>          help file can be structured into topics.
>      (2) Context-sensitive help for a single field in our input
>          dialogs. I'd suggest picking this field:
>            <object class="wxTextCtrl" name="Comments">
>          in 'skin.xrc'; text can be just "Comments placeholder".
>  (C) Then hand it over to us, and we'll fill in all the details.
>  (D) Let me worry about changing makefiles to put the final help
>      text into archives and so on.

Can you clarify the expected behavior? Do you want F1 to invoke popup 
window with contextual help (I gather this is standard behavior in 
dialog boxes and is what wx implements) or to show help viewer with 
page specific to the control or dialog the user is in? The former 
doesn't even have to involve wxHelpcontroller and can be specified in 
XRC files directly.

FWIW, here's the relevant ("Contextual Help") guideline from MSDN 

    The F1 and SHIFT+F1 keys are the shortcut keys for this form of    
    interaction. The F1 key displays the most context-sensitive Help 
    available based on the current context. In primary windows, 
    pressing F1 typically displays the HTML Help viewer with an 
    appropriate topic. In secondary windows, pressing F1 typically 
    displays the context-sensitive pop-up window for the control that 
    has the input focus. However, if you support context-sensitive 
    Help for elements of your primary window, use SHIFT+F1 to begin 
    context-sensitive Help mode, changing the pointer and enabling the 
    user to click a menu or control in the window to provide the 
    context. In secondary windows, use SHIFT+F1, like F1, to display 
    the context-sensitive Help pop-up window for the control that...

(Although you need to take with a grain of salt, it also says "F1 - 
Display Application Help and SHIFT+F1 - Display tips help 
(context-sensitive help) near the selected control." at 
http://msdn2.microsoft.com/en-us/library/ms971323.aspx and Vadim 
found this in "Keyboard Interface Summary" in the MSDN:  F1 Display 
contextual Help window  SHIFT+F1 Activate context-sensitive Help mode 
(What's This?)...)

To me, it seems best to let F1 show contextual popup when possible 
(even in the main window, because it's "dialog-like") and if there 
isn't any, show main page of the help book.

> I have a prior notion that wxHtmlHelpController would be a
> better starting point than wxBestHelpController, because AIUI
> the latter requires some ms tools that I'd much rather avoid,
> and GNU/Linux would use the former anyway. But tell me if I'm
> wrong.

wxCHMHelpController has the advantage of using native and it lets you 
provide contextual help in the help files (IIRC), which 
wxHtmlHelpController doesn't (but as you say, that's what we have to 
use on other platforms anyway).

Regards,
Vaclav

-- 
PGP key: 0x465264C9, available from http://pgp.mit.edu/