Contents
Welcome to WinHelp Demo 95

An In-depth Demonstration of WinHelp 95 Features

Created using Help Magician Pro 95

  	Introduction

 	Types of Help Topics

 	Basic Elements of Windows Help

 	Advanced Windows 95 Help


Introduction

This demonstration file was created to show you many concepts relating to Windows Help including:

 	Various design ideas for Help Topics

 	Basic elements of Windows help including help windows, non-scrolling regions, formatting help text, formatting paragraphs, hypertext links, graphics, multimedia audio and video, browse sequences, and more

 	Advanced elements of Windows Help including macro programming, standard and customized buttons, authorable buttons, shortcut buttons, and more

We include this demonstration file and its source file (demo95.hlx) with Help Magician Pro 95 in the directory \DEMO95.  Feel free to disect this file within Help Magician to learn how some of these ideas are implemented.


Types of Help Topics

As a help author, there are many ways that you can structure your help topics.  Remember that each "page" in Help Magician is a different topic, no matter what it's function is.  You have control over the look and function of each topic page.  You can optionally define which window a topic page will be shown in.  Within each topic page, you can define its title, context id number, context string, and keywords.  Below is a listing of the types of help topics used in help authoring.

Definition Topic	A topic that is the destination of a popup that usually contains a definition of a word.  It could also serve as the definition of a word contained in a glossary.

Glossary	A topic that contains a glossary consisting of a non-scrolling region with buttons a-z and a close button.  The scrolling region contains words in alphabetical order with popup links to other help topics containing the actual definitions.  The glossary topic is usually displayed in its own secondary window.  Help Magician Pro has a glossary wizard that generates a complete glossary template in a few mouse clicks.

What's This? Topic	A topic that has a short description of a dialog box control, toolbar button, or menu item within an application.  Depending how it is programmed, a What's This? help could be invoked by right clicking the mouse on the element of interest and a What's This? command appears.  When the user clicks on the What's This? command, a unique context id number is passed from the application to WinHelp.  WinHelp displays the help topic in a small popup window.

Procedure Topic	Procedure Topics are the most prevalent form of help. They serve the central role in documentation: explaining the purpose of tasks, how to carry them out, and what the special issues are.  They may contain a topic heading, a descriptive conceptual paragraph, a subheading, the steps to carry out a specific task, and additional notes.

Command Topic	A Command Topic provides a functional description of a command and its dialog box elements.  It is similar to What's This? except it provides help for all the elements of a dialog box on one topic page.  A Command Topic could be displayed when the user hits the F1 key while inside a dialog box, or by pressing a Help button in a dialog box.  The link from the application to the Command Topic is usually done through the Context ID number passed to WinHelp.

List Topic	A List Topic basically contains a list of jumps to other Help topics.  Many help systems use List Topics as a form of navigation.  Some List Topics contain a paragraph above the list of jumps, hence they are hybrids of Overview and List Topics.  By indenting List Topics, it is possible to show a hierarchy within a help system.

Overview Topic	An Overview Topic is a type of topic that explains conceptual knowledge about a specific task or group of procedural topics.  It may contain a jump to another topic showing an example of a concept.

Screen Region Topic	A Screen Region Topic consists mainly of a graphic of a major interface element such as an application's main workspace, a tool palette, a dialog box, or a toolbar. Typically, this graphic is composed of multiple hotspots, each of which, when clicked, displays a pop-up that identifies and explains a particular command button, check box, or other similar interface element on the major one.  By using a Screen Region Topic, hotspots on each of the main menu elements, and picture of each of the menu options on a separate popup topic page, it is possible to simulate a menu being pulled down on a main window, with help for each of the menu elements.

Keyboard Shortcut Topic	A Keyboard Shortcut Topic is a topic that contains a list of keyboard shortcuts for specific tasks associated with an application.  Shortcut Topics can be organized into function groups, depending on the complexity and number of keyboard shortcuts.

Error Message Topic	When error-message topics are included in Help, they generally supplement the system messages that appear in message boxes within the application's interface.  An application would generate a messagebox containing an error message, an OK button, and a Help button.

Troubleshooting Topics	Troubleshooting Topics lead the user through a set of diagnostic and/or recommendation topics to help the user through a troubleshooting situation.  The topic may start out with a general diagnostic, lead to a specific diagnostic, then finally to a recommendation or hints/suggestions to resolve the problem.


Definition Topic

This example shows that a definition of a word can be shown in a popup window.  The glossary topic in this file sends all definitions here.


Glossary

A

A word

Another word

B

B word

C

C word

D

D word

E

F

G

H

I

J

K

L

M

N

O

P

Q

R

S

T

U

V

W

X

Y

Z


What's This? Topic

What's This? topics are displayed in a small popup window similar to this one.


Basic Elements of Windows Help

This section will familiarize you with the basic elements of Windows Help.  Click on the section you want to know more about.

 	Help Windows - Where do you want to display your help topics

 	Screen Layout - Formatting ideas for your help topics

 	Hypertext Links - Creating links between topics

 	Graphics - Adding pictures to your help topics

 	Multimedia - Adding sound and video to your help topics

 	Browse Sequences - Creating relationships between help topics


Help Windows

Main Windows	Many of the help topics displayed in WinHelp goes into the main window.  The main window is the window that you see this text displayed in.  There can be only one main window in Windows Help.  The main window has the menus (File, Edit, Bookmark, Options, and Help) and beneath them, a button toolbar.  The toolbar normally features the Help Topics, Back, Print, and Browse command buttons.  You cannot delete items in the menus, but you can add items to them using macros.  You can configure the button toolbar quite easily with the Help Magician, without any macro programming.  You have control over the size and placement of the main window.  The "Help Windows" text above is contained in a non-scrolling region and this text is in a scrolling region.

Secondary Windows	Secondary windows are used to augment the main window.  They can also be used by themselves when showing training card help or other specific tasks.  They can contain a button toolbar, fully programmable by the help author.  A secondary window can even be automatically "sized to fit" the length of its topic.  Like the main window, secondary windows can contain non-scrolling regions, graphics, multimedia, and hypertext links to other topics.  You have control over the size and placement of secondary windows.  Up to 255 secondary windows can be defined, and out of them, up to 9 can be displayed simultaneously.  Click on the different examples of secondary windows below.

Secondary window without a button bar

Secondary window with a button bar

Secondary window set for automatically sizing to fit topic

Secondary window that plays a .wav file when displayed

Popup Windows	Pop-up windows are used extensively for word definitions, lists of related topics with hypertext jumps, or other text, where the main or secondary windows would be overkill.  Popup windows do not have menus, button toolbar, or scrolling regions.  They can contain graphics or hypertext links to other topics or multimedia.  You have no control over the size and placement of popup windows.   Click on this text to see a popup window.

Help Magician Pro 95 allows you to visually create your windows.  If you are currently viewing the help source of this file under Help Magician Pro 95, click on Options...Windows to see the list of defined windows for this demo.


Screen Layout

This section will show you a few ideas on how you can make your help screen layout more visually appealing.   WinHelp provides many methods of organizing your help screens.  Some of these methods are discussed below.

Non-Scrolling Regions

Formatting Text

Special Characters

Formatting Paragraphs, Bullets, and Borders

Horizontal Rules

How to Include Math and Scientific Formulas


Hypertext Links

WinHelp and Help Magician Pro 95 support many types of hypertext links.  Hypertext links (or "hotspots") are what allows you to move from one topic to another or run a WinHelp macro.  Hotspots may appear within text or be sectioned off within a graphic.  The mouse cursor typically changes to a hand when the user moves the cursor over a hotspot.  Within a hotspot definition, you can optionally specify which window the destination topic will appear in.  The different types of hotspots are demonstrated below.

 	Jump to Another Topic - The simplest form of link to another topic within the same help file.

 	Jump to Another Help File - This type of link allows you to display a topic in another help file.  You specify which help file and what its context id number is.  Click on this hotspot to see the help for Windows 95.

 	Jump to a Mid-Topic - With Mid-Topic jumps, it's possible to link to an "anchor" point within a specified topic (such as a glossary).

 	Jump to a Keyword - The Jump to Keyword link will allow a user to jump to a topic containing the specified keyword.  If more than one topic contains the keyword, then a list of topics will appear and the user can select which topic to jump to.

 	Jump to a Macro - When the user clicks on a hotspot containing this type of jump, a predefined WinHelp macro is executed.  Macros allow you to run other programs, play multimedia, create buttons that run other macros, create menu items, etc.  Clicking on this example will run the calculator in Windows 95.

 	Popups - Popup hotspots cause the destination topic to appear in a small popup window near the hotspot.  Popups are frequently used for definitions, as well as "About" boxes.  Popup windows can contain text, graphics, and hotspots.


Graphics

Putting graphics into your help files adds a new dimension to displaying your help file.  However, graphics will use memory.  You should decide on what kind of graphic you want in your help topic.  16-color graphics will work across all video display systems and provides the most compatability and uses the least amount of memory.  256-color graphics are good for showing photo-quality images.  However, 256-color images take up twice the memory as the same size 16-color image.  256-color images will not display properly with systems that can only display 16 colors (standard VGA mode). Most systems today have the capability of displaying 256-color images.   Higher resolution color images (more than 256-color) take even more memory and probably will not be displayable on most systems.

 	File Formats - WinHelp supports primarily .bmp and .wmf images.  Help Magician Pro 95 reads other image formats (.tif, .tga, .pcx, .gif, .bmp, .ico, .wmf) and converts them to the WinHelp suitable format.

 	Static Graphics - Regular bitmaps (or metafiles) that are displayed with character alignment, left alignment, or right alignment.

 	Hotspot Graphics - These types of graphics contain hotspots.  The hotspot may cover the entire graphic or a portion of the graphic.  Use the SHED.EXE editor to make SHG files with hotspots from bitmaps.

 	Pre-defined Bitmaps - A set of predefined WinHelp bitmaps that you have at your disposal.

 	Transparent Bitmaps - A 16-color bitmap in which WinHelp replaces the white pixels with the color of the bacground of the current Help window.  They are commonly used to displaying images that aren't rectangular against a colored window background.

 	Bleeding Graphics - A method by which you can display a bitmap in a WinHelp window without the eight-pixel left margin.


Multimedia

You can include many different multimedia elements within your help system.  They may be played when the help file first starts up, when a topic is about to be displayed, or when a user clicks on a hotspot.  Help Magician makes it easy for you to insert multimedia elements into your help.  You do not need to learn macro programming.  It takes care of that for you.

Click on each element below for a demonstration.

Sound - Plays .wav files using the standard Windows multimedia drivers on your PC.

Animation - Plays .mmm files, although this format is not used much these days.

Video - Plays .avi files in a small window that appears on top of WinHelp.  AVI files can contain video clips or screen animation.  This option doesn't work in this demo because we needed to make this file smaller for web distribution.   It is available on the demo CDROM and the distribution version.

Embedded Video - A Windows 95 feature that plays .avi files within a WinHelp window.


Browse Sequences

Browse Sequences are used to define groups of help topics that are related to each other.  When browse sequences have been defined, WinHelp will show the << (previous) and >> (next) buttons.  The user can click on these buttons to move forward or backward within a browse group and view those related topics in the group.

For example, you might have a hypertext file containing creatures of the world.  One browse sequence could contain a group of topics that show all the species of mammals, another could show all the birds, and another could show all the fish.  In this example, you could define the mammals in alphabetical order within the browse group.

It is up to the help author to determine how the help topics will be grouped together in a browse group.  Help Magician makes it easy to define browse groups and re-order topics in that group.  It will also generate the necessary macro to show the browse buttons.

This topic is the first of three topics that have been defined in a hypothetical browse group.  The other two topics are other help topics that appear in this file (the "area" topics for the hotspot graphics demo).  You can see how this sample browse sequence has been defined by selecting Links...Browse Sequences from Help Magician's menu.


Advanced Windows 95 Help

This section shows you more advanced features of Windows 95 Help.  Click on the area you want more info on.

 	Macro Programming

 	Buttons


Macro Programming

Macro programming for WinHelp can be technically demanding, depending on what you want to do.  Here we'll show you a few common uses for WinHelp macros.  This section is not meant as a full tutorial on macro programming.  Help Magician Pro 95's macro editor can make programming macros easier.

Controlling When WinHelp Macros Get Executed

Project Level - A macro will get executed when the Help file is first shown.  We use a project level macro to initialize DLLs, the Stop Sound button, and to play an opening theme for this demo.

Topic Level - A macro will get executed just before a topic is shown.

Hotspot Level - A macro will get executed when a user clicks on a hotspot.

Window Level - A macro will get executed just before a specific window is shown.

Keyword Level - A macro will get executed when a user selects a keyword from the Index Tab in the Help Topics browser.

Samples

Running External Programs from within your Help file - This example runs the Windows 95 Calculator program.

Running an aplet from the Control Panel - This sample runs the ControlPanel macro that tells Windows to show the display settings for the screen saver.

Checking to see if a file exists - This sample checks to see if the calc.exe program exists.  If it does, it is run, else a popup topic appears telling that the application doesn't exist.

Popping up a messagebox - This sample pops up a messagebox, by calling an API routine in Windows.


Buttons

WinHelp supports many types of buttons.  The Standard and Customized buttons appear in the WinHelp Bar within a WinHelp main or secondary window.  The Authorable Buttons appear inside a help topic and will animate when clicked on.  Shortcut buttons show a "shortcut arrow" button and run an application.  The shortcut button macro is similar to the ExecFile macro, except that in addition to running an application it can also pass standard WM_COMMAND messages to a Windows application.

You define which WinHelp macros to execute when a button is pressed.

Below is a sample of different kinds of buttons.

Standard - Standard buttons can be defined in the WinHelp bar and can include the Contents, Index, Find, Help Topics, Print, Back, Options, and Browse buttons.

Customized - Custom buttons can include any text you want and can be made to run any WinHelp macro.  You must define at least one standard button before a custom button.  This example shows a secondary window containing a Calculator Button which runs the ExecCalc macro, showing the calculator.

Authorable Buttons - Click on this [image] to run the calculator program.

Buttons in Secondary Windows - Both standard and customized buttons can be defined for secondary windows.  The examples above do place the buttons in a secondary window.

Shortcut Buttons - These buttons usually appear in "How To" topics and they help the user accomplish their task.   Click here  [image]  to see a shortcut demo (that copies this help topic's text to the clipboard, runs WordPad, and pastes the text into WordPad).


Popup Example
  This is an example of a popup window with a graphic.


Secondary Window without button bar
This is a simple secondary window without a button bar.  It does not have a non-scrolling region defined.


Secondary Window with a Button Bar

This window is a secondary window that contains a fully functional button bar.  The button bar can contain standard buttons or custom buttons that will run WinHelp macros when pressed.


SecWinSizing
Non-Scrolling Region

Depending on how you set up the windows, you can have the window to automatically resize itself to accomodate the text appearing in it.  The following text is just text to take up space.

"Filler text"

Many of the help topics displayed in WinHelp goes into the main window.  The main window is the window that you see this text displayed in.  There can be only one main window in Windows Help.  The main window has the menus (File, Edit, Bookmark, Options, and Help) and beneath them, a button toolbar.  The toolbar normally features the Help Topics, Back, Print, and Browse command buttons.  You cannot delete items in the menus, but you can add items to them using macros.  You can configure the button toolbar quite easily with the Help Magician, without any macro programming.  You have control over the size and placement of the main window.  The "Help Windows" text above is contained in a non-scrolling region and this text is in a scrolling region.


Secondary window that plays a wav file when displayed

When this topic is displayed, a sound clip is played.  This is accomplished by defining a multimedia element within Help Magician and attaching it to a topic.  Help Magician does the work of creating the necessary project and topic macros to play the sound.  In this example, Help Magician created the macro definition Play_SPACE.WAV_000 which contained the sndPlaySound("space.wav",1) macro.  The 1 parameter forces return to WinHelp immediately following the macro call (the sound is played in the background).  If this parameter was a 0, the sound would have to be fully played before control is returned to WinHelp.


NonScrolling Regions
 Non-Scrolling Region Area

 Scrolling Region Area

Non-scrolling regions is an area of a help window that stays in place, even though help text beneath the area can scroll vertically.  Non-scrolling regions can contain text, graphics, or anything that the scrolling area can contain.  Typically, a non-scrolling region can contain a Topic Header, a company logo/information, or anything else that you might want to remain stationary for the duration of the display of a single topic.

Help Magician Pro 95 fully supports WYSIWYG non-scrolling regions and you can instantly switch between the non-scrolling region and the scrolling region for editing.


Formatting Text

You can format text just about any way you like in WinHelp.  WinHelp supports different styles of fonts, font attributes, and font colors.  Keep in mind that if you use a unique font on your system, the target system must also have the same font installed, otherwise Windows will try to do a font substitution and the results may not be what you want.  If you are developing a help file that will be seen by a wide audience, it's best to stick with the common fonts supplied with Windows (such as MS Sans Serif, Arial, Symbol, etc.).  When you are making a jump or popup within Help Magician, do not add your own green underline to the text; Help Magician will do it for you.

This is normal text.

This is bold text.

This is italic text.

This is bold italic text.

This text has a different color.

This text is larger than above.

This text is smaller than above.

This text contains a mixture of bigness and colors within the same line of text.

This text contains a different font.


Special Characters

WinHelp and Help Magician Pro 95 has the capability of displaying special characters including European character sets.  You can use these special characters to add trademarks and copyright symbols to your text.  Here is some of the symbols that are supported by WinHelp and are directly insertable within Help Magician Pro 95.

α    β     φ     ♣     ♥    ♦     ♠     ↔     ←     ↑     →     ↓     •     ⊗     ®     ©      ™


Formatting Paragraphs

WinHelp and Help Magician Pro support a variety of paragraph formatting options.  Within Help Magician Pro 95, you can create paragraph styles and apply these styles to paragraphs.  If you made changes to the style, Help Magician Pro would update all paragraphs using the modified style.   Below are some examples of Paragraph Formatting options.

Text Alignment - Make text left, centered, or right aligned

This text is left aligned

This text is centered.

This text is right aligned.

Line Spacing - you can control the amount of spacing that will be appearing between paragraphs.

This line of text is spaced 1.5 lines before the next line

Next line

Indents - Easy to do in Help Magician by using the Ruler Bar.

It's easy!	Indented text allows for visually appealing paragraphs, columns of text, definitions, etc.  Create hanging indents visually by moving the lower marker on the Ruler Bar.  This paragraph is setup as a hanging indent.  A tab character separates the first column with the rest of the hanging indented paragraph.

Bullets - WinHelp and Help Magician support bulleted lists like the one below...

♥	Item #1

♥	Item #2

♥	Item #3

Borders - Highlight one or more special paragraphs with a border around it.  WinHelp supports many types of borders.

Line Above

Line Below

Line on the Left

Line on the Right

Single Box

Double Box

Thick Box

Shadowed Box - set the right margin to force a smaller box

Bold Text in Box
Put a box around two paragraphs by highlighting both paragraphs and selecting the box.  You can even indent the box

This is another paragraph.

Tabs & Columns - Tabs and columns make it easier to organize your data.  Make sure that the text in one column does not get too close to the text in another column- any font differences between systems could cause the text in that column to move to the next column.

By using right-aligned tabs, you can make numerical data line up properly as in the following example (notice the box around the data and the larger size heading):

3-Month Avg Stock Prices

Stock	Jan	Feb	Mar

IBM	98.50	99.50	101.25

MSFT	79.75	92.00	104.50

IOMG	14.00	18.75	25.00


Horizontal Rules

Horizontal Rules can be used to separate major sections within one page.  They are commonly used in Internet Web publishing.  Add a horiztonal rule with one mouse click in Help Magician Pro 95....

The above line is a sample of a horizontal rule.

You can also use a bitmap for a horizontal rule, however the disadvantage is that it will not resize when the window is resized...

The line above is a bitmap horizontal rule.


How to Include Math and Scientific Formulas

WinHelp does not have the capability of directly handling special math symbols, superscripted, and subscripted fonts.  One way of getting your formulas into WinHelp is by first converting them into a bitmap and then inserting that bitmap into your text, as in the following example.


JumpKeywordOne
Jump to Keyword #1

This page #1 is the destination topic of the Jump to Keyword example.


JumpKeywordTwo
Jump to Keyword #2

This page #2 is the destination topic of the Jump to Keyword example.


JumpAnotherTopic
Jump to Another Topic

This is the destination topic for the Jump to Another Topic example.


MidTopic
MidTopic Jump Example

This example shows the destination topic of the Mid-Topic Jump example.

some text

more text

even more text which shouldn't be shown initially.

Here is where the mid topic jump will be shown.  Notice the # in the Help Magician editor which means a midtopic jump anchor point.  You can scroll back to see the previous text in this topic.


Static Graphics

Static graphics are normal graphics that do not contain hotspots.

The character-aligned option allows you to place a bitmap [image]  within the text.

 The left-aligned option places the bitmap on the left, with text wrapping around it on the right.

 The right-aligned option places the bitmap on the right, with the text wrapping around it on the left.

16-color image

256-color image

24-bit color (not fully displayable on all systems)


Transparent Bitmaps

The transparent bitmap option in WinHelp only works for 16-color images.

Regular Bitmap

Transparent Bitmap


Bleeding Graphics

Here is an example of a bleeding graphic.

Here is an example of a normal graphic (with no negative indent settings).


Pre-defined Bitmaps

Here is a list of all the standard pre-defined bitmaps for WinHelp 95.  You can easily insert any one of these bitmaps from the Insert...Pre-defined Bitmap option from Help Magician's menu.


HotSpot Graphics

Here is an example of a hotspot graphic.  As you move the mouse over a hotspot on the graphic, the cursor changes to a hand.  Clicking on a defined area within the bitmap will bring up different help topics.  You define which area is "hot" and which topic (by its context string) it belongs to by using the SHED editor.  You can run the shed editor within Help Magician from the tools menu.


Area1
This is area 1 of the hotspot graphic.  It has been defined as a jump.


Area2
This is area 2 of the hotspot graphic and it has been defined as a popup.


Custom Button Demo

This demo shows a calculator button defined in a secondary window.  Click on the button to run the calculator.


Standard Button Demo

This topic shows a secondary window with some standard buttons defined.


calc not installed

Can't run calculator application - It is not installed on your system.


Embedded Video

This is an example of a topic containing an embedded video.  You can include AVI files within your help topics, without any macro programming!

Note:  This option doesn't work in this demo because we needed to make this file smaller for web distribution.  It is available on the demo CDROM and the distribution version.