by John P Scott

Advanced Windows Help Topics

Windows help however provides the capabilities to expand into areas such as multimedia, intelligent documents and computer based training. To produce such a system is simply a matter of incorporating the more advanced help features into the design process.

In order to give a flavour of how Help can be expanded we need to look at the more advanced features. These include: The Help Project file; Structured bitmaps; Secondary Windows; Macros and MCI functions.

[OPTIONS]

A title option allows you to specify a caption for the Main Help Window.
e.g. TITLE="My Recipe Book"

[WINDOWS]

This section lists the properties required of the main Help Window as well as listing properties for secondary windows which may be required in the system. Normally WINHELP starts up with the same Window properties as the last usage. However, it may be desirable to fix the size of the Help Window so that it always appears at the optimum size for your particular needs. Secondary Windows can be used (although only one secondary window can be active at any one time) for the display of ancillary information independent of the current help topic. These will also be defined in this section. The format for the window definition statements is:

type = "caption", (x, y, width, height), sizing, (clientRBG), (nonscrollRGB)

The caption, if supplied, supersedes the title in the options section sizing takes the value 0 for normal window display and 1 for maximised. clientRGB and nonscrollRGB are numeric triples specifying the colours of the client window background and the non scrolling regions respectively.

The main help window is always called Main. You may choose any names and captions for your secondary windows.

Examples:

    Main= ,(100,100,400,300),0
    Win1="Secondary Window Win1", (10,50,850,750), 0,(128,128,128), (192,192,192)
    Win2="Secondary Window Win2", (25,25, 300,300), 1

[CONFIG]

This section can be used for many purposes by listing macros which will be executed when the help file is first loaded by WINHELP.

Macros can be used to modify the buttons on the main help window, modify the menu, execute other Windows programs and call functions from Windows libraries plus many other features. The complete list is available in the Help reference Help file on the network.

---

Structured Bitmaps
A structured bitmap is created using the Microsoft Hotspot Editor.

It consists of a compressed bitmap with additional information identifying areas of the bitmap as hotspots and coding the appropriate actions (jump, pop-up or macro) when the hotspots are selected in Windows Help. The source graphic for the Hotspot Editor can be a bitmap of a Windows metafile. The resulting structured bitmap has the .SHG extension. The hotspot editor is straightforward to use. Hotspots can be created by dragging a rectangle on the graphic image and double clicking it to allow its actions to be edited. The on-line help is informative and makes use of structured bitmaps to allow explanation of the various dialogs in the system.

---

Secondary Windows
A secondary window is simply an additional window which can be used to display a help topic independently of the main help window. A secondary Window is created using an extension to the syntax for a topic jump. The help context identifier for the topic is suffixed by the symbol ‘>‘ and the name of the secondary Window as identified in the [WINDOWS] section.

e.g. Secondary WindowhcNewWind>Win2

This will cause the hotspot ‘Secondary Window’ to create a secondary window whose identification is Win2 in the [WINDOWS] section of the project file.

Secondary Windows have no buttons by default.

---

Macros
Macros were touched upon in the [CONFIG] section above. This section will give a few examples of their use.

Macros can be combined by separating them by ‘;’ characters and so a single string can perform a set of related macros. A macro string should be no more than 512 characters and so use the short form for a macro if one exists.

A macro can be also be executed when a topic is opened. This is done by placing a ‘!’ footnote at the start of the topic. The macro string is typed in as the footnote text, in much the same way as a keyword string. There may be more than one ‘!’ footnote in a topic, thus allowing a topic to action a list of macros.

A macro can also be added to a hotspot. This is done by placing a hidden text macro sequence including an initial ‘!’ character immediately after the double underline hotspot reference. Selecting the hotspot causes the macro to be executed.

Brief macro list

Back()

Displays the previous topic in the History list, and is equivalent to the user selecting the Back Button

BrowseButtons()

Adds browse buttons to the main help window

CreateButton(buttonId,name,macro)

Adds a button on the main help window. buttonId is a string used internally to identify the button. name is the text which will appear on the button, and macro is a string of macros which will be executed when the button is pressed

ExecProgram(command-line,display-state)
abbreviation EP

Executes the Windows application specified in the command-line using the supplied parameters in command-line. The application will be run normally if display- state is 0, minimised if 1 and maximised if 2.

PositionWindow(X,Y,Width,Height,State,Name)
abbreviation PW

Sets the size and position of the Window Name using the parameters X, Y, Width, Height and State. The parameters are the same as those in the [WINDOWS] section.

RegisterRoutine(lib-name,func-name,format-spec)
abbreviation RR

The function whose name is func-name in the Windows library lib-name is registered so that it can be used as if it were a macro. The parameters to this function are specified in format-spec. Details of this are in the Help authoring help system on the network.

The above gives just a flavour of the power of the macro system. When used in conjunction with other Windows programs and Windows libraries the system can be extended considerably. The following section gives an example of this.

---

MCI Functions
The Windows Media Control Interface (MCI) allows applications, including Windows Help, to control multimedia devices such as Audio CD’s, Midi Sequencers, Wave devices, Video and Animation. MCI is a complex area and so it will only be touched on in this section as a demonstration of how Windows Help can be used to create more sophisticated Help than just Hypertext and Hypergraphics.

The Windows Multimedia Library, MMSYSTEM.DLL, contains a function called mciSendString which can send command strings to any of the media playing (and recording) hardware in your system. The basic command strings are open, play and close although other commands can be used for more specialised functions. The commands may differ between devices, although there is a degree of consistency in the three basic commands.

To allow your help system to make use of multimedia you need to register the function mciSendString. This is done by placing the following macro in the [CONFIG] section of the help project file:

    RegisterRoutine("MMSYSTEM.DLL", "mciSendString", "Suuu")

The following macro strings will allow sounds and animations to be played, if you have the appropriate hardware.

CD Audio
(requires a CD-ROM drive)

This macro opens the CD Audio device, sets measurements to tracks and plays track 6 of the CD. The CD device is then closed. To stop the CD playing before the selection is complete send the string "stop cdaudio", before the "close cdaudio" command.

    mciSendString("open cdaudio",0,0,0);
    mciSendString("set cdaudio time format tmsf",0,0,0);
	 mciSendString("play cdaudio from 6 to 7",0,0,0);
    mciSendString("close cdaudio",0,0,0)

Wave device
(requires Sound card with Windows driver)

Substitute the name of the .WAV file you wish to play. The second macro causes the sound to complete playing before closing. Remove the word ‘wait’ and place the ‘close sound’ macro in another place to allow the sound to be played and closed asynchronously.

    mciSendString("open path\name.wav alias sound",0,0,0);
    mciSendString("play sound from 0 wait",0,0,0);
    mciSendString("close sound",0,0,0)

Video playback
(requires Video driver, e.g. MS Video for Windows)

Substitute the name of the .AVI file you wish to play. Like the wave file commands you can use them asynchronously by removing ‘wait’ and placing the ‘close video’ command in another place.

    mciSendString("open path\name.avi type avivideo alias video",0,0,0);
    mciSendString("put video",0,0,0);
    mciSendString("play video wait",0,0,0);
    mciSendString("close video",0,0,0)

Midi file playback
(requires Sound card with Midi driver for Windows)

Same rules apply as for the sound (.WAV) file and the video file.

    mciSendString("open path\name.mid type sequencer alias sound",0,0,0);
    mciSendString("set sound time format ms",0,0,0);
    mciSendString("play sound from 0",0,0,0);
    mciSendString("close sound",0,0,0)

The format of the MCI commands are only briefly hinted at in the above examples. A complete description of all the MCI strings can be found in the MCI Help reference on the network. A demonstration help file HELP.HLP together with its source and media files are available for download MMHELP.ZIP.

---

Exercises

1.

Amend the BITMAPS.HLP system from the help tutorial directory to include structured bitmaps linked to pop-up definitions of the contents in the images. Call your files SHG.RTF, SHG.DOC and SHG.HPJ.

2.

Add secondary Windows to the help file from question 1 to display the ingredients for each recipe, adding a button in the main window called ‘ingredients’ for each topic which needs it. Call your files SECWIND.RTF, .DOC, .HPJ

3.

Add start-up macro to the result of question 2 to set up the main Window Size.

4.

If you have access to multimedia devices incorporate sound and images for your help system. These may not be correct (i.e. the sounds and images may not be in the right context) but you should try to plan the sound and images you would need in a real system to enhance the product (e.g. Spoken methods stored as .WAV files can be easily produced using the Windows Sound Recorder, if you have a sound card and microphone.)

---

Copyright (C) 1995

JPS Graphics, 30 Adder Hill, Great Boughton,CHESTER, CH3 5RA, UK
All rights reserved

Comments to author: fcg@jpsgraph.demon.co.uk 

URL: HTTP://194.80.193.185/fcg/help/advhelp.htm

---