|C H A P T E R 21|
X-Designer provides extensive on-line help which can be accessed from many different points in the application. This chapter describes the support that X-Designer provides for building help into your application.
The model used to support help in your application is very simple. You can either use the help callback, available with all Motif widgets, or an activation callback on a help button. Therefore, to provide context-sensitive help, all you need is a generic callback that takes as its client data the help (or a path to the help) to be displayed when the callback is invoked. In X-Designer this help specification is defined as a document path and a marker that denotes some reference in that document. We supply a callback that can be used with one of the help system interfaces provided with X-Designer. See Help Viewers for more information on which systems are provided to display your help.
Obviously you are free to re-implement the callback that you use in your application to make it interface with the help system of your choice. Likewise, you can achieve the same effect simply by using the ordinary callback mechanisms, or you can decide not to give your users any on-line help at all.
Internally, X-Designer uses two systems when displaying help:
In order to try out your help within X-Designer you will have to use one of these.
By default in Motif the Help callback is invoked by the Help action which is specified for every widget. This action is bound to the <osfHelp> key using a default translation in every Motif class.
X-Designer provides interfaces to the following viewers:
You can use these to display help in your application. They are explained in more detail in the following sections.
You set up help for your application in the same way, regardless of which viewer you intend to use. You then link your application with the appropriate supplied library, as described in Help Implementation.
XD/Help is X-Designer's own help viewer and is shown in FIGURE 21-1.
The XD/Help help viewer contains a menubar with "File", "Edit", "Navigation" and "Help" menus containing file, editing and navigation commands respectively. The "Help" menu contains version information and help on using XD/Help. A toolbar is also provided with buttons for quick access to most of the menu items. As you pass the mouse pointer over the toolbar buttons, information about the function of the button is displayed in the status line at the bottom of the viewer window.
There are two text areas in the help viewer. The topmost text area displays help about the currently selected topic. The bottom area contains links to other related topics. Double clicking over one of the links displays help on that topic.
The files used by XD/Help are in HTML (HyperText Markup Language). This is a public domain format which uses only printable characters and can, therefore, be created in any text editor. It is also a standard used by many applications.
XD/Help does not claim to be a full HTML interpreter; it recognizes a subset of HTML and interprets them in a simple way. HTML Tags describes the HTML keywords recognized by XD/Help and the way they are interpreted.
See Appendix F for suggested books on HTML.
Netscape is a browser which takes HTML (HyperText Markup Language) files and displays them complete with any hypertext links or special formatting you have specified.
Netscape also provides file operations and navigation commands allowing the user to browse around the help files you provide.
FrameMaker is a desktop publishing package which uses its own internal format. FrameMaker also provides a means of viewing and browsing around read-only documents. For information on using FrameMaker as your help viewer, see Using FrameMaker.
Both XD/Help and Netscape read HTML files. You will need to write the files so that you have specified HTML anchors at points which will be the source and destination of a link. You should remember the names of these anchors as they are used to specify the help action for individual widgets.
These anchor points are the "markers" in X-Designer which are specified in the Help callback. Setting up Help callback markers is explained in Setting up Help in X-Designer.
To use either XD/Help or Netscape as the help system in your application you will need to do the following:
1. Create the help files in HTML format
You do not have to create a separate file for each topic as, in HTML, you can have links within the same document. In order to maintain the help text, however, you may wish to have separate files. Because XD/Help uses a subset of HTML, you will need to refer to HTML Tags for details on which HTML keywords are recognized by XD/Help.
2. Specify the Help callback for individual widgets or for whole modules
See Setting up Help in X-Designer for information on adding help callbacks to widgets in your design. Note that you will need to follow the instructions in Linking Help Into Your Application so that the help callback is defined in your application.
3. Link the generated code with the XD/Help or Netscape libraries provided
See Help Implementation.
This section gives a brief description of the major HTML keywords, known as tags. The tags listed here are all those interpreted by XD/Help. The description given offers an indication of the way the tags are interpreted by most full HTML interpreters (such as Netscape) and the way they are interpreted by XD/Help, if different.
In HTML tags are enclosed within angle brackets (< and >). You must use these brackets in your text files. See Example HTML Document for an illustration of the way you should use HTML tags in your documents.
The tags have been divided into categories according to their usage. Note that the tags are listed here in uppercase. HTML, however, is not a case sensitive language. You can, therefore, use either case.
<HTML> All HTML documents start with this tag.
</HTML> HTML documents end with this.
<A NAME="anchorname">text</A> This is an anchor which will be used as the destination of a link. anchorname is your internal name for the anchor. text is the text you want people to click on to go to the link destination.
<A NAME="#anchorname">text</A> This is the source of a link to another part of the same document. anchorname is the internal name given to the anchor.
You can have links to other files using relative or absolute pathnames. An external file can even reside on another server. For external links anchorname is the filename and you should omit the `#' sign at the beginning.
<P> This tag is used to indicate the start of a paragraph. Paragraphs are separated by a blank line.
</P> This tag is used to indicate the end of a paragraph.
<BR> This tag indicates a hard line break. If there is no line break, the text will flow to fit the width of the browser window.
XD/Help does not handle the different types of list in the way most HTML interpreters do. Lists are interpreted for compatibility so that existing HTML documents can be used.
<OL> Indicates that the following lines are an ordered list. Most HTML implementations would put a number in front of the list items but XD/Help simply prints a `-' (dash).
</OL> Indicates the end of an ordered list.
<UL> Indicates that the following lines are an unordered list. Most HTML implementations would put a bullet mark in front of the list items but XD/Help simply prints a `-' (dash).
</UL> Indicates the end of an unordered list.
<DL> Indicates that the following lines are a definition list. Most HTML implementations would expect a "term" and a "definition" as in a glossary--XD/Help simply prints a `-' (dash) in front of each item in the list.
</DL> Indicates the end of a definition list.
<LI> Indicates a list item. A `-' (dash) is printed at the beginning of the line.
<DT> Indicates a "term" in a definition list. XD/Help treats these as plain list items.
<DD> Indicates a "definition" in a definition list. XD/Help treats these as indented list items with no `-' (dash).
<EM> Indicates the following text should be emphasized. Some HTML interpreters use italic and some use bold. XD/Help prints a `*' (asterisk) before and after the text.
</EM> The end of the text to be emphasized.
<B> Indicates the following text should be printed in bold. XD/Help prints a `*' (asterisk) before and after the text.
</B> The end of the text to be printed in bold.
<I> Indicates the following text should be printed in italic. XD/Help prints a `*' (asterisk) before and after the text.
</I> The end of the text to be printed in italic.
HTML defines a range of headings from "H1" to "H6" which, according to most HTML interpreters, start large and bold and gradually lessen in size and weight. XD/Help simply prints two blank lines before a heading. The heading tags indicate the beginning and end of the text of the heading:
<H1>First Level Heading</H1>
<H2>Second Level Heading</H2>
<H3>Third Level Heading</H3>
<H4>Fourth Level Heading</H4>
<H5>Fifth Level Heading</H5>
<H6>Sixth Level Heading</H6>
<PRE> Most HTML interpreters format the text in a HTML document ignoring any extra spaces, tabs or line returns. The "preformatted" tag causes the interpreter to print the text as you typed it and uses a monospaced font, such as Courier. XD/Help only prevents the output function from stripping white space.
</PRE> End of preformatted text.
Below is an example of a help document written for XD/Help in HTML:
A complete list of help topics is available, and can be viewed by similarly selecting the `Index of Help Topics' item.
This file is shown displayed in XD/Help in FIGURE 21-1.
If you plan to use FrameMaker to build your help system, you must know how the FrameMaker hypertext system works. Complete documentation is provided in your FrameMaker manuals and a brief summary is given below.
FrameMaker lets you mark places in the text as either source or destination markers. Destination markers are places you can jump to in a help document. Source markers are places in a help document or your application that the user can select which cause an action, usually a jump to a destination marker. Source markers in a help document require a visual clue to tell the user he can click on them. The best way to do this is to specify a character format such as italics or underline to denote a source link.
When the user clicks in a document at a place where the special character format is in effect, FrameMaker checks for a source marker in that area. If it finds one, it highlights the whole graphical area or section of text and executes the action specified by the marker.
You can insert these special markers into your FrameMaker document by using the "Marker" command from the Special menu.
1. Select "Hypertext" from the Marker Type list.
2. To specify a destination marker, type: newlink <tag_name> in the Marker Text field.
3. To specify a source marker, type: gotolink <tag_name>
A tag can be specified either as <tag_name> for a tag in the current document, or as <document_name>:<tag_name> for a tag in a different document.
4. Hypertext markers are only effective in a locked document. To toggle the lock of a document on or off, type: <escape> <F> <l> <k>
5. To exit from a locked document, type: <escape> <f> <c>
This command gives you the option of saving the document in its locked state.
The term tag means the combination of a document and a marker. Help Tags are specified from the "Code generation" page of the Core resource panel. There are two Help tags that can be specified: one for the Help callback, which can be specified for any Motif widget, and one for the Activate callback, which can only be specified for PushButton and CascadeButton widgets.
To specify a tag, type the name of the document and the name of the marker, and press "Apply". You should now be able to display that document by invoking the callback in the dynamic display, which is done by clicking on the button for an Activate callback, or pressing <F1> for a Help callback.
When you specify tag information in the Core resource panel, X-Designer automatically adds the callback function XDhelp_link() to the appropriate callback list for the widget. You do not have to specify a callback in the Callbacks dialog for the widget.
You may be able to specify some of your help information by typing the marker only, without having to retype the name of the help file. If you specify a marker but no document name for the Help callback, X-Designer uses the Help callback document of the closest parent widget. If none of the widget's ancestors has a Help callback document, X-Designer uses the default document specified in the Module Help defaults panel, as described in Module Defaults.
In the case of the Activate callback, if no document is explicitly set the document for the Help callback is used. If this is not set, the same Help document inheritance, described above, takes place.
If you are running X-Designer in Windows mode, you can specify Activate Help callbacks which are then mapped through to the Windows code.
When the generated application is run on Windows, these callbacks invoke the default web browser on the system using the specified URL and a pre-defined help path. The help path is specified in the Help Defaults dialog which is displayed by selecting "Help Defaults" from the Module menu. The default path should be set to the root of the HTML included with the application.
To allow the HTML files to be opened on multiple platforms, you need to be able to modify the path to the root of the HTML according to the platform. For example, the path c:\program files\myapp\myhtml will not work with the Motif XP version of the help system. In order to help you with this, X-Designer generates the following structure into the stubs and the main code file.
In the main code file the following is generated:
The stubs file contains a similar structure:
This structure can be modified and extended. Modifications are retained when code is regenerated. This allows you to specify the help path for any system you intend to use for the help, as shown in the following example:
You then need to specify DUAL_PLATFORM in the project settings for your application. If you do not wish to provide absolute paths, you can use this mechanism to pick up environment variables or settings from the registry.
There are numerous help defaults that can be specified on a per module basis. To specify these defaults, pull down the Module Menu and select "Help defaults". The resulting dialog is shown in FIGURE 21-2.
The Help Defaults Dialog lets you specify defaults for use both in building the help system in X-Designer and in the finished application.
All help tag document names are assumed to be relative paths unless they begin with "/". This field specifies a default path to be added to the beginning of any relative path document names. The Default path is also used to find documents when you test your help in X-Designer.
This field specifies an event to be added as a translation to every widget that has a marker specified for the Help callback. The translation calls the Help() action. This lets you designate a key combination as an application help key.
This toggle makes the FrameMaker integration callback display the document in its own window. If this toggle is off, an existing window is used to display the new page. You can designate the use of a new window for individual pages using the "Own window" toggle in the Help documents and markers dialog.
The "Activate callback" and "Help callback" buttons in the "Code generation" page of the Core resource panel can be used to display a dialog showing all the documents and markers that are currently referenced by your design.
This button pops up a file selection dialog to help you navigate in the file system. You can also display this dialog by selecting the "Default path" or "Default document" buttons in the Help defaults dialog.
This button makes X-Designer try to connect to the selected help viewer and display the named document at the named marker. Select which help viewer you wish to use in the Module Help Defaults dialog--see Module Defaults.
Each document has an "Own window" flag associated with it. This flag forces the system to display this document in its own window, not to share a common window with other documents. This toggle lets you designate the state of the flag for the selected document.
To use X-Designer's default help callback function, you must link in the supplied object files which can be found in X-Designer's installation directory (referred to below as $XDROOT).
There are three directories, one for each help viewer. For XD/Help and FrameMaker you will also need to link with additional files.
To use XD/Help you will need to link the file helplink.o in with your application. The source of this object file, helplink.c, is found in:
There is also a Makefile with instructions for building helplink.o and a file named README with information on linking in XD/Help.
In addition you will need to link in the library in:
There is a Makefile in that directory with instructions for building the library.
To use Netscape you will need to link the file helplink.o in with your application. The source of this object file, helplink.c, is found in:
There is also a Makefile with instructions for building helplink.o and a file named README with information on linking in Netscape.
To use FrameMaker you will need to link the file helplink.o in with your application. The source of this object file, helplink.c, is found in:
There is also a Makefile with instructions for building helplink.o and a file named README with information on linking in FrameMaker.
In addition you will also need to build the files in
There is a Makefile in that directory with instructions for building the library.
You can also supply your own Help callback function. This function should also be called XDhelp_link() and should follow the same form as X-Designer's function. See the Help Implementation section below for suggestions on how to customize the Help callback function.
The preceding descriptions show how the help system works within X-Designer. If you use the default Help callback provided with X-Designer, the help in your application will work in the same way. However, you may want to customize your implementation of the Help callback. The following sections describe how to do so using the FrameMaker integration as a guide.
The X-Designer directory libhelplink/fmhelplink contains all the sources for the FrameMaker integration callback XDhelp_link. The subdirectory libframe contains various source files, adapted from the FrameMaker release. The original files are in $FMHOME/source/openmaker if you want to check them out.
XDhelp_link() receives a client_data parameter that is a pointer to an _XDHelpPair_t structure:
This contains a pointer to an _XDHelpDoc_t structure, a pointer to a marker (tag), and an open_doc flag. If tag is NULL the developer has specified one of the default markers: <Widget name> if open_doc is FALSE, <Open> if open_doc is TRUE. The document structure is:
The doc field is the name of the document. path is a pointer to the default path if one exists. This path is calculated as described above, taking account of the setting of the help path application resource and environment variable. handle is the document handle returned from FrameMaker, and new_window specifies whether the document is to have its own window.
The main code file contains static arrays of documents and markers, and an array of tag pairs that points into the other arrays. A pointer to an element in the tag pairs array is passed as the client data.
XDhelp_link() calls the appropriate routines to communicate with FrameMaker to display the document as requested. Other implementations of XDhelp_link() communicate with different help systems. There are libraries supplied for integrating with Netscape and with XD/Help.