Manual for wxHelp 1.30:

A hypertext help system for wxWindows

Julian Smart

Knowledge Based Decision Support Group Artificial Intelligence Applications Institute

80 South Bridge University of Edinburgh

EH1 1HN

April 1993

Contents

1 Introduction 4 1.1 What is wxHelp? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2 How to use wxHelp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3 Command buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Editing 6 2.1 File format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.2 Generation of wxHelp files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

3 Accessing wxHelp from other applications 8

Copyright notice

Copyright (c) 1993 Artificial Intelligence Applications Institute, The University of Edinburgh

Permission to use, copy, modify, and distribute this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice, author statement and this permission notice appear in all copies of this software and related documentation.

THE SOFTWARE IS PROVIDED “AS-IS” AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WAR-RANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL THE ARTIFICIAL INTELLIGENCE APPLICATIONS INSTITUTE OR THE UNIVERSITY OF EDINBURGH BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHAT-SOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Chapter 1

Introduction

1.1 What is wxHelp?

wxHelp is a help system for wxWindows programs running under X and Windows 3. It allows the programmer to develop hypertext, browsable help which may be invoked using the API supplied with wxWindows (see the wxWindows user manual and wxHelpInstance class). Like Windows 3 help, it allows the user to click on words and phrases to see more detail, and search for topics matching a keyword. Unlike Windows 3 help, ASCII files may be marked up interactively using edit mode, and the system runs under both X and Windows 3.1

1.2 How to use wxHelp

When installing wxHelp, set the environment variable WXHELPFILES to be the list of directories you wish wxHelp to search when loading a file. wxHelp also searches the directories in the PATH variable.

To invoke wxHelp, start it on the command line with an optional filename, e.g.

  % wxhelp -f help.txt

If you specify the -edit switch, wxHelp will start up in Edit mode.

There is also a -server switch for specifying the numeric identifier used by programs connecting to wxHelp (see later).

A contents page should appear, with highlighted blocks of text, some of which are mouseable (click with the left mouse button). Clicking on these takes you to other parts of the help file.

Above the main text area is a panel with buttons for commonly-used operations, and a menu bar.

1.3 Command buttons

• Contents – displays the first section, normally a contents page.

• Search – pops up a dialog box. The user may type a string (or an asterisk) into the text item, press Do Search, and click one of the matching section headings displayed in the listbox.

• Back – goes to the previously-visited section or block. This works across different files, since the recorded history includes file names.

• <<– goes to the previous sequential section.

• >>– goes to the next sequential section.

Editing

If you start wxHelp with the -edit switch you will get more functionality and some extra menus.

You can now highlight blocks of text by dragging with the left mouse button, and assigning new block types to them using the Blocks menu. If you change your mind after selecting a block, deselect the block before dragging again or you’ll have two overlapping selected blocks! Dragging is fiddly - the rectangle must be just within the block.

Select/deselect a marked block with shift left-click: it will be marked in cyan (or inverted on a monochrome display) if selected.

Link block A to block B by selecting B, going back to A, right-clicking on A and selecting the Link block to selection menu item. Use this menu to unlink or clear the block.

Find out the block type and when the block is linked with CONTROL left-click.

You can also link blocks to blocks which are in another file, after loading a file, selecting a block, going back the previous section (using the Back button) and linking as per usual.

The usual way to proceed is to take an ASCII file with section headings, then mark it up. Or you could generate the .xlp file automatically (as with the wxWindows help file, reconstructed from the Latex manual.)

2.1 File format

A help file consists of plain ASCII text, with blocks marked with codes as in the following:

  \hy-X{Y}{Text}

where X is the block type and Y is the block identifier (unique within a file). The block type indicates the style of the block (font, colour, section), where the mapping between type and style is defined in a table in wxhelp.cc. See the file wxhlpblk.h for a list of block type constants; you may include this file into programs which generate help files (for example).

Note that blocks may be nested, in which case any styles in an inner block which have been the assigned ‘default’ characteristic will inherit the style from the outer block.

At the end of a file there is an optional index section, for example:

\hyindex{
"wxWindows Help"
101 102 "wx.xlp"
114 115
117 118
120 121
123 124
}

The first line indicates the start of the index, the second line is a title for the help file, subsequent lines (until a closing curly bracket) indicate the link between two block identifiers, with an optional filename after each pair of (long) integers.

2.2 Generation of wxHelp files

The program tex2help generates .xlp files from LaTeX documents; in particular, it is used on classes.tex from the wxWindows user manual and hyText user manual. The utility makes use of the library tex2any which handles parsing and traversal of LaTeX file structure, allowing the conversion utility to simply output appropriate block information and text to files. Unfortunately I do not have time to document these programs, but examination of the source should give an idea of what’s going on.

The file wxhlpblk.h contains block type definitions used by wxHelp and may be included by generators to ensure blocks of the appropriate type are generated.

Accessing wxHelp from other applications

There are two main ways in which wxHelp may be used by other applications. The simplest is via the API (Application Programmer’s Interface) included with the wxWindows system, as documented in the reference manual under wxHelpInstance. The other method is to use the DDE (Dynamic Data Exchange) commands on which the API is built. The only reason for doing this might be to access wxHelp from non-wxWindows applications running under Windows 3.1 (such as Visual Basic programs).

Under UNIX, the service name (the identifier for connecting to a DDE server) is generated at random by the API and passed to wxHelp when running it by specifying the -server switch. This is not fool-proof but usually doesn’t result in a socket clash.

Under Windows, the service name is always assumed to be “4000”, since there is only ever one instance of wxHelp running under Windows (a restriction of large model programming).

Listed below are the commands that wxHelp implements by means of a string sent to it using the Execute DDE command. Each string comprises an initial command letter followed by a space, followed by an argument, for example “f help.xlp”.

• b Display block command. The argument is interpreted as a long integer indicating the block id at which the file is to be displayed.

• f Load file command. The argument is interpreted as a filename, and the current directory, WXHELPFILES variable and finally PATH variable are searched for the file. If the file is still loaded, it is not reloaded, so this command may be used to ensure that a subsequent display command refers to the correct file.

• k Keyword search command. The argument is interpreted as a string for matching against section headings. If only one matching section is found, it is displayed, otherwise the search dialog is shown for the user to make a selection.

• s Display section command. The argument is interpreted as an integer starting from 1 indicating the section number to be displayed. -1 means display from the top (by convention, the contents page).