IPF Editor 2.x Adding Help to C or C++ Applications Q&A

What is needed to create help?

In order to set up to create help you will need the following files:

A subdirectory to hold the IPF files and tables created. We recommend against doing this in your primary application development directory.
Your applications resource files (.RC) and dialog (.DLG) files
All of the include files for your application placed in the same directory as the resource and dialog files unless they are enclosed in the (meaning they are in the INCLUDE path).
If you have include files using the set the IPFEDIT_INCLUDE statement in your CONFIG.SYS to point to the appropriate directory containing your include files.

Is the Help resource file necessary?

No. The help resource file generated during the "Create help resource tables" process need only be used for compatibility with help projects created with the IPF Editor 1.0x. The help tables are now created in the C source file generated.

If you are using C++ you may find it easier to use the help resource tables, however. Simply rcinclude the help resource file into your primary resource file. For more information on C++ support see Appendix 1 in the IPF Editor 2.x User's Guide.

What tools are needed to add help to applications

You will need the following tools:

IPF Editor 2.x
IBM C Set/2, C Set/++, Visual Age C++ (or compatible)
IBM OS/2 Toolkit (2.11 or Warp) (specifically the resource compiler)

How do I add help for new features in my application?

If you add new features (such as new dialog box items or new menu items), after you have already created help for your application, you have two choices as to how to create help for them:

First, you can simply create a new panel using the Panel List (with your already defined panels loaded) and then on the Panel Settings Notebook's "Options" page use the "Select ID" push button. Then select the #define label in the list provided that matches the dialog control or menu item you want to define help for. Then save and compile your help file when you are finished adding help. The final step requires you to rebuild the resource tables by using the "Application, Create help resource tables" menu item.

The second method is to use the "Application, Generate panels from RC file" menu item. It will ask you if you want to append these panels to the end of the current panel list. Answer "Yes". Then reselect your primary RC file and any new panels detected will be appended to the end of the Panel List. Once again save and compile your help document. Then run the "Application, Create help resource tables" menu item to rebuild the help resource tables.

You must, of course, rebuild your application after building the help resource tables or the changes will not take effect.

How to I create separate HLP files for each DLL?

Treat each DLL as if it was a separate program. This means that you will need to generate panels for each DLL's resource file, create help resource tables, and compile and link them into the DLL.

There is also one additional step which is required&colon. You must initialize the help access as shown in the following example:

case WM_INITDLG:
    HelpInit( hwnd );
    HelpInstallMessageHandler( hwnd );
    return (MRESULT) 0L;

case WM_HELP:
    return HelpDlgDllHelp( hwnd, msg, mp1, mp2 );

This code must be added to each dialog procedure in the DLL or the help will not be displayed properly.

Where are the prototypes for the IPF Editor Generated Help Functions?

The prototypes for each function generated by the IPF Editor 2.x are located in the generated include file.

How do I make "help" push buttons work in my dialog windows?

The dialog editor lets you specify both a "help" and "no pointer focus" attribute for push buttons used in dialogs. When both of these are on pressing a push button will generate a help request for the current dialog item that has the focus.

When should I process WM_HELP messages in my application?

Never - if you are using the HelpInstallMessageHandler() function. Generally the IPF Editor's message handler will handle all WM_HELP messages automatically with no further action required by you. In fact, if you do handle these messages you may prevent help from being displayed in you application.

When should I use the "help" RC file generated by the IPF Editor?

Generally you will never need to use the RC file generated by the IPF Editor. It is generated for use by customers who used earlier versions (1.0x) of the IPF Editor. New users will find it much easier to just use the help table structure defined in the generated C file.

Why do I receive a warning when scanning RC files that some panels were ignored?

The IPF Editor automatically discards any dialog controls or menu items that use ID's that match any ID already scanned (usually from a dialog control or menu item found previously in the resource files). Since the IPF language requires individual res attributes for every panel and the IPF Editor bases its generation of panels from resource files from the item's id's you should verify that you do not use duplicate res values for any push button, menu item, or other dialog control. If duplicate id's are discovered only the first one encountered will generate a panel and a help resource statement (when you generate a resource, c, and include file). This means that only the first one will respond when you press F1 for help while the focus is on the control.

When should I use "HelpInstallMessageHandler()"?

Use this in the WM_INITDLG or WM_CREATE of dialogs or windows that have an owner that is not in the primary client's window chain (i.e. it cannot trace the window chain back up to the client window initially used with HelpInstallMessageHandler()).

Why do some Combo-Boxes and Spin Buttons not have any help?

When using OS/2 Warp for Windows the HELPMGR.DLL has a small problem with creating help for these two dialog controls. Generally the IPF Editor's message handling will overcome this limitation as long as the owner window of the control is in the HelpInstallMessageHandler()'s window chain.