Making Help Manager Useable

By Samuel Audet

---

Last Modified: May 7, 2001 20:07:02 EDT.

---

First of all, some explanations. When trying to make the usual "help tables" work with notebook dialogs, it seems they do not accept the notebook dialogs as HELPITEMs. This is very frustrating, as it SHOULD work that way. Oh well, that's how it is... Now, here's how I think is the best (ie.: not perfect) way to implement IPF in Notebook dialogs.

First, load and associate the usual help tables with the main dialog, but leave out the notebook from it. For example, you have an "OK" and "Save" Button, here's what you'd put in the resource file:

HELPTABLE MAINTABLE
BEGIN
   HELPITEM ID_MAIN, SUBTABLE_MAIN, 1000
END

HELPSUBTABLE SUBTABLE_MAIN
BEGIN
   HELPSUBITEM ID_OKPB, 1100
   HELPSUBITEM ID_SAVEPB, 1100
END

Note: as the "extended help" for the MAIN HELPITEM, include a more general help than only the buttons, because if you leave cracks in the following method, the user expects to see something that gives information on the whole notebook.

Now in the C code, you will need a big structure containing all information needed on the notebook dialog. I always use such a structure when using Notebooks. It permits me, for example to delay loading of dialog windows to when the user requests it, or to easily find a dialog window handle to send a message to it (like we will need here), etc. Thanks Rick Fishman for that great idea everyone should use in Notebooks! Here's what I use:

/* notebook page info structure */

typedef struct _NBPAGE
{
    PFNWP    pfnwpDlg;    /* Window procedure address for the dialog */
    PSZ      szStatusLineText;  /* Text to go on status line */
    PSZ      szTabText;   /* Text to go on major tab */
    ULONG    idDlg;       /* ID of the dialog box for this page */
    BOOL     skip;        /* skip this page (for major pages
                             with minor pages) */
    USHORT   usTabType;   /* BKA_MAJOR or BKA_MINOR */
    ULONG    ulPageId;    /* notebook page ID */
    HWND     hwnd;        /* set only when page frame is loaded */

} NBPAGE, *PNBPAGE;

Then, initialize a global variable of this structure with the values, for example:

NBPAGE nbpage[] =
{
   {wpFoo,  "Tab 1 of 4", "~Foo",  ID_FOO,  FALSE, BKA_MAJOR, 0, 0},
   {wpFoo2, "Tab 2 of 4", "Foo~2", ID_FOO2, FALSE, BKA_MAJOR, 0, 0},
};

/* some constants so that we don't have
   to modify code if we add pages */
#define PAGE_COUNT (sizeof( nbpage ) / sizeof( NBPAGE ))
#define PAGE_FOO  0
#define PAGE_FOO2 1

int main()
{
   ...
}

When cooking up your notebook, make AT LEAST the window handle available.

In the main dialog (or client) window procedure, include the following. You will need to find your Notebook window handle (usually with a window ID).

case WM_HELP:
{
   HWND hwndfocus = WinQueryFocus(HWND_DESKTOP);
   HWND hwndNB = WinWindowFromID(hwnd,ID_NB);
   int i;

   /* this is useful when the user presses Help button
      and the focus is on the notebook tabs themselves */

   if(hwndfocus == hwndNB)
   {
      WinSendMsg(
         LONGFROMMR(WinSendMsg(hwndNB, BKM_QUERYPAGEWINDOWHWND,
            WinSendMsg(hwndNB,BKM_QUERYPAGEID,0,MPFROMSHORT(BKA_TOP))
                                                  , NULL))
                                                     ,WM_HELP,0,0);
      return 0; /* prevents the notebook unfriendly
                   help manager to interfere */
   }

   /* this is useful when the user presses Help button
      and the focus is on one of the notebook dialog controls */

   for(i = 0; i < PAGE_COUNT; i++)
      if(WinIsChild(hwndfocus,nbpage[i].hwnd))
      {
         WinSendMsg(nbpage[i].hwnd,WM_HELP,0,0);
         return 0; /* prevents the notebook unfriendly
                      help manager to interfere */
      }

   break; /* if focus is not on notebook controls or the
             notebook, let the usual help mechanism handle it */

case WM_CONTROL:
{
   switch(SHORT2FROMMP(mp1))
   {

   /* this is useful when the user presses F1 on a notebook tab */
   case BKN_HELP:

      WinSendMsg(LONGFROMMR(WinSendMsg(WinWindowFromID(hwnd,ID_NB),
                 BKM_QUERYPAGEWINDOWHWND, mp2 /* this is ulPageId */, NULL))
                                               ,WM_HELP,0,0);
      return 0; /* bug off Help Manager */
   }
}

Note: if you try to send a "WM_HELP" to the notebook when "hwndfocus == hwndNB" thinking you are smart because BKN_HELP is sent, and an error occurs, the notebook sends back a WM_HELP to its owner and keeps getting back more and more WM_HELP and BKN_HELP around and around, until you're quick enough to remove the focus from the notebook... don't ask me why. It's a miracle it even works.

Then, as you might have imagined where all those WM_HELP are sent to, include the following into all your Notebook dialog window procedures.

/* this is useful when the user presses F1 in
   any of the dialog controls owned by this window.
   Also, all the previous kludges send WM_HELP here. */

case WM_HELP:
   WinSendMsg(WinQueryHelpInstance(hwnd),
              HM_DISPLAY_HELP,MPFROMP("FooPanel"),
              MPFROMSHORT(HM_PANELNAME));
   return 0; /* grrr, beat off Help Manager */

Next, in your .HLP file, just include the newly defined panel name or reference you have included in all the WM_HELP messages like above. I also recommend a global variable indicating successful loading of the help file (into a help instance) so that the user won't have to mess around with errors and possible crashes.

Tada! Great help management in notebooks!