Re: [lmi] help implementation

[Greg Chicares]

On 2008-02-25 16:38Z, Vaclav Slavik wrote:
> 
> 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.

I hope this will be straightforward now that we've arrived at the
design decisions documented below.

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

You've already done (B)(2), thanks.

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

The former, based on our recent discussions. (The "popup window"
you mention resembles a tooltip without a timer, so it's not
intrusive.) It's plenty good enough--in fact, ideal IMO--and it's
easy to maintain because help text is in the XRC files.

That takes care of one situation: when a dialog is active. Now we
need a strategy for the other one: no active dialog....

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

Perhaps we're saying the same thing, but I want to be sure.
I guess I would have said that if there's no active dialog (or
dialog container like wxBookCtrl), then there's no context for
a popup, and the main page of the help book should be shown.

But in what way is the main window like a dialog?

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

We'll put contextual help strings in the XRC files, not in the
help files, so that advantage disappears. Let's proceed with
wxHtmlHelpController for all platforms; if we don't like its
non-native appearance well enough, we can always "upgrade" to
something msw specific later, AIUI.