in PowerBuilder - sys-con.com's archive of magazines - SYS-CON ...

FIGURE 6 |FIGURE 8 |FIGURE 7 | FIGURE 9 |SELECT "pbcatcol"."pbc_cnam","pbcatcol"."pbc_cmnt"FROM "pbcatcol"WHERE "pbcatcol"."pbc_cmnt" is not NULL;The above query should return the column name and the column’scomment textual value as located in the PBCatCol table. For this test Iadded a comment to the Employee’s Sex column and the query aboveresulted in the ISQL result set shown in Figure 5.Help CompilationOnce you have taken the time to populate appropriate commentson the data elements within your data model (schema), the extendedproperties will also be loaded into your database’s system tables. Youcan use the technique I just described earlier to extract the columnname and the column’s comment text using the previous SQL example.To test this, I commented the “Contact” table’s columns and ran theSQL, which resulted in a two-column output in the ISQL pane of thedatabase painter. To export this information, I used the “alternate”mouse button (RHMB) and chose the “Save Rows As” option in theresulting pop-up menu. I then proceeded to save the result set as a tabdelimited text file. Using this format allows the developer to easilyinclude this key information into any help compiler.The favorite product that I use to generate help files is called “Docto-Help”from ComponentOne. I can utilize this tool to generate varioushelp file flavors for all my Web, PocketBuilder, and PowerBuilderprojects. I will briefly show you the highlights of this process. The firststep is to create a new project and import the tabbed delimited textoutput from the database painter as described above. The new projectwill generate an MS-Word document where you can import the text filewith the column name and description. At this point you must markthe column names as a procedural heading. In Doc-to-Help, you cando this by selecting each column name and setting each property to“Heading 4.” The type “Heading 4” sets the font, point size, and marksthe 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 thesub-type “procedural.” At this point you can select a property called“AutoContextID” and set this value to “True” (see Figure 7). This forcesthe Doc-to-Help Compiler in concert with the MS-Help compiler togenerate and incorporate “Context ID” numbers into your .HLP or.CHM file. From this point onward, the easy part can be enjoyed by thePowerBuilder 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 andtheir Context IDs, so now we have the direct mapping to the informationthat 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 ASA9.0 database and the columns such as City, Fax, and First Name showup as well as their Context ID numbers (see Figure 8). When coding aSingleLineEdit, MultilineEdit, DataWindow, or other type of control inPowerBuilder, you are provided with a “Help” event (present sincePowerBuilder version 8.0). The Help event is automatically triggeredwhen 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’stitle bar. Dragging the window “?” on to any control also fires the Helpevent during the drop operation.For the Help event, use the ShowPopupHelp ( ) command. If I wantedto provide Context help to the command button, for example, called“City,” my Help event would use the code: ShowPopupHelp ("CON-TEXT.HLP", THIS, 63) – which would result in Figure 9.To make this more reusable, I typically use the “Tag” property orcreate an ancestor class that adds a protected instance variable (suchas il_context_id”) where I can store the Context ID mapping that I getfrom the help compiler. You would never want to hard-code this valueas it can change as new information is added to the help file. I wouldeven take this further for pure object-oriented reusability and create aservice that would dynamically read the “mapping file” and return theContext ID based on a component name.DataWindow ColumnsFor DataWindow columns, the process has to be slightly different aswe have to consider two objects – the DataWindow control and theDataWindow object – that when combined create the “dynamic duo”that all PowerBuilder developers have come to know and love (evenVisual Studio developers now with DataWindow.NET). When the Helpevent is fired, the operating system message is actually sent to theDataWindow control but it only contains the X and Y position of theContext Help request. What the developer needs to do at this point isdetermine the column name. Luckily, we can use the “GetColumn-Name” method to return the column, which has focus in the DataWindowobject. Once we have that information, you could use the techniqueof 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 DataWindowcontrol does not activate the “Help” event and we need to acquire theinformation about the column that has focus (which is an object insidethe DataWindow object, which is inside the DataWindow Control, i.e.,nested scenario). Remember, the GUI standard for requesting Help isShift+F1, but if you try this on the DataWindow Control, the Help eventwill not fire. This seems to have been an oversight in PowerBuildersince release 8.0.We can easily simulate the Help request though by adding a userevent to the DataWindow control. In this case, we need to map a newuser event to the “pbm_dwkey” Event ID. This will allow you to receivenotifications from the keyboard. Once this event is mapped, we can18PBDJ volume12 issue11www.SYS-CON.COM/pbdj/