Win32 Context Sensitive Help
Contributed by Roy Kiesler
|n_cst_winsrv_contexthelp||n_cst_winsrv||Context sensitive help window service.|
If you have been using Windows 95/98 or NT 4.0 for a while, you should be familiar with the little button. It appears on many of the operating system's dialog boxes, and in many Microsoft software products. Windows applications use it to provide context sensitive help by clicking this button first, and then clicking on any control in a dialog box. As a result, a popup window with a brief description of the control's functionality is displayed.
Have you ever wandered how to implement this feature in you PowerBuilder applications? Did you ever wish this was just another checkbox in the window painter's properties dialog? This article presents a PFC implementation of this feature.
Function Description of_GetClickedObjectHandle Determines the handle of the control being clicked. of_SetContextHelpID Registers a unique help id for a given control with the operating system. of_SetHelpButton Adds the button to the window titlebar. of_ShowHelp Display the popup text for a registered control.
Enabling The Service
In order to use this service, you have to update your copy of w_master (from the PFE layer, NOT the PFC). To make things easier, the demo .PBL contains a fresh copy of w_master with all changes made for you. If you haven't made any changes to your w_master yet, you can simply replace it with this one. If you have made changes, just copy the code.
The required changes are:
- Add an instance variable of type n_cst_winsrv_contexthelp (inv_help).
- Add an of_SetContextHelp( boolean ab_switch ) function to enable/disable the service.
- Add the following code to the close event:
of_SetContextHelp( FALSE )
- Map 3 user events, ue_ParentNotify, ue_SysCommand and ue_ActivateApp to pbm_paranetnotify, pbm_syscommand and pbm_activateapp, respectively. Copy the code from the demo version of w_master for these events.
Save and regenerate w_master. Now, in order to enable context sensitive help in your dialog, put the following line in the response window's open event:
Listing 1: Open() event for a response window this.of_SetContextHelp( TRUE )
Using The Service
The service is tag-enabled. To use it, all you have to do is assign this string in the tag property of each control: "helpid=<uniqueid>" (without the enclosing <>). The service will take it from there. The file context_sensitive_help.pbl contains a small PFC application that demonstrates the use of all functions in this service.
Brian Leslie was the first to implement this functionality in native PB. He thought the PFC community could benefit from a wrapper service and offered me the challenge of creating one. Obviously, I accepted. Brian can be reached at email@example.com.
Thanks also to Philip Salgannik for the screen coordinates conversion solution. His solution enables the service to display context help for controls on userobjects, tabs etc., at any nesting level. Philip can be reached at firstname.lastname@example.org.
|1/12/1999||Initial Revision||Ver. 1.0|
timing object instance variable since the functionality it provided is now provided by the
user event mapped to pbm_activateapp on w_master.
This version also fixes a bug where the help mode was not cancelled if the mouse was clicked outside the window.
|1/15/99||This version fixes a bug where if an editable datawindow has focus and the user clicks on the current column while in help mode, then the recursive call to of_GetClickedObjectHandle was returning the handle of the edit control which floats above the datawindow, causing the default "No help topic is associated with this item" help text to be displayed.||Ver 1.3|
Interested in contributing material to this web site? Send an email to email@example.com, but don't forget to check the contribution guidelines first.
For information or suggestions about this web site please contact firstname.lastname@example.org
sponsored by Dynamic Technology Group.
The information on this site is provided for advice only and not to be considered a contract or a liability against Dynamic Technology Group.