Re: [lmi] help implementation

[Greg Chicares]

On 2008-02-27 12:10Z, Vaclav Slavik wrote:
> Greg Chicares wrote:
>> > 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.
> 
> Yes.

In light of the discussion below, let me try to reformulate the
strategy more precisely:

 - If the focused window contains controls governed by XRC,
   then we use <help> and possibly helptext="...". The user
   interface by which the wx help provider serves up the
   help text is just great; I wouldn't change it at all.

 - Otherwise, we show the main page of the help book.

Once we have a simple specimen help book, we can validate that
strategy completely. I'm not sure what will happen if the focused
window contains controls *not* governed by XRC, but I don't think
that case will be important enough to worry about. I'm not sure
what will happen if an XRC wxNotebook tab is focused (the tab
itself, as distinct from the notebook page it corresponds to).

>> But in what way is the main window like a dialog?
> 
> What I meant was that even the main window's MDI windows are "dialogs" 
> in the "window with a bunch of standard controls" sense.

Okay, most of them are. Some aren't--e.g., the wxHtmlWindow
"calculation summary" shown after
  File | New | Illustration
  Enter
In that case, as for a frame with no MDI child, we'd want F1 to
show the main help page.

> Look at 
> rounding or policy editors -- they consist entirely of controls, much 
> like dialogs do and I think it makes sense to provide contextual help 
> for these controls too.

Agreed. Those two use XRC, so adding contextual help to them is a
simple task that fits perfectly with our help strategy. The
  File | Preferences
dialog also belongs in this category.

> Obviously, that's not the case for database 
> editors.

The '.db4' and '.tir' editors are also dialog-like wxViews with
multiple controls. But they don't use XRC, so they don't fit well
with our strategy of using XRC to provide all contextual help.

It would be ideal to provide contextual help for them, but I
wouldn't change our help strategy just for that. Maybe someday
we should consider reimplementing them with XRC.

> But the guidelines I cited earlier actually provide instructions for 
> this situation: F1 should show main help page and Shift-F1 should 
> show popup help for the control with focus.

Well, yes, there are guidelines that specify those behaviors.
I'm even aware of them because I've read books about this stuff.
But I don't think msw users care or even know what Shift-F1 is
supposed to do.

Anyone who does care will be disappointed:
 - msw "task manager": Shift-F1 does nothing at all
 - "firefox", adobe "acrobat": no help whatsoever on dialogs
 - ms "freecell": F1 and Shift-F1 both do what Shift-F1 should
 - ms "internet explorer": F1 and Shift-F1 behave the same
 - msw "media player": F1 and Shift-F1 behave the same
I tried several other msw applications, and found only two that
follow the guidelines: the ms spreadsheet and word processor.

I'd say we just do whatever wx makes it easy for us to do, and
then step back and look at what we've done: if it doesn't feel
wrong, then it's right, and we're done. I'm already implementing
the strategy for contextual help on dialogs and dialog-like
windows, and it feels right. I know users will be happy with it.