Conference abbott::visual_basic

2513.0. "WhatsThis Help Problems" by MRSERV::PETERS () Mon Mar 10 1997 17:23

There seems to be several basic problems with Micrsoft's implementation of the
"Whats This" form of Help. Note 2214 alludes to this problem, but didn't get
any responses. I'll describe the problems I encountered, and then give a
workaround that I found.

While I've written several VB4 applications, I'd never used the "Whats This" form
of Help, instead using the simpler form of VB3 Help. So, curious about this
great new feature, I thought I'd give it a try.

My first problem was with my application's main form. According to VB4's help
text, just how you get a section of your Help file to display depends upon the
setting of your WhatsThisHelp property. If set to False, the default, pressing
F1 when a control has the focus brings up Help file text for that control, using
the control's HelpContextId. Not a great idea, because the control can only get
focus by

      -  being clicked on, and presumably you want help on this control
         BEFORE you click on it

      -  hitting Tab until the control gets the focus
         (a nuisance if there are many controls on the form)

OK, so you set HelpContextId to True. Now help popup mode is in effect, which
can be a nice feature, enabling the display of popup help on the WhatsThisHelpID
of the targeted control. To do this simply, we just have to turn on the form's
WhatsThisButton. But wait. the fine print says that when you do this, you can't
resize your form! We do that a lot in our application, so we had to scratch this
technique.

But of course you don't HAVE to invoke popup help with the WhatsThisButton on the
top of the form. You can add your own button and have it invoke the forms
WhatsThisMode to do the same thing. I did this. Worked (almost) fine. Except that
this button should be captioned with the standard "upward left pointing arrow
followed by a question mark" image, in order to make its function clear to the
user. But there is no font character for "upward left pointing arrow"! Looking
through the VB4 control set, it turns out there is another command button that
allows pictures on it (SSCommand). And, if you look in the system icons directory,
there is the appropriate icon for it (you have your choice of three, actually).

But when you try it, it doesn't work. Turns out that there is some bug in the
code implementing this button that causes it not to invoke the WhatsThisMode mode,
while the regular button can do it just fine (but you can't label it properly)!


At this point is was desperate. I simply chose to recognize the MouseDown event
on a control, and then trigger the ShowWhatsThis method, which displayed the popup
help text associated with the control's WhatsThisHelpID. But I still wasn't
happy since I had a Help button on my form, but couldn't get full application
help - only popup help, since that's the mode I was in. And, wouldn't you
know it, the fine print of form property WhatsThisHelp says it is Read-Only at
run time, so you can't freely switch Help modes at run time. That didn't make
sense to me.

So finally I scrapped all Microsoft's recommendations, and went to low-level
calls. It was a bit of work initially, but it was far simpler to use. And
without any unnecessary restrictions. Here are the the implementation details:

--------------------------------------------------------------------------
First, include the declaration for the WinHelp API:

   Declare Function WinHelp Lib "user32" Alias "WinHelpA" _
   (ByVal hWnd As Long, ByVal lpHelpFile As String, ByVal wCommand As Long, _
    ByVal dwData As Any) As Long

Then you will need some constants. I got them from my old VB3 file CONSTANTS.TXT.
They are: 
 
   Global Const HELP_CONTEXT = &H1        'Display topic in ulTopic
   Global Const HELP_QUIT = &H2           'Terminate help
   Global Const HELP_INDEX = &H3          'Display index
   Global Const HELP_CONTENTS = &H3
   Global Const HELP_HELPONHELP = &H4     'Display help on using help
   Global Const HELP_SETINDEX = &H5       'Set the current Index for multi index help
   Global Const HELP_SETCONTENTS = &H5
   Global Const HELP_CONTEXTPOPUP = &H8
   Global Const HELP_FORCEFILE = &H9
   Global Const HELP_KEY = &H101          'Display topic for keyword in offabData
   Global Const HELP_COMMAND = &H102
   Global Const HELP_PARTIALKEY = &H105   'Call the search engine in winhelp

Use the following example routine if you want non-popup help:

   Sub Help(RefForm As Form, ContextId As Long)
      Dim Status As Integer
      'Use the following to get help by context identifier
      Status = WinHelp(RefForm.hWnd, App.Path & "\RefView.HLP", _
                       HELP_CONTEXT, ByVal ContextId)
   End Sub

And, if you want popup help, use this example:

   Public Sub HelpPopup(RefForm As Form, ContextId As Long)
      Dim Status As Integer
      'Use the following to get help by context identifier
      Status = WinHelp(RefForm.hWnd, App.Path & "\RefView.HLP", _
                       HELP_CONTEXTPOPUP, ByVal ContextId)
   End Sub

Finally, in the Click event of your Help button, insert the code:

   Help Me, 1

Replacing the "1" with the help context number of your choice.

To get popup help, I chose to recognize a right-click on a control, and
implemented it as in this example:

   Private Sub cmdCopy_MouseDown(Button As Integer, Shift As Integer, X As Single, Y As Single)
      'Show the help popup for a right mouse button click
      If (Button And 2) <> 0 Then HelpPopup Me, 203
   End Sub

The only problem I had was when I used this technique with a text box. In that
case the standard right-click popup appeared along with my own. Except for that,
I really like the concept: left-click for action, right-click for a note on
what the action does.