Adobe Portable Document Format (PDF) Online Help

When help is requested, if the help file specifies a Portable Document Format (PDF) file (detected by the .pdf file suffix), JADE attempts to execute Adobe Reader to handle the file. JADE checks the Windows registry for the Acrobat Reader (AcroRd32) or for the acrobat executable program.

If Adobe Reader is not found, the help request is ignored and entries explaining the cause of the failure are output to the jommsg.log file. If Adobe Reader is located, it is initiated for the PDF help file defined in JADE. See also "Using Bookmarks for Navigation around a PDF File", later in this chapter.

For a helpKeyword help request, the helpKeyword property is passed to Adobe Reader as a named destination, which Adobe Reader uses to position the help file display. As there are no equivalent concepts in a PDF file of any other type of help request (for example, helpContextId, index request, and so on), only the first page of the PDF file is displayed for a help request other than using the helpKeyword property.

When preparing your documents for PDF online help, note the following points.

The Window class helpKeyword property can contain a help file name before the keyword, separated by a semicolon. This help file (which can be a .pdf, .hlp, or .chm file) is specific to this helpKeyword property, and overrides the default value; for example:
```
btnHelp_click(btn: Button input) updating;
vars
begin
    if fldFolder.topSheet = shtSelect then
        btn.helpKeyword := "DevRef.pdf;selectinglibraryacxautomationdrg10";
    elseif fldFolder.topSheet =  shtLibrary then
        btn.helpKeyword := "DevRef.pdf;namelibrary_activex";
    elseif fldFolder.topSheet =  shtObjects then
        btn.helpKeyword := "DevRef.pdf;namingobjectclassesacxautomationdrg10";
    elseif fldFolder.topSheet =  shtInterfaces then
        btn.helpKeyword := "DevRef.pdf;naminginterfacesacxautomationdrg10";
    elseif fldFolder.topSheet =  shtConstants then
        btn.helpKeyword := "DevRef.pdf;namingconstantsacxautomationdrg10";
    endif;
    btn.showHelp;
end;
```
Although it is more efficient to use a single help file, specified in the Help File text box on the Application sheet of the Define Application dialog, this feature is intended for situations in which multiple help files are required for a single application.

If you do not specify a help file in this text box or you do not use the Application class helpFile property to dynamically set the help file at run time, no help file is opened when help is requested, regardless of the value specified in the helpKeyword property.
When handling automatic Help menu items, if a helpContextId or helpKeyword property is specified on the Help menu Index automatic menu item, the destination of the help is based on the value of the helpContextId or helpKeyword property. In addition, the click event method is not executed.

For details about the JADE initialization file parameters that enable you to configure your JADE help files, see "JADE Help Section [JadeHelp]", in your JADE Initialization File Reference.

Acrobat does not convert index fields in your source documents to named destinations. You can manually create named destinations to correspond to topics in your source file. (For details, see the Adobe Reader online help.) Alternatively, you can write a macro to generate named destinations from headings, if required. Named destinations are case-insensitive, must be unique within the document, and cannot contain spaces.

As named destinations are Print fields, an error or unexpected results can occur if you output a document containing these fields to a printer. You may therefore want to create a copy of your source file to meet you print requirements.

Alternatively, create the PDF file from your source document that contains the named destination fields and then print the PDF file.

To create a context link for a PDF help file

In your documentation for a specific topic (for example, for a Products list box control on a form that has a topic (a subsection) in your documentation for that control called "Products List Box"), insert a unique named destination field, which automatically becomes a help keyword when you generate your PDF help file. The example used in this procedure has a unique saleproduct named destination field.

To manually add a named destination field if you have not written a macro to generate named destinations from headings, perform the following actions.
1. Press Ctrl+F9.
  
  A pair of braces symbols { } is then displayed.
2. Inside the brace symbols, enter the following, where named-destination is the unique name for your named destination field.
```
PRINT "[ /Dest /named-destination /DEST pdfmark"
```
  This is the correct syntax; there is not a missing closing bracket (]) symbol.
  
  The named destination fails if there is a space after any virgule character (/) or the name of the named destination contains a space.
You can add a named destination to any part of your Word source document.

Unlike the insertion of a bookmark for subsequent creation of Windows online help when you create a source Word document for generation as a PDF help file, the named destination can be inserted in any part of the document, regardless of the formatting style applied to the text at the position you insert the named destination field.
Turn on the display of fields in your Word document (by checking the Field codes check box on the View sheet of the Options dialog, accessed from the Options command in the Tools menu). All of your named destination help fields are then displayed.
In your JADE development environment, apply the named destination keyword to your list box object. In this case, you would:
1. Edit the Products form in JADE Painter.
2. On the Common sheet of the Properties dialog for the Products list box control, specify saleproduct in the text box for the helpKeyword property.
  
  Although you can type the value into the helpKeyword property on the Common sheet of the Properties dialog, you can also copy only the portion of the field in the Word document between the Dest / and /DEST (that is, only the sales product part of the PRINT "[/Dest /salesproduct /DEST pdfmark" field) and paste it into the helpKeyword property.
Alternatively, if you cannot edit a control in Painter (for example, when the sheets of a folder control are overlaid at run time so you cannot apply help keywords to sheets in Painter), apply your keyword in your JADE code, usually in the load method for the form, as shown in the following example.
```
if products.topSheet = supplier then
    supplier.helpKeyword := "salesproduct";
elseif ... then
```
Apply help keywords in your JADE code when you have multiple sheet folders, as you do not normally want your Help button to display text relating to the whole dialog but only for the sheet that is on view.

In this case, identify the sheet that is on top and then apply the keyword using code in the click event for the Help button, like that shown in the following example:
```
if <form-name>.topSheet = <sheet1-name> then
     <sheet1-name>.helpKeyword := "<named-destination-1>";
elseif <form-name>.topSheet = <sheet2-name> then
     <sheet2-name>.helpKeyword := "<named-destination-2>";
...
```
To make your menu commands context-sensitive (or "hot"), apply your named destination help keyword by using the Menu Design facility. Specify the help keyword for your menu command index entry in the Help Id text box on the Text sheet of the Menu Design dialog.
Index entries must be unique. For example, if several of your forms have identical controls, you must further qualify each one; for example:
```
Print Option Button - invoice
Print Option Button - receipt
Print Option Button - address
```

As you cannot define the F1 key as a shortcut key on a menu item (Painter does not allow you, because Windows treats F1 key messages differently), you must implement this functionality with a keyDown event method on the top-level Form class in the application. Ensure that the key code is set to null before leaving this method so that JADE's default help processing is not actioned.

In addition, you should use the registerKeys method to specify that you are interested only in the F1 key so that the presence of the keyDown event method does not have too much impact on remote thin client users.

The PDF file must be located in the help binary directory and the exact name of the PDF file must be specified in the Help File text box on the Application sheet of the Define Application dialog for the application. However, this specification of the PDF file (for example, OurSalesApp.pdf) must be set up on the Define Application dialog and the file located in the binary directory before the appropriate command (for example, the User's Guide command on the Help menu in the application itself will launch the PDF file).