Cover Story

Digg This!

Page 2 of 3   « previous page   next page »

The favorite product that I use to generate help files is called "Doc-to-Help" from ComponentOne. I can utilize this tool to generate various help file flavors for all my Web, PocketBuilder, and PowerBuilder projects. I will briefly show you the highlights of this process. The first step is to create a new project and import the tabbed delimited text output from the database painter as described above. The new project will generate an MS-Word document where you can import the text file with the column name and description. At this point you must mark the column names as a procedural heading. In Doc-to-Help, you can do this by selecting each column name and setting each property to "Heading 4." The type "Heading 4" sets the font, point size, and marks the column name as "procedural" help (see Figure 6).

Doc2Help will automatically generate Context IDs for any project. In the project painter of Doc-to-Help, select "topic types," then the sub-type "procedural." At this point you can select a property called "AutoContextID" and set this value to "True" (see Figure 7). This forces the Doc-to-Help Compiler in concert with the MS-Help compiler to generate and incorporate "Context ID" numbers into your .HLP or .CHM file. From this point onward, the easy part can be enjoyed by the PowerBuilder developer who only has to use the ShowPopupHelp ( ) command to activate this great MS-Windows feedback mechanism. Doc2Help has also generated a reference file for the PowerBuilder, VisualBasic, C#, Delphi, etc., programmer as to the topic names and their Context IDs, so now we have the direct mapping to the information that we need for the help or bubble help feature we want to use.

In the test case above, I used the "Contact" table in the sample ASA 9.0 database and the columns such as City, Fax, and First Name show up as well as their Context ID numbers (see Figure 8). When coding a SingleLineEdit, MultilineEdit, DataWindow, or other type of control in PowerBuilder, you are provided with a "Help" event (present since PowerBuilder version 8.0). The Help event is automatically triggered when the application user has focus on the control and presses the "shift+F1" key. Also, in a response dialog, you use the "ContextHelp" property (set to True) to have the O/S generate a "?" on the window's title bar. Dragging the window "?" on to any control also fires the Help event during the drop operation.

For the Help event, use the ShowPopupHelp ( ) command. If I wanted to provide Context help to the command button, for example, called "City," my Help event would use the code: ShowPopupHelp ("CONTEXT.HLP", THIS, 63) - which would result in Figure 9.

To make this more reusable, I typically use the "Tag" property or create an ancestor class that adds a protected instance variable (such as il_context_id") where I can store the Context ID mapping that I get from the help compiler. You would never want to hard-code this value as it can change as new information is added to the help file. I would even take this further for pure object-oriented reusability and create a service that would dynamically read the "mapping file" and return the Context ID based on a component name.

DataWindow Columns
For DataWindow columns, the process has to be slightly different as we have to consider two objects - the DataWindow control and the DataWindow object - that when combined create the "dynamic duo" that all PowerBuilder developers have come to know and love (even Visual Studio developers now with DataWindow.NET). When the Help event is fired, the operating system message is actually sent to the DataWindow control but it only contains the X and Y position of the Context Help request. What the developer needs to do at this point is determine the column name. Luckily, we can use the "GetColumnName" method to return the column, which has focus in the DataWindow object. Once we have that information, you could use the technique of storing the Context ID in the "tag" property.

Once you have the column name and its Context ID, the ShowPopupHelp ( ) method should do nicely here. However, the DataWindow control does not activate the "Help" event and we need to acquire the information about the column that has focus (which is an object inside the DataWindow object, which is inside the DataWindow Control, i.e., nested scenario). Remember, the GUI standard for requesting Help is Shift+F1, but if you try this on the DataWindow Control, the Help event will not fire. This seems to have been an oversight in PowerBuilder since release 8.0.

We can easily simulate the Help request though by adding a user event to the DataWindow control. In this case, we need to map a new user event to the "pbm_dwkey" Event ID. This will allow you to receive notifications from the keyboard. Once this event is mapped, we can use the KeyDown ( ) method in PowerBuilder to determine the exact keys pressed. Once we have determined that context help is required, we can easily fire the real Help event. The code for the "key" user event on the DataWindow Control should be:

IF KeyDown ( KeyShift!) = TRUE THEN
    IF KeyDown ( KeyF1!) = TRUE THEN
      THIS.POST Event Help (0,0)
    END IF
END IF

As you can see from the above code, the real Help Event is activated on a Shift+F1. Since we don't know the object that has focus, you can pass the value "0,0" as the arguments.

In the real DataWindow control's Help event, we can use the "0,0" arguments to determine that the "Key" User Event has probably been the trigger of how we arrived here in this code segment. The next step would be to get the column name and then its tag property where you may have stored the Context ID. The code for the DataWindow Help event might be as follows:

String			ls_object
Long			ll_id
ls_object	=	THIS.GetColumnname ( )
ll_id		=	Long (THIS.Describe(ls_object +".Tag"))
ShowPopUpHelp ("CONTEXT.hlp", THIS, ll_id )

In the above code segment, the DataWindow control interrogates the DataWindow object for the column name that the user is focused on. Once it has the name, you can use the Describe ( ) method to acquire the "tag" property setting. Converting the Tag property to a Context ID number to forward into the ShowPopUpHelp ( ) method completes the requirements and the real columns' context help should appear (see Figure 10). To make this design even more dynamically configurable, I would suggest writing a PowerBuilder utility program that reads the Context Map from the latest help file build - loading this information into a database table. Then, the Context ID can be ascertained by reading the database table at runtime. That way, if you rebuild the help file and resequence all the Context IDs, you can simply reload the database table with the current mapping information. This will avoid a lot of work updating all the column "tag" properties, recompiling, and redistributing the application and help file(s).

PocketPC
Getting back to the original PocketBuilder context-sensitive help issue I started describing at the beginning of this article - since we cannot use the nice features from the PowerBuilder world that I outlined earlier in this article, how could I implement a robust feedback mechanism to the Pocket PC user? One of my first thoughts was to extend my Software Tool & Die Inc. (STD) Foundation Classes (FC) to emulate a standard MicroHelp bar on an MDI type of window class. As it turns out, the "Controller" window class in the system STD framework is emulating an MDI behavior. All I would have to do is extend its features to include such a feature.

In the real old days of PowerBuilder (i.e., releases 1 and 2), we did not have an MDI window as the version of MS Windows that PowerBuilder supported at that time did not yet have the MDI feature. So creative developers used User Objects to design such an object class and allow this to be used, like an early version of the MDI MicroHelp bar. I decided that the STD FCs could easily implement this feature and created a "vc_status_bar" object class. This object has one public method (of_Set_StatusBar) that allows external routines to send the object the message text to be displayed (see Figure 11). The user object is also attached to the "abstract" level MDI Controller window class (wn_Controller_Master). The Base class window was enhanced to include an "of_Set_StatusBar" method, which allows the redirection of the display text to the user object. In the Controller window class, this function is extended to work with the user object. In all other windows classes, the method ignores the request, as the Status Bar user object is not present.

Page 2 of 3   « previous page   next page »