Copyright: Herd Software Development 1995-96


The ThinHelp wish list
The ThinHelp wish list and survey

ThinHelp was developed to solve a lot of Help and Viewer authoring problems and provide a new range of creative opportunities for authors.  But it is capable of much, much more.  In order to release this software within a reasonable timeframe and allow you the ability to work with it, certain design decisions had to be made and a number of our “what if” ideas simply didn’t make it into the final release.

There are also features on our “to-do list” which you may want even more than the features you already have.  Here’s your chance to let us know.  Just fill out and fax, mail or email this form (the datafile is saved as WISHLIST.TXT in ThinHelp's installation directory) to keep us informed about your authoring needs.

One small reminder...please tell us about your needs, not what you think others might need or what you’d like to see in other authors’ Help and Viewer titles.  If you think something would be a good idea but you wouldn’t use it yourself, please don’t suggest it as a high priority for you.  We want to focus our efforts on developing features that you will use.

Please type continuous lines.  This test version of the HSFORM.DLL forms extension does not yet support carriage return characters.  Feel free to develop an ongoing list of ideas and suggestions.  You can load, edit and save your “wish list” as often as you like.

What feature did you like most about ThinHelp?

What did you like least?

What feature did you find the most difficult to understand?

What feature did you find the most difficult to apply in your authoring?

Were there features which were important to you which you felt were “buried” in the Help?  If so, which features were they?

Have you discovered any problem or incompatibility with ThinHelp that you felt made it unusable for one of your Help or Viewer projects?  (Please specify.)

Which help authoring software do you use (i.e. a text editor, Word, ForeHelp, other WYSIWYG tool/word processor)?

Which destination platforms and Windows versions do you work with most (i.e. Windows 95, Windows NT, Windows 3.1x, Multimedia Viewer, MediaView, etc.)

Have you discovered situations where neither HelpDebug or the Help compiler didn’t detect an error in your Help?  If so, can you tell us what kind of error it was?

Would HelpDebug be of more use to you as a stand-alone utility rather than a component of Push?

Have you found any areas where HelpDebug did not provide the kind of information you needed about your project?  If so, please specify what sort of information you would like to see in a HelpDebug report.

Are you unsatisfied with the results of compressing .SHG files with LZH?  Would you use HelpDebug to convert an entire existing Help project to ThinHelp embedded windows if it took a little longer and produced a slightly smaller file size?

We included a demo of pane technology in Help with this release of ThinHelp.  Did you find this interesting enough to want to know how to use this in your own Help projects, even though there is a fair bit of work involved in developing a paned topic?

Would you be interested in participating in a ThinHelp Users’ Group on the Internet  or Compuserve?  If yes, would you be interested in making demo helpfiles of your unique applications of ThinHelp available for other users to download and study?(If so, specify your preference.)

Would you use custom animation sequences even if they ran a little slower than normal animations, to -- for example -- run an animation sequence in reverse?

Would you use transparent animations that behaved like transparent GIFs on the World Wide Web, meaning that every frame of the animation could have its own transparent regions, if they ran a little slower than normal animations?

If Push had the ability to define visible hotspots, would you use them?

Would you be more interested in using visible hotspots if you could assign text captions to them on the bitmap, much the way borders around sections of dialog boxes have text captions?

ThinHelp’s license key technology is based on elapsed time since the installation of the software.  An additional form of dating technology could also be implemented, based instead on the actual date recorded on the end user’s system calendar.  If ThinHelp could provide true date checking as well as elapsed-time dating, would you make use of this feature?

You’ve seen the author-definable buttons supplied by ThinHelp.  Would you use these buttons more if you could assign variables to them, so that they would appear to be constantly depressed when the user was browsing a specific topic?

Are you able (or proud enough) to supply a CompuServe or AOL download location or an Internet URL where others can view your discoveries and creations?

Here's a list of potential enhancements which could be added to ThinHelp in future versions.  On a scale of 1 to 11 (we know how emotional Help authors can be sometimes), please rate these in order of importance and urgency to you:

 Metafile-based SHG graphics in PUSH

 “Balloon help” or “Tool Tips help”...the ability to automatically display a popup topic if the user holds the mouse button over a hotspot for two seconds or longer

 Automated or conversion of ThinHelp-based Help projects to HTML

 Helpfile encryption on a high security standard.

 A function to test if a given topic ID exists in a helpfile, useable both from an application and a help file.

 TWAIN scanner interfacing in Push

 An embedded window editor utility for allowing point-and-click editing of embedded window (and possibly THWaterMark() and THMoveWindow() macro) strings.

 An enhanced compression technology for digital sound files which would allow for much higher compression rates than achievable using LZH-compressed .WAV files

 Watermarks and background color control for the non scrollable region

 A point-and-click setup workshop for assisting you in the creation of self-extracting, self-starting .EXE installation archives for your projects.

 SHG import filtering for 32 bit applications

 SHG export filtering

And finally, having seen what ThinHelp can do, is there anything you’d like to see in future versions of ThinHelp that we haven’t mentioned here?  We’re especially interested in knowing what sorts of macros and special functions you might find useful, considering that ThinHelp will be able to provide these functions in both 16 bit and 32 bit projects.


THINHELP.HLP main menu
Main menu

  Features: ThinHelp overview

  ThinHelp online guide and tutorial

  Online help for Push

  Online help for ThinHelp's ForeHelp interface

  Technical reference

  Quick reference

  Troubleshooting ThinHelp

  ThinHelp  demos  and authoring ideas

  Catalog, licensing and ordering info

THNHLP,THIN,!ANICONS.LZH;world;0/0/0/150/255/0/255}
ThinHelp is copyright 1996 Herd Software Development
WWW: http://members.aol.com/herdsoft/index.htm
See Licensing, Prices and Ordering.

Every bitmap in this help system is displayed using ThinHelp’s high-speed
optimized-redraw technology.  LHA.EXE is copyright 1992,1996 by Yoshi.


ThinHelp Help contents

 Features: ThinHelp overview

 ThinHelp online guide and tutorial

 Online help for Push

 Online help for ThinHelp's ForeHelp interface

 ThinHelp technical reference

 Quick reference

 Troubleshooting ThinHelp

 ThinHelp demos and authoring ideas

 Catalog, licensing and ordering info

 Appendices and documentation updates


ThinHelp Help contents

 Features: ThinHelp overview

 ThinHelp online guide and tutorial

 Basic ThinHelp embedded window functions

 Hotspots, macros, buttons and transparencies

 Watermarks (textures), animation and WAV audio

 Miscellaneous functions

 Utilities and extras

 Online help for Push

 Online help for ThinHelp's ForeHelp interface

 ThinHelp technical reference

 Quick reference

 Troubleshooting ThinHelp

 ThinHelp demos and authoring ideas

 Catalog, licensing and ordering info

 Appendices and documentation updates


ThinHelp Help contents

 Features: ThinHelp overview

 ThinHelp online guide and tutorial

 Basic ThinHelp embedded window functions

  Getting started: how does ThinHelp handle bitmaps?

  Adding bitmaps to ThinHelp projects

  Referencing bitmaps or archives in ThinHelp project files

  Referencing bitmaps in RTF source documents

  Working with dynamic graphics libraries

  Compiling and testing with ThinHelp

 Hotspots, macros, buttons and transparencies

 Watermarks (textures), animation and WAV audio

 Miscellaneous functions

 Utilities and extras

 Online help for Push

 Online help for ThinHelp's ForeHelp interface

 ThinHelp technical reference

 Quick reference

 Troubleshooting ThinHelp

 ThinHelp demos and authoring ideas

 Catalog, licensing and ordering info

 Appendices and documentation updates


ThinHelp Help contents

 Features: ThinHelp overview

 ThinHelp online guide and tutorial

 Basic ThinHelp embedded window functions

 Hotspots, macros, buttons and transparencies

 Adding hotspots to ThinHelp bitmaps (loads PUSH.HLP)

  Working with SHGs in ThinHelp embedded windows

  Adding macros to ThinHelp bitmaps

  Creating embedded-window buttons

  About transparent bitmaps in WinHelp

  Transparent bitmaps GIF-style” (index-based)

  Transparent bitmaps using masks

 Watermarks (textures), animation and WAV audio

 Miscellaneous functions

 Utilities and extras

 Online help for Push

 Online help for ThinHelp's ForeHelp interface

 ThinHelp technical reference

 Quick reference

 Troubleshooting ThinHelp

 ThinHelp demos and authoring ideas

 Catalog, licensing and ordering info

 Appendices and documentation updates


ThinHelp Help contents

 Features: ThinHelp overview

 ThinHelp online guide and tutorial

 Basic ThinHelp embedded window functions

 Hotspots, macros, buttons and transparencies

 Watermarks (textures), animation and WAV audio

  Watermarks and background textures

  Creating animations with ThinHelp

  Animation: advanced techniques and parameter reference

  Developing slide shows

  Compressed WAV audio support

 Miscellaneous functions

 Utilities and extras

 Online help for Push

 Online help for ThinHelp's ForeHelp interface

 ThinHelp technical reference

 Quick reference

 Troubleshooting ThinHelp

 ThinHelp demos and authoring ideas

 Catalog, licensing and ordering info

 Appendices and documentation updates


ThinHelp Help contents

 ThinHelp online guide and tutorial

 Basic ThinHelp embedded window functions

 Hotspots, macros, buttons and transparencies

 Watermarks (textures), animation and WAV audio

 Miscellaneous functions

  Metafiles: overlaying vector graphics on JPEGs and BMPs

  Precision window sizing control with ThinHelp

  Controlling Help’s background colors

  Registry key and serial number technology

  Graphic import filtering with THNHLP.DLL

 Utilities and extras

 Online help for Push

 Online help for ThinHelp's ForeHelp interface

 ThinHelp technical reference

 Quick reference

 Troubleshooting ThinHelp

 ThinHelp demos and authoring ideas

 Catalog, licensing and ordering info

 Appendices and documentation updates


ThinHelp Help contents

 Features: ThinHelp overview

 ThinHelp online guide and tutorial

 Basic ThinHelp embedded window functions

 Hotspots, macros, buttons and transparencies

 Watermarks (textures), animation and WAV audio

 Miscellaneous functions

 Utilities and extras

 HelpDebug for troubleshooting for 16 bit Help projects

  HLPLHA.DLL: compressed baggage and LZH extraction

  Creating installation packages with ASETUP

 Online help for Push

 Online help for ThinHelp's ForeHelp interface

 ThinHelp technical reference

 Quick reference

 Troubleshooting ThinHelp

 ThinHelp demos and authoring ideas

 Catalog, licensing and ordering info

 Appendices and documentation updates


ThinHelp Help contents

 Features: ThinHelp overview

 Online help for Push

 Online help for ThinHelp's ForeHelp interface

 ThinHelp technical reference

 Quick reference

 Troubleshooting ThinHelp

  Contacting us about support for ThinHelp-related problems

  Push or .SEG-related errors

  Troubleshooting the ForeHelp interface

  The selected transparent color will not display transparently

  Topic displays Unable to display bitmap” error or black spot

  Bitmaps or animations in formatted tables won’t display

  Jumping to a topic from a popup displays the wrong background color or watermark

  Statement and macro templates copied from ThinHelp helpfiles won’t paste properly

  Macros won’t work in 32 bit helpfiles

  Hotspots disappear from SHGs displayed as embedded windows

  Macros won’t work in 16 bit helpfiles

  Windows reports ";" Expected

  Macros won’t work properly in watermarks

  ThinHelp causes a GPF on entry to a topic

  Animation frames display out of order

  Watermarks show palette errors when switching windows

  Helpfile shows no WinHelp or Viewer error but does not display bitmap

  Topic window display is taking too long

  Bitmap colors are distorted

  Users’ desktop colors interfere with the look and feel of your helpfile

  Graphic import filtering is no longer available for SHGs

 Troubleshooting ThinHelp

 ThinHelp demos and authoring ideas

 Catalog, licensing and ordering info

 Appendices and documentation updates


ThinHelp Help contents

 Features: ThinHelp overview

 ThinHelp online guide and tutorial

 Online help for Push

 Online help for ThinHelp's ForeHelp interface

 ThinHelp technical reference

 Quick reference

 Troubleshooting ThinHelp

 ThinHelp demos and authoring ideas

 Catalog, licensing and ordering

  Licensing, prices and ordering

  ThinHelp support

  What’s new: updates, features and fixes since JPANI

  The ThinHelp wish list and user survey

 Appendices and documentation updates


ThinHelp Help contents

 Features: ThinHelp overview

 ThinHelp online guide and tutorial

 Online help for Push

 Online help for ThinHelp's ForeHelp interface

  ThinHelp's baggage handling

  File selection from the ForeHelp interface

  ThinHelp display options

  Troubleshooting the ForeHelp interface

 ThinHelp technical reference

 Quick reference

 Troubleshooting ThinHelp

 ThinHelp demos and authoring ideas

 Catalog, licensing and ordering info

 Appendices and documentation updates


  The Herd Software Development catalog


Overlaying vector graphics on JPEGs
Overlaying vector graphics on JPEGs and BMPs

  Solving a JPEG ”bug”

  Transparent bannering

  Adding metafiles to BMPs (and vice versa)

  Using metafiles in animations

  Example

  Step by step

  Notes, issues and tips

Solving a JPEG ”bug”

One of the biggest headaches with JPEGs, especially in a commercial authoring environment, is their difficulty with sharp edges.  JPEG compression tends to soften and blend these edges into the surrounding area.  Text is nothing but sharp edges, and this feature of JPEG compression can turn a carefully-designed text overlay on a JPEG graphic into something that looks like it was glued into place with mucilage.

We recognize the need for greater control over the look of text bannering and labelling in JPEG graphics.  That’s why ThinHelp allows metafiles (WMF-format graphics created in a vector graphics program such as CorelDraw, FormPad or PowerPoint) to be copied to the clipboard and pasted into a .SEG hotspot generated by the PUSH.EXE hypergraphics editor.  Now you can add transparent, resizeable arrows, explanatory text and banners to your JPEGs (and BMPs too) by pasting them into Push hotspots, just like the example ”Flower Power” banner shown in one of the demos.  (This effect is only available using Push’s proprietary .SEG hotspot datafile format.)

You don’t lose the use of the hotspot when you insert metafile graphics into Push hotspots.  You can define the very same hotspot (but only the entire hotspot) as a clickable jump, popup or macro link by double-clicking the hotspot and adding the appropriate attributes.

Transparent bannering

Another useful application of metafiles is the addition of banners to transparent bitmaps, creating an even more ”Web-like” appearance in your helpfile.  Simply create a .SEG file with your metafile embedded in it, and name the saved .SEG so that its name corresponds with the .BMP or .JPG and the .MSK file you are using as a mask, and it will overlay your banner on the transparency.  The demo menu includes an example of this application.

Note that you cannot make color-defined regions of the metafile transparent.  ThinHelp loads bitmap overlays in a specific order, and metafiles are always placed on top of the masked bitmap as the last step in the display process.

Adding variety to BMPs...and adding BMPs as metafiles

You can also add metafile graphics to BMPs, allowing you to display the same bitmap in two different fashions, or with two different sets of pointers and text descriptions overlaid on the graphic.

If you use Paint Shop Pro you have a tool which offers you a unique method of adding special effects to your metafile-enhanced JPEGs and BMPs.  If you load a BMP into Paint Shop Pro and select any or all of it for copying to the clipboard, the data copied to the clipboard will be available for pasting both as a metafile and as a bitmap.  Just be sure to set the right hotspot dimensions for these ”modified bitmap overlays” or they’ll look stretched and distorted.

Adding a metafile to the last frame of an animation

ThinHelp also allows you to add a WMF format metafile to a Push-generated hotspot which is displayed over the very last frame of a play-once animation.  With this feature allows you to display an animated corporate logo or cartoon and have the same animation display descriptive text on the last frame telling more about the product, procedure or section of the title.  Unfortunately, you’re limited to one .SEG file per animation, so if you want to use multiple effects you’ll need to use multiple animation archives or a custom animation sequence.  There’s a demo of this technique available from the demos menu.

Example

MYPIC.JPG, MYPIC.SEG and MYPIC.MSK will produce a transparency-masked, metafile-overlaid JPEG image using the following syntax:

{ ewc THNHLP,THIN,!BITMAPS.LZH,MYPIC }

If you want to overlay the metafile and mask on a .BMP bitmap (e.g. MYPIC.BMP) rather than a JPEG, the syntax is exactly the same:

{ ewc THNHLP,THIN,!BITMAPS.LZH,MYPIC }

If you want to use the same bitmap twice, once with a mask and no banner and once with a mask and a banner, name your files MYPIC1.BMP, MYPIC1.MSK, and MYPIC.SEG.  You can now reference the bitmap and mask with no banner...

{ ewc THNHLP,THIN,!BITMAPS.LZH,MYPIC1 }

...and use MYPIC without the ”1” to display both the banner and the mask:

{ ewc THNHLP,THIN,!BITMAPS.LZH,MYPIC }

Step by step

1. Create metafile text or graphics in your drawing program (You can use MS Draw from Microsoft Word to create rudimentary metafiles and text banners if you have no other metafile drawing tools) and copy it to the clipboard.

2. Select a .JPG or .BMP file to which you wish to add text or metafile graphics and load this bitmap into Push.

3. Create a Push hotspot by dragging the mouse cursor over the bitmap just as you would with SHED or a normal Push hotspot.  The hotspot can be any size.

4. Select Edit from the top menu bar of Push and Paste the metafile into the hotspot, or use Ctrl+V.

5. Resize the hotspot so the metafile is correctly proportioned.  Your vector graphic will dynamically stretch and shrink to fit the hotspot.  Once it has been proportioned correctly, position the hotspot on the bitmap by clicking and dragging it, making sure that the hotspot boundaries do not go over the edges of the graphic.

6. If you need to add a jump, popup or macro to the hotspot, add this before saving the .SEG file and adding it to the compressed graphics archive.

7. Save the .SEG file so that its name corresponds with the bitmap’s name (e.g. if the bitmap was called PRODUCTA.JPG the .SEG file would normally be called PRODUCTA.SEG.)

8. If you’re overlaying a metafile on a JPEG, add both the JPEG and the .SEG file to a new or existing .LZH bitmap library archive.  JPEGs with overlays cannot be added to baggage or referenced in your RTF source without first being added to an .LZH archive or the .SEG file will not be displayed.

9. Reference the bitmap in your embedded window statement just like a normal ThinHelp embedded window bitmap, but leave off the file extension.  For example, if PRODUCTA.JPG and PRODUCTA.SEG were stored in the archive BITMAPS.LZH, and BITMAPS.LZH is added to the file’s baggage, the resulting embedded window would be referenced with this statement:

{ ewr THNHLP,THIN,!BITMAPS.LZH;PRODUCTA }

10. Transparency and display properties can also be added to the embedded window statement if desired.

Notes, issues and tips

 Even though Push will only permit one metafile overlay per hotspot, you can paste metafiles into more than one hotspot on the same bitmap.  This offers a wide range of layout and bannering effects.

 When you first copy the metafile into a hotspot it may appear distorted.  This is because the metafile fits itself to the dimensions of the hotspot.  Change the shape of the hotspot by dragging the corners to create the appropriate dimensions for the metafile.

 The zoom function of Push is useful for creating proper hotspot boundaries for pasted metafiles, particularly if the metafile was originally a bitmap.  Zoom in on the graphic using the View menu to tweak hotspot sizes.

 The file format for .SEG files, if you require it for development purposes, is documented in SEG.H.


Precision window sizing control with ThinHelp

  There are windows...and there are windows.

  Pixel-based sizing versus Help units

  Sizing windows: two approaches

  THWaterMark() window sizing step by step

  THMoveWindow() window sizing step by step

  Notes, tips and issues

There are windows...and there are windows.

The level of graphical flexibility offered by ThinHelp will often result in creative dilemmas which are difficult to resolve with the tools Help provides.  One of the most common dilemmas is layout insurance, specifically how to insure the quality of Help topic layouts at 640x480, 800x600, 1024x768 and 1280x1024 display resolutions without losing graphical balance at one or more of these resolutions.

There are many 16 bit Help DLLs which offer the ability to size and position Help windows to precise pixel-based coordinates.  If you’re comfortable with these DLLs and don’t author 32 bit Help, you may not care about ThinHelp’s precision sizing features.  But if you need better control over 32 bit Help layouts and don’t want to learn complex API calls for the task, ThinHelp offers two solutions that should meet most needs.

Pixel-based sizing versus Help units

Help comes with its own method of sizing windows at launch using the [WINDOWS] section of the .HPJ, and it allows you to alter preset window sizes using the PositionWindow() macro.  The problem with this macro is that it is blind to the hardware.  It doesn’t know or care what display resolution is in use on the target system.  Instead it sizes the window based on ”Help units” which are calculated as percentages of the screen’s total height and width.  This method works well for most text-based Help, but it’s a cumbersome and unpredictable method for sizing Help-based applications that depend upon careful graphical balance.  In fact, many of Microsoft’s own helpfiles which depend on Help units sizing look ugly and unbalanced at high screen resolutions or become difficult to use at standard 640x480 resolution.

You can’t control the end user’s screen resolution.  But you can control the size of your Help window, right down to the pixel if necessary, so that a layout designed at 640x480 resolution retains its topic layout at 1280x1024.

Custom Windows API functions

Custom Windows API macro calls such as MoveWindow() or SetWindowPos() can provide this ability using relatively complex and highly versatile macro syntax, and 32 bit Help authors can use the relatively obscure and seldom-used HelpWinInfo() macro for more Help-specific sizing control.

The problem with these macros is that they pose compatibility problems.  Custom API function calls, especially in 16 bit helpfiles, can be a real problem if they’re not handled perfectly by you as the author.  ThinHelp solves this problem by using something called an abstraction layer to insure that no matter what flavor of Windows your helpfile is running under -- 3.1, 95 or NT -- ThinHelp translates your custom macros into the appropriate macro syntax for that flavor of Windows before passing your command on to the appropriate Windows module.  THMoveWindow() is provided as a means of reliably implementing the versatile MoveWindow() macro regardless of where your helpfile is used.  (MoveWindow() is our Windows API command of choice for resizing Help windows.)

Sizing windows: two approaches

THWatermark()’s way

THWaterMark()’s window sizing is less versatile than that provided by THMoveWindow() (described below) and Windows API functions, but it’s also the quickest and easiest precision sizing technique available to Help authors who don’t have ”hacker blood” or the patience to deal with a six-parameter macro.  THWaterMark() doesn’t apply your specified pixel-based dimensions to the whole window.  Instead, it assumes that what’s important to you is the content of the window.  When window sizing parameters are used as part of this macro, ThinHelp applies the specified size to the sum of the non-scrolling and client regions, and the borders and menus are then drawn around the resized topic display area.  Finally the entire window is centered on the screen.

The result is an entirely new type of content control.  You can now position bitmaps in a topic window, specify a window’s height and width with a THWaterMark() macro and know with absolute certainty that when the topic is displayed, no amount of end-user desktop customizing will affect the resulting layout.  What you author is what your user will see...no questions asked.  The only possible obstacle to always-perfect display will be the use of non-default Help text font sizes.

THMovewindow()’s way

SetWindowPos(), HelpWinInfo(), MoveWindow(), ARSENAL.DLL, WINSIZEx.DLL and HCONTENT.DLL all apply their sizing routines to the entire window.  A 400x400-pixel window is 400x400, menus, buttons and all.  They also use offsets.  You don’t just specify height and width when authoring these macros...you also specify distances from the top and left edge of the screen to the window’s border.  The result is surgically precise positioning of windows...and a vast improvement over Help’s handling of the job.  All of these options offer more control over the Help window than ThinHelp can provide.  You can also author THMoveWindow() to resize the window without moving it, or move it to a new position without resizing it.

Unfortunately none of these techniques are particularly easy to learn and author.  THMoveWindow() usually requires some study and a fair bit of testing before you truly become comfortable with it, but once you see the visual effect it has on your window layouts at various screen resolutions and some of the tricks you can apply with it, you may find it more useful than the [WINDOWS] section of the HPJ for defining window sizes and positions for all your Help projects.

THWaterMark() window sizing step by step

1. Determine the screen size you wish to use for a given topic or series of topics.  This size should always be less than 600x420 to insure accurate display on systems set to 640x480 resolution.  The best way to do this is to compile your helpfile without sizing controls and manually resize it to the dimensions you want, capture the window to a graphics editor and allow the graphics editor to tell you the window dimensions.

2. Register the THWaterMark() macro in the [CONFIG] section of your project (this will be done automatically for ForeHelp users) and insert a THWaterMark() macro either in the [CONFIG] section of your .HPJ file or as a topic entry (footnote) macro in the topic where you wish to change the window size to pixel-based coordinates.

THWaterMark() macros designed for the sole purpose of resizing the window should be authored as follows:

THWaterMark(hwndContext, [WidthInPixels], [HeightInPixels], coBackground, qchPath, `',0xnnnn)

...where [WidthInPixels] is the desired width of the window in pixels, [HeightInPixels] is the desired height of the window in pixels, and nnnn are the desired parameters for any watermarks or color control you may wish to include with this macro.  (If no watermark or color control is desired, 0x0000 may be used as the default parameter here.  This parameter should not be left blank.)

The following sample macro will set the topic display area (the nonscrolling region plus the scrolling region) to a width of 550 pixels, a height of 350 pixels, apply no watermark bitmap, and either preserve or restore normal text background color:

THWaterMark(hwndContext, 550,350, coBackground, qchPath, `', 0x0000)

Be extremely careful of excessive height measurements.  ThinHelp will center your resized topic display area on the screen before adding window borders, menu bar, caption bar and button bar to the Help window.  If you specify a topic display area larger than 600x420, it is possible that users of 640x480 displays will see part or all of the caption bar disappear off the top of the screen, especially in large font modes.  This results in more than just an ugly layout.  It can also scare the daylights out of novice users who may not know how to use Escape or Alt+F4 hotkeys to close the Help window.

Also be careful of the values used for window positioning, specifically the use of zeroes.  If one of the two window sizing parameters is set to 0, then both must be set to 0.  The window will not be resized vertically to 400 pixels in height if you specify 0,400 as the sizing parameters.  Use either both parameters or two zeroes.

3. Compile and test.  Try to test the appearance of the helpfile in at least three different screen resolutions (640x480, 800x600 and 1024x768) with large font mode activated to insure the best possible layout in all common display modes.

THMoveWindow() window sizing step by step

1. Determine both the screen size or screen position you wish to use for a given topic or series of topics.  If size and position are desired, you should calculate dimensions based on a target sytem of 640x480 resolution.

2. Register the THMoveWindow() macro in the [CONFIG] section of your project (this will be done automatically for ForeHelp users) and insert a THMoveWindow() macro either in the [CONFIG] section of your .HPJ file or as a topic entry (footnote) macro in the topic where you wish to change the window size to pixel-based coordinates.

THMoveWindow() macros designed for resizing and repositioning the window should be authored as follows:

THMoveWindow(hwndApp,[PixelsFromLeft], [PixelsFromTop], [WidthInPixels], [HeightInPixels],1)

...where [PixelsFromLeft] is the distance from the left edge of the screen in pixels where the window should start, [PixelsFromTop] is the distance from the top edge of the screen in pixels where the window should start, [WidthInPixels] is the desired width of the window in pixels, and [HeightInPixels] is the desired height of the window in pixels.  (The ”1” is always used as the last parameter.  It tells Windows to repaint the window at the new position and dimensions.)

The following sample macro will resize the window to a width of 550 pixels, a height of 350 pixels, and reposition it 10 pixels from the left edge of the screen and 30 pixels from the top edge.

THMoveWindow(hwndApp,10,30, 550,350,1)

The same cautions listed for THWaterMark() window sizing also apply to THMoveWindow().  Be careful of using excessive height measurements if your compiled project might be used on 640x480 displays.

3. Optionally you can have THMoveWindow() resize your Help window without moving it, or move your Help window without resizing it.  To move without resizing, use ”-1” as the fourth and fifth parameters, for example:

THMoveWindow(hwndApp,10,30,-1,-1,350,1)

To resize the window without changing its position, use ”-1” as the second and third parameters, for example:

THMoveWindow(hwndApp,-1,-1, 550,350,1)

4. Compile and test.  Try to test the appearance of the helpfile in at least three different screen resolutions (640x480, 800x600 and 1024x768) with large font mode activated to insure the best possible layout in all common display modes.

Notes, tips and issues

 It is usually considered a courtesy not to specify the same set of pixel-based coordinates in every topic in a browse sequence or helpfile in case the user decides they would prefer a resized window.  This means that some topics accessed from the Windows 95 Contents tab may not have pixel-based sizing control.  It’s a trade-off between end-user comfort and graphic design that must be looked at in context of the whole project.

 If a watermark has been specified and you want this watermark to continue to be displayed after the window has been resized, then you must specify its filename, path and positioning parameters in the same macro as your resizing parameters.  If you do not do so, the THWaterMark() macro will resize the window but not continue to display the watermark.  If you are applying background color control to a helpfile using THWaterMark, you must re-specify the color in the resizing macro or the coBackground parameter shown above will restore the background to the default desktop text background color.  You cannot leave this parameter blank.

 THMoveWindow() can be used with hwndContext instead of hwndApp as its first parameter.  This will move the contents of the scrolling region of the topic window rather than the whole window, offering a range of unusual layout effects.  You’ll find it most useful if you decide to explore ThinHelp’s unsupported paning features.

 Although it won’t ordinarily be needed in your authoring, THMoveWindow() produces a TRUE/FALSE return value so that it can be used in IfThenElse() macros.  It returns TRUE if the window was successfully resized and FALSE if the resizing failed.

 ”Adjust window” buttons of the type used with some 16 bit sizing DLLs are recommended for use only by experienced Help authors.  The global application of a window-resizing macro could knock out custom watermarks and background colors in projects where multiple watermarks or colors are applied.


Controlling 16-bit Help background color
Controlling Help’s background color

  Changing color topic by topic

  What works and what doesn’t work

  How ThinHelp defines the background color

  Steps for authoring custom background colors

  Using THRGB() to translate RGB indices to BGR hex values

  You now have background colors...what about link colors?

  Notes, tips and issues

Changing color topic by topic

WinHelp allows the author-defined alteration of text colors on a character-by-character basis, but until now background color could only be controlled through the .HPJ file or by the implementation of a series tricky and rather cryptic ”hacks”.  Any Help author who has dabbled in HTML knows the value of topic-by-topic color control, and now it’s achievable in WinHelp, reliably, in both 16 bit and 32 bit helpfiles.

What works and what doesn’t work

Background colors for the nonscrolling region cannot be controlled in this version.  The only color control available with version 1.0 of ThinHelp is applied to the scrolling region of the topic display area.

Text color cannot be controlled with ThinHelp.  This function is available through your authoring tool and does not require control by ThinHelp.

This function will override background colors specified in the [WINDOWS] section of the .HPJ and adapt to nonstandard custom themes in Windows 95.  ThinHelp will display your specified background color even if the end user has specifically told windows to apply no background colors to Help.

Any of the 16 million available colors can be used as background colors for the client region, but Windows will dither the colors as it sees fit on most displays with 256 colors or less, just as it dithers nonstandard background colors specified in the [WINDOWS] section of the .HPJ file.

How ThinHelp defines the background color

THWaterMark()’s background color support uses the COLORREF value, the same value programmers use to control application colors, instead of the usual RGB values, and expects author-specified colors to be defined as BGR (Blue|Green|Red) values rather than the usual RGB.  This is Microsoft’s standard for setting this particular window property.  It is not a design flaw of ThinHelp.  You should have no difficulty adapting to this if you’re experienced at Windows interface programming, but if you’re a veteran Help or Viewer author who’d prefer to work with the standard comma-separated RGB values used in defining your window colors in the project file, or if you have no tools available to you for calculating hex color values, the optionalTHRGB(), submacro is available to allow you to enter your color values in standard Help-style RGB syntax.

Unlike ThinHelp’s transparency support for embedded windows, THWaterMark() can accept any valid hexadecimal color value...but be aware that it is usually wise to stick to the sixteen standard Windows colors or one of the preselected dithered shades offered from ThinHelp’s background color sampler in order to avoid display colors which may be difficult to read.  Few things will make your project look worse, especially on 16 color and 16 bit systems, than a carelessly-selected background color.

Steps

1. Select the color you want to use for your Help background.  Use the supplied color chart as a guide if you like.

2. Create a THWaterMark() macro to change the background color to the selected color.  Be extra-careful with the syntax...you’ll need to handle this delicately if you’re using a watermark or tiled texture bitmap in the topic.  The macro is applied as a standard THWaterMark() macro except that it uses no watermark filename in the sixth parameter and no window sizing parameters, just 0’s for the sizing parameters, and only a pair of empty quotes where the filename usually goes.

Here’s an example that places the menu watermark bitmap bottom-left and changes the window background color to white.

THWaterMark(hwndContext,0,0, 0xFFFFFF, qchPath, `!BILDER.LZH;THWATER.BMP', 0x0211)

3. If you wish to change the background color for the topic without allowing end-user control, use the macro as a topic-entry (footnote) macro.  If you want to use it for special effects or offer the user control over the background color (for example, by offering from a menu of background colors for use when browsing your helpfile), author the THWaterMark() macro so that it is activated from a hotspot, button or menu item.

Using THRGB() to translate RGB indices to BGR hex values

If you’re not a programmer, you’re probably familiar with Help’s RGB values and want nothing to do with hexadeximal BGR values.  No problem...the THRGB() macro is included as a custom ThinHelp macro to assist you in this area.

THRGB()’s only function is to allow you to enter your background color values using the same RGB color syntax used in your project file’s [WINDOWS] section.  For example, you may already know that 255,255,192 is pale yellow.  If you didn’t know, you can get this value from any program which gives you access to the Windows palette, from Control Panel to MS Paint.  The BGR hexadecimal equivalent for this is 0xC0FFFF...a value you probably couldn’t track down without a special tool for the job.

Once THRGB() is registered in the [CONFIG] section of your project file (the reference card offers click-and-copy buttons for the registration syntax) you can begin using it to specify background color values as shown in the samples below.

THWaterMark(hwndContext,0,0,THRGB(255,255,0),qchPath,`',0x0000)

...specifies a bright yellow background.

THWaterMark(hwndContext,0,0,THRGB(192,255,192),qchPath,`',0x0000)

...specifies a pale green background.

You now have background colors...what about link colors?

If you’re adventurous enough to want to control background colors, or under orders to make your helpfiles match the color schemes used on your company’s Web site, you won’t want to stop at background colors alone, not when link color control is so easy.

It’s not widely known that Help supports not one but two types of link color control.  You probably know about preceding context strings with ”%” to force links to display in your specified color, but this won’t work if you want your custom-colored links to have the corresponding link underlines.  Instead you must use ”*” before your hidden context or macro string.  Here’s how a sample teal colored link might look in Word.  The text is hard-coded to a teal color using your authoring tool’s own font color formatting, and the ”*” tells Help to keep the teal color and produce the telltale Help link underline.

Many Help authoring tools provide their own limited or complete control over link color, so this feature will not be explained in further depth here.

Notes, tips and issues

Always, always, always define text colors in your RTF source when you use THWaterMark() to set background colors.  Auto color text is not acceptable.  If your user has an inverse color scheme set on their computer, any light colored background specified as your topic background color could render your topic text completely unreadable if the window text color is set to an inverse shade such as yellow, white or cyan.  Triple-check your projects prior to release to insure that all topic text in color-controlled topics is ”hard-coded” to your specified text color.  Configure an inverse color scheme on your own system for testing purposes (Windows’ Control Panel offers inverse color schemes) and preview both the RTF source and the helpfile with inverse screen colors activated to insure that no stray topic text is set to Auto color.

 Never assume that what you see on your screen is what your end user will see.  Check to make sure.  Keep in mind that the drivers used by your video card may provide a very different appearance from other video drivers.  Graphics specialists almost always test their work using standard Windows 3.1 video drivers before considering the project finished.  Screen resolution should be checked as well as color accuracy.  If you do not have a copy of QuickRes, an unsupported Microsoft tool designed for switching screen resolution and color depth on the fly, obtain it from the Power Toys archive at Microsoft’s Web site.  (No link is provided to this tool.  Microsoft regularly changes its URL making direct links unreliable.)  A quick resolution changer is an important testing tool no serious Help author should be without.


License key and serial number technology
License keys, serial numbers, date locking

When combined with the ASETUP installer or any other installation software capable of writing registry entries in Windows 3.1, Win95 or NT, ThinHelp offers a powerful license key technology for copy protection, topic restriction, software expiry dating and shareware registration insurance.

ForeHelp users will need to apply this feature of ThinHelp manually using the instructions supplied here.  THTestLicenseKey() does not integrate with the ForeHelp interface.

  What exactly does license key protection do?

  Uses for ThinHelp license key technology

  How ThinHelp uses checksum technology

  The THTestLicenseKey() macro

  Setting registry values

  Author definable actions for THTestLicenseKey()

  Enforcing trial date limits

  Locking users out of specific topics

  Setting multiple access levels in a helpfile

  Testing THTestLicenseKey() prior to distribution

  Notes, tips and issues

What exactly does license key protection do?

The easiest way to describe what it does to tell you how we used it in JPANI’s shareware editions.  (JPANI was the predecessor to ThinHelp.)  When you first installed the shareware version of JPANI, you were asked for your name and serial number.  Normally you would not have a serial number, so you left this field empty.  This information was written to the Windows registry along with the installation date of the software.

Macros registered in the [CONFIG] section of JPANI’s helpfile were used to detect the installation date and compare it against the current date.  After two days, it popped up a registration reminder.  This nag screen” had a dual purpose.  In addition to being a registration reminder, it also described how that reminder was authored and how the protection and dating scheme could be used in your helpfiles and Viewer projects.

The shareware version of JPANI had a 30-day trial limit, after which time it was assumed that you weren’t interested in purchasing the software.  Through the use of another set of macros registered in the [CONFIG] section based on the same technology, a lock was applied to the helpfile which forced it to close before the first topic was displayed.  The only way to break” this protection was to set your system clock back to a period within your 30-day trial or to install a newer shareware release.

With ThinHelp, we realize that thirty days may not be long enough to fully evaluate its many features.  The shareware version of ThinHelp can remain on your system as long as you like...you simply can’t distribute any projects using the shareware version of the DLL.

Uses for ThinHelp license key technology

JPANI’s expiry dating” is only one of many potential applications for ThinHelp’s license key technology.  This feature can be used to compare the installation date against the current date, allowing you to kill-date” your software if it has been installed long past a point at which the user should have updated; to date-lock only certain topics or sections of your helpfile; provide special day” popup topics (perhaps a set of weekly tips or motivational reminders) and other unique features.  The serial number information can also, of course, be used to determine whether your end user has the right to use your software.

ThinHelp’s license key features will not completely replace utilities such as the WinHelp Password Lock System, SoftLock for WinHelp or HDK’s helpfile encryption technology.  It won’t protect a helpfile from any hacker who knows how to use a Help/Viewer binary decompiler utility.  But for most situations where a degree of topic security, dating control, or registration insurance is needed, you should find its capabilities quite sufficient and fairly easy to implement.

How ThinHelp uses checksum technology

In order for ThinHelp to properly make use of its checksum technology and perform an action based on the validity of registry entries, there must be two values written to the registry to compare against each other.  One of those values will be a string of text (usually a name) and the other will be a checksum value (a serial number) corresponding to that name.  This serial number is generated by a utility called GENSNR.EXE, included only with the full registered version of ThinHelp.  GENSNR.EXE determines the appropriate matching value from the supplied name, and it will be up to you to supply this value (serial number) to the user as needed.

The THTestLicenseKey() macro

The license key technology is based on a single macro, THTestLicenseKey(), which can be called from WinHelp or Viewer in any normal fashion.  This macro is registered in the [CONFIG] section of your HPJ or MVP file using the following syntax:

RegisterRoutine(`THNHLP',`THTestLicenseKey',`i=USSSii')

...and it is called from a hotspot, topic entry (footnote) macro or [CONFIG] macro using the following syntax:

THTestLicenseKey(hwndApp,`THNHLP',`[KEY1NAME]',`[KEY2NAME]',n1,n2)

...where n1 is the number of elapsed days between the installation of the helpfile and the date the helpfile is opened, and n2 is the action to be taken after that number of days has expired. The first four parameters are always the same; only the last two are author-definable.

[KEY1NAME] is the entry value of the first key ThinHelp is to check, and [KEY2NAME] is the entry value against which it will do a checksum comparison if required.  Information about checksum calculation and help with the GENSNR.EXE utility used to generate matching registry key values are available only in the THREGKEY.HLP file distributed to registered users.

Setting registry values

Help with creating valid registry values for THTestLicenseKey() is only available in the THREGKEY.HLP file distributed to registered users.

Author definable actions for THTestLicenseKey()

How ThinHelp performs and reacts to its registry checks depends on which return value you want THTestLicenseKey to test for.  The macro can execute a protection action or check for two possible situations, each corresponding with a different value.

n1

The n1 value is the number of days elapsed since the recording of the ThinHelp registry key.  This value is used to control when or if the actions specified by the n2 value will be executed.  If fewer than the specified number of days have passed, the action specified by n2 will either not be executed or, if the n2 value is 2”, return a value of FALSE to WINHELP.EXE for use in IfThen() or IfThenElse() macros.  Valid values for this parameter are whole integers such as 2, 14, 90 or 365.  Fractions or decimals may not be used to specify a part of a day.  Values higher than 999 will probably be of little practical use; actual values may be as low as 1.

n2=0

If a value of 0” is specified as n2’s value, ThinHelp checks the registry for a serial number and matching username stored in the registry.  If the serial number matches the name, the macro does nothing.  If the two do not match, ThinHelp displays a message and closes the helpfile instantly.

The name/serial number match is calculated with the help of a special algorithm which is not explained in this helpfile.  The specifications of this algorithm and the utility which uses this algorithm to generate serial numbers from usernames will only be made available to registered users.  (If you are a registered user, you can find this information in KEYINFO.HLP.)

n2=1

If a value of 1” is specified as the n2 value, ThinHelp will only search for a ThinHelp registry entry...any ThinHelp registry entry.  If no such entry is found, ThinHelp will assume that the software setup has either been deliberately hacked or damaged somehow, display a message alerting the user to incorrect software setup and close the helpfile.  If an entry is found, the helpfile proceeds normally.

This value is usually used for determining whether someone has tried to outfox a helpfile’s trial usage period by erasing the registry key.

n2=2

This value tells ThinHelp to interact with other Help macros rather than perform actions on its own.  If 2” is specified as n2’s value, ThinHelp will check for a valid name/serial number pair.  If a valid pair is found, it returns a TRUE value to WinHelp which can be used to determine which actions in IfThen() and IfThenElse() macros will be carried out.  This allows you to define application-specific actions for the macro to perform rather than simply closing the helpfile or allowing the user to proceed, and also permits you to author your own custom registration and security messages for use with THTestLicenseKey().

Enforcing trial date limits

Here’s a sample THTestLicenseKey() macro which could be used to pop up nag screens” and enforce a 30-day trial date limit in some or all topics of a helpfile.  This macro runs immediately after the RegisterRoutine() macro and sets a maximum 30-day trial period” for the software.  After 30 days, the helpfile will show an expiry message box and quit.

THTestLicenseKey(hwndApp,`THNHLP',`NAME',`SNR',30,0)

Now THINHELP.HLP checks to see if more than five days have expired since the software was installed.  If so, it returns TRUE and opens the helpfile at an author-defined nag screen” topic instead of the contents topic.

IfThen(THTestLicenseKey(hwndApp, `THNHLP', `NAME', `SNR', 5, 2), `JI(`',`ID_OLDER')')

Locking users out of specific topics

If your user has a decompiler, or enough skill to acquire and use one, this feature won’t lock them out of the text data.  But for the average user it’s more than enough security to prevent them from seeing topics meant only for some users.  Remember that macros such as this must always be typed with no line or paragraph breaks.

IfThenElse(THTestLicenseKey(hwndApp, `THNHLP', `NAME', `SNR',0,2), `JI(`myfile.hlp', `AUTHORIZED_USER_INFO')', `JI(`myfile.hlp', `UNAUTHORIZED_USER_ALERT')')

Setting multiple access levels in a helpfile

Your setup software can query the end user to enter more than one serial number if necessary and store this information in several registration keys, such as SNRLOWACCESS, SNREXTENDED, SNRADMINONLY, etc.  By applying THTestLicenseKey() repeatedly and using these additional key names as the fourth parameter, you can distinguish multiple access levels in the same helpfile, or even for the same user, and have these access levels apply even when the helpfiles are stored on a network server.

Testing THTestLicenseKey() prior to distribution

ThinHelp includes an embedded window class, THINREGISTER, which can be used to test your projects prior to release.  Here’s the syntax for this embedded window statement:

{ ewc THNHLP,THINREGISTER,THINHELP/[KEY1NAME]/[KEY2NAME] }

This statement should be entered into your helpfile using the two keys to examine as the [KEY1NAME] and [KEY2NAME] subparameters.  No other options are available.  It is intended for live testing of your helpfile’s license key performance prior to distribution.  It can also be added to helpfiles designed for administrator access only as a means of keeping track of registry information for individual users.

The sample statement below could be used to check the validity of ThinHelp’s own installation.  It compares the value assigned to NAME in the THINHELP key against the value assigned to SNR.  If they don’t match, it exits the helpfile instantly.  If they do match, it displays the registry key information.

{ ewc THNHLP,THINREGISTER,THINHELP/NAME/SNR}

This embedded window can also be used as a rudimentary protection scheme and is meant for use in distribution only if you have a project which would otherwise exceed the acceptable limit for registrations of custom macros (the limit is approximately 55).  You’ll probably need more flexibility than simply an instant shutdown of the helpfile (perhaps a conditional action to take based on a match or lack of a match), and you may have more than one key which needs to be checked in each helpfile (perhaps several levels of access on a network to the same helpfile), so this method of protecting a helpfile is not very versatile.  It also displays an embedded window which may be inappropriate to the helpfile itself.

Notes, tips and issues

 The serial number is generated to match the user’s name, so it can only be used in conjunction with that name.  This provides a fairly high degree of copy protection for your registered shareware and secure help systems.


Licensing ThinHelp
Licensing and registration of ThinHelp

Rights of use

This shareware version of ThinHelp may be used to test its suitability for your help authoring needs for up to 30 days.  It displays a shareware registration reminder at launch.  Under no circumstances are shareware versions of the ThinHelp DLLs to be redistributed with compiled projects, even by registered users.

About the registered version

The registered version of ThinHelp does not display these reminders and registered users may freely distribute THNHLP.DLL, THNHLP32.DLL, THNBMP.DLL, THNBMP32.DLL and HLPLHA.DLL with their compiled helpfiles or Viewer titles.

Registration of ThinHelp also includes the right to use Push, the ThinHelp hotspot hypergraphics editor, on a single machine.  Push may not be redistributed.

Registration is not required for the use of the ASETUP micro-install creator included with this demo.  Consider it to be our gift for taking the time to give ThinHelp a look.

Registered users of ThinHelp will receive the latest versions of THNHLP.DLL and THNBMP.DLL personalized for their use and with the shareware reminders removed, complete documentation, additional utilities for ThinHelp’s registration key protection, access to direct support from the developer, as well as HLPLHA.DLL for use in LZH archive management from WinHelp or compressed non-graphical baggage handling and the Graphics Gallery for ThinHelp graphics browser and bitmap library.

In most cases, you can receive your registered version of ThinHelp via email on CompuServe, America Online, or over the Internet, within 48 hours of receipt of payment.

Prices

ThinHelp can be registered by mail or, for faster service, via CompuServe.

ThinHelp in Germany:	DM249 (DM199 prior to Nov. 1/96)
ThinHelp elsewhere:	US$169.00 ($139.00 prior to Nov. 1/96)
ThinHelp via CompuServe GO SWREG:	US$169.00 ($139.00 prior to Nov. 1/96)
European sales, licensing and product development:

Dipl. Ing. Bernd Herd	Order form

Rudolf-Virchow-Str. 8

68642 Bürstadt

Germany

CompuServe: 100545,3001

Internet: herdsoft@aol.com
Voice: +49-6206-79222 After march 1997 +49-6206-707775
Fax: +49-6206-79222 After march 1997 +49-6206-707776

North American sales and licensing

Weisner Associates Inc.,	Order form

2817 Zarthan Ave. S.

Minneapolis, MN 55416-1861

USA

Voice: 612-928-8177

Fax: 612-928-3007

World Wide Web: http://www.primenet.com/~wai/resource/thinhelp/

Internet: cublea@cyberstore.com

Warranty

No warranty is expressed or implied that ThinHelp is suitable for any particular requirement or will function in any specific programming or application environment.  You have 30 days to test this software with non-distributed projects to determine its fitness and reliability for the purpose intended.

Reverse engineering, alteration or disassembly
of any of the ThinHelp utilities is expressly prohibited.
Distribution of the shareware version with your helpfiles
and programs is not permitted under any circumstances.
It is for personal use only.


Copyrights and rights of use

You must have a legal right to distribute the bitmaps, animations and sound files used in your helpfile or Viewer title.  The bitmaps in this helpfile were all either created for this project or acquired from Internet archives or public domain graphics libraries.  You are free to use and distribute the ANICONS.LZH library and the JPG files inside of BILDER.LZH, but you may not use the BMP files in BILDER.LZH in your helpfiles.

Registration of ThinHelp gives you the right to distribute Help and Viewer titles with ThinHelp DLLs only if these files are under the registered company or individual’s copyright or development agreement.  You may not loan ThinHelp to clients, students or others and permit them to distribute their helpfiles or Viewer titles with ThinHelp’s DLLs.


Internet-accessible resource...

 The product, service or resource referred to here is an Internet-accessible or freely downloadable resource which you can access using the World Wide Web HTML links page supplied with this software.

THINHELP.HTM, which is found in the directory containing ThinHelp’s helpfiles, includes more than a dozen useful Internet links for Help authors in general and ThinHelp users in particular.  To access the resources linked on this page, simply connect to the Internet, open your browser, and load THINHELP.HTM into it either by dragging it onto the browser window or by using the supplied launch button.


Graphic import filtering with THNHLP.DLL

A partial solution for .SHG editing woes

A long-missing ingredient in the Help authoring recipe has been at least partially completed with the addition of .SHG graphic import filtering to THNHLP.DLL 16 bit.  This means that you can finally import your .SHG files directly into the 16 bit versions of Microsoft Office applications, Paint Shop Pro 3.x, Photoshop 3.0, and virtually any other application that supports the Microsoft graphic import filter standard.  It has been tested with the following 16 bit applications and will probably be compatible with many more.

MS Word 2.0
MS Word 6.0
Microsoft Office 3.x
Paint Shop Pro 3.0/3.11 (16 bit)
JASC Multimedia Center (16 bit)
DaVinci 2.2
    (the universal graphic import tool used by FormPad and Push)
LZVIEW

Essentially this feature allows you to open an .SHG file created by SHED.EXE right into your graphics processing software as if it was a normal .BMP or .WMF file, edit its graphical content and save it without having to go through the intermediate step of exporting it from SHED.EXE...if your version of SHED.EXE even supports exporting.  (Most don’t.)

Push offers the ability to open .SHG files and export them as JPEG or .BMP bitmaps, but you might still find true .SHG import a timesaving feature in your authoring.

Graphic import filter compatibility is not available as a feature in the 32 bit version of THNHLP.DLL.  It will work as advertised for 16 bit applications in 32 bit versions of Windows but it will not function with 32 bit applications unless they also support other 16 bit MS-standard import filters.

How to install THNHLP.DLL as a graphic import filter

If you’re a registered user, you may already have this feature installed on your system.  If graphic import filtering was not configured when you installed the software, or if you need to reinstall THNHLP.DLL as an import filter later, you can do so by manually adding a single line of text to your WIN.INI file.

To install THNHLP.DLL as a graphic import filter for 16 bit applications, insert an entry in the [MS Graphic Import Filters] section of WIN.INI formatted as follows.  (Clicking the Copy button will copy a template INI entry to the clipboard.)

Segmented Hypergraphic(.SHG)=[DRIVE]:\[PATH]\thnhlp.dll,SHG

...where [DRIVE] is the letter or name of the drive where the 16 bit version of THNHLP.DLL is stored and [PATH] is the subdirectory path to that file.  Here’s an example of how the INI entry might be written on a typical system:

[MS Graphic Import Filters]
Segmented Hypergraphic(.SHG)=C:\THINHELP\redist\dll16\thnhlp.dll,SHG

As long as you keep a copy of THNHLP.DLL in the directory specified here, THNHLP.DLL will be available as an .SHG import filter.  If you move your ThinHelp installation directory, simply run the install program again so that THNHLP.DLL’s new path is properly identified to applications that can use it.  If you want to avoid all such problems, simply make a copy of THNHLP.DLL in your \MSAPPS\GRPHFLT\ directory and reference it from there in your INI entry.

Notes, tips and issues

 This function does not allow save-as-SHG at this time.  It only allows import.  Save-as-SHG can only be achieved by Push or SHED-compatible hypergraphics editors.


ThinHelp features
ThinHelp features and quick-start

With built-in support for watermarks/textures, transparent bitmaps, buttons, animation, audio, registration keys and more, ThinHelp is arguably the most versatile and comprehensive embedded-window extension available for WinHelp.

This versatility means that working with ThinHelp at a deep level can become quite complex for new users.  We recommend learning ThinHelp one feature at a time to get a feel for how it works.  You now have the tools...give yourself the time you’ ll need to make them work for you.

 Features: ThinHelp overview and quick-start

 Printable 16/256 color BMPs and TrueColor JPEGs

 Painless animation development without AVI or extensions

 Finally, a replacement for SHED with the features you’ve been asking for

 A fast, thorough and uniquely versatile bug checker for 16 bit Help projects

 Full support for two types of author-selectable bitmap transparency.

 Fast-displaying, ultra-versatile 16 and 32 bit watermark support

 Compiled Help up to 90 percent smaller and 90 percent faster than standard compression

 Conditional bitmap display.

 Depressable buttons from any size BMP or JPEG

 Graphics databasing” for interfile graphics sharing

 Serious compatibility...not serious compatibility problems.

 Several types of author-definable performance optimization

 Stable high resolution graphics even in popups

 Two types of slide show support

 Full ForeHelp interface compatibility

 Background color control

 WAV audio playback directly from baggage

 16-and 32 bit support

 Custom palettes for clean, flexible color control

 No more font size or screen resolution worries

 Up to 100 different 256 color BMP bitmaps or TrueColor JPEGs per topic

 Dynamic or user-defined palette allocation

 Insured compatibility with Windows NT

 Unlimited redistribution rights with Help/Viewer titles

 Special registration features allowing time-limited demos and locked topics

 Uses as little as 40k of disk space

 Bonus features and special gifts

 A self-extracting install creator for Help/Viewer projects

 A 16 bit baggage compression DLL

 No-cost upgrades to registered Graphics Gallery WinHelp graphics libraries

 An optional SHG graphic import filter for graphics software

 JPEG graphic import filtering for your non-hypertext development

All this for a single low price.


ThinHelp includes an integrated version of HelpDebug Lite, one of the most uniquely useful tools ever released for Help authors.  HelpDebug is designed to hunt down errors the Help compiler doesn’t check or won’t report, and provides a wealth of reporting and database functions for your Help projects.  The ThinHelp integrated version of HelpDebug comes integrated into the Push hypergraphics editor and is limited to 16 bit Help only (the full version of HelpDebug supports the additional features of 32 bit Help).

Among its timesaving features are a thorough error reporting function that can tell you what kind of errors have crept into your macros and checks for invalid links in even the largest multi-file Help systems.  Its integration into Push provides you with instant updates and a drop-down list of topic IDs for editing .SHG and .SEG hotspots.


You can’t please everyone, but ThinHelp goes out of its way to help you come as close as possible.  In addition to backward compatibility with all popular Windows versions, it offers author-selectable memory cache control to insure your Help meets the design specifications of context-sensitive Help, enhanced transparent bitmap performance for bitmaps using a plain black background, and -- a real treat for JPEG specialists -- author-definable browser-style” disk-based caching of JPEGs to eliminate decompression delays in subsequent displays of the same JPEGs.


Herd Software Development is serious about supporting Windows NT 3.5x and up in addition to Windows 3.1/3.11.  ThinHelp was developed on the NT platform, so you can count on it behaving itself in 16- and 32 bit Windows versions.


ThinHelp offers conditional bitmap display through its unique application of watermarking technology.  You’ ll see examples of this in the THDEMOS.HLP demo project.

Using IfThenElse() macros and watermark positioning parameters, it is now possible to have conditional 16 and 256 color bitmaps and JPEGs in both 16 and 32 bit Help.  Your conditional bitmaps can even include hotspots.


Registered users of ThinHelp are entitled to a free copy of the Graphics Gallery (for Help Authors) graphics browser and bitmap library for WinHelp.  It’ s a collection of over 3,000 bitmaps and graphical components for sprucing up your Help projects and improving the visual impact of your Help.

Graphics Gallery for ThinHelp is available as part of the ThinHelp CD.  If you received your copy electronically and were never issued a CD, you can receive your copy by email on CompuServe or over the Internet (specify MIME or UUE) or from a special Web page from D:\Mystify Software, the publishers of Graphics Gallery.  You’ ll find a link to D:\Mystify’ s Web site on the Internet Resources for ThinHelp users Web page included as part of your package.


THNHLP.DLL’ s 16 bit version can now interface with Paint Shop Pro, Microsoft Office 16 bit applications, our own FormPad metafile generator, and many other applications offering you the ability to import SHG files directly into your other applications.  No more messing with SHED’ s export function just to edit an SHG graphic.  You can add SHG import yourself or let ThinHelp’ s installation options take care of it for you.

(This function does not allow save-as-SHG at this time, however Push offers many enhancements over SHED which should solve most of your conversion and import/export problems.)


ThinHelp includes an interface DLL for full embedded-window editing compatibility with ForeHelp.  Authoring even the most complex embedded-window functions with ThinHelp becomes point-and-click easy.


Multiple 256 color bitmaps in long topics are no longer a worry...ThinHelp updates the palette every time it encounters a new bitmap in your topic window.  Even use multiple 16 color images using nonstandard Windows palette colors...it’ s as easy as adding GIFs to a Web page.

You can also define your own palettes so that your multiple-bitmap or JPEG topics look the same on the end user’ s system as they do on yours.


HLPLHA.DLL is a unique DLL designed for creative Help and Viewer authors which gives your 16 bit Help titles all the basic functionality of a software installer.  It allows you to use LZH compression to achieve extraordinary reductions in baggage file footprints.  The versatility of this tool might surprise you...it can also extract files from LZH-compressed archives anywhere on the user’ s system, not just in baggage.


ThinHelp gives you complete control over the background color of your helpfile, on a topic-by-topic basis if necessary, in 16 and 32 bit helpfiles.  This feature can be used in conjunction with other ThinHelp embedded windows for a striking range of unique effects.  The Colors button on the button bar of this helpfile is just such an example.


ThinHelp allows you to define one or more LZH-compressed bitmap archives as shared archives for all bitmaps in a multi-file Help or Viewer project and drastically reduce both the end user’ s space requirements and your project management demands.  This feature also allows you to update screenshots in a Help system without changing a single line of RTF source...a boon to developers and users alike.  This essentially gives Help and Viewer the equivalent of their own dynamic graphics libraries.

A note to ForeHelp users: while ThinHelp’ s ForeHelp interface eases the task of authoring embedded window statements, it cannot support ThinHelp’ s graphics databasing features.  This aspect of ThinHelp’ s technology will require manual editing.


The final link in the chain is complete...tiling Web-style textures, known in WinHelp as watermarks, are not merely viable in Winhelp, but available in less memory than you may have thought possible, and with far better performance and precision than the finicky tiled-bitmap effects you may be using now.

Your Help and Viewer titles can look and behave almost exactly like your Web pages, with the advantages of lower system overhead and no special browser.  Frames” effects, hotspotted backgrounds, backdrops that wrap to fit snugly to the Help window, different watermarks for nonscrolling and client regions, even user-selectable watermarks for secondary windows...it’ s all possible.

ThinHelp's watermarking technology differs substantially from that used by other watermarking DLLs, offering you a much higher degree of control over Help’ s look and feel than you’ ve had before.


Your last excuse for not using DLLs in WinHelp just vanished.  At around 70 kilobytes, thanks to its use of ultra-high-speed, ultra-compact assembly language construction, THNHLP.DLL packs more raw power for kilobyte than any Help DLL in its class.  But if you only want 256 color BMP graphics and don’ t need JPEG display in your helpfile, THNBMP.DLL can do everything THNHLP.DLL can do in about half the space.


Create your own custom, depressable buttons from any bitmap ThinHelp can handle, even JPEG and SHG files.  You can use animated icons, or entire animations, as depressable button faces...you’ ll see several examples in the demo project.


ThinHelp is designed to work almost everywhere Help works...from old 80286 dinosaurs to Motorola powerhouses.  SoftPC, SoftWindows, WINE (untested), RISC NT and every standard Microsoft release since 1992.  If it’ s compatible with Windows 3.1 running even in standard mode, and uses a WINHELP.EXE that conforms to Microsoft’ s API, ThinHelp supports it.  One commercial user reports a CD distribution of over 300,000 copies relying heavily on ThinHelp’ s technology without a single complaint about bitmap display or compatibility.


ASETUP is our freeware install creator which uses LZH compression to create compact, fast-installing packages for on-disk and downloadable distribution.  This demo helpfile includes a walk-through for using ASETUP to create a simple installation package for your Help or Viewer title which can even be self-extracting.  It’ s a quick, slick way to solve most of your software update and prototype distribution needs and it’ s right here in this demo at no extra cost.

The freeware ASETUP.EXE version included here, while believed to be reliable and bug-free, is unsupported software and is provided only as a courtesy to our customers and as a thank-you for evaluators of the shareware version of ThinHelp.


Creating slide shows has never been this easy...or this friendly to the end user.  With ThinHelp, you can develop WinHelp-based slide shows from a single-topic helpfile.  Simply place an embedded window statement in the topic, create an LZH archive to hold your full-screen slides”, compile the helpfile and you’ re finished.  You can add slide shows to Viewer titles just as quickly and easily.  All you ever need to distribute is the helpfile and the appropriate ThinHelp or ThinBMP DLL.  No other runtime viewer software is needed, and the compiled, installed project will produce one of the smallest footprints of any slide show and demo technologies.


Beginning with ThinHelp, the ten-embedded-bitmap-per-topic limit is obsolete.  Now you can spruce up your helpfiles with up to one hundred 256 color bullets, icons, separator bars, clip-art pieces and graphic objects from your HTML graphics library as you like, and as many as five hundred frames of animation, lifting your helpfiles to a new level of visual excellence.


ThinHelp achieves its remarkable reductions in file size through the use of tried-and-true LZH (Lempel-Ziv/Huffman) compression, and LHA.EXE, a program developed by Haruyasu Yoshizake to process LZH-compressed archives.  Until PKZIP 2.0, LHA/LZH was actually more effective at compressing data than PKZIP.  Even today it is usually even more effective than ZIP compression in reducing the size of .BMP data, with the added benefit of being free software.

If you distribute electronically or on floppy disk, you’ ll be interested to know that ThinHelp helpfiles take up as much as 20 percent less space than compressed or uncompressed helpfiles when re-compressed for distribution using PKZIP, Diamond or COMPRESS.EXE.


ThinHelp supports transparent bitmaps, allowing you to closely match the look and feel of your Web pages in your helpfiles.  The effect works in both 16 bit and 32 bit Help with none of the limitations or bugs of WINHLP32.EXE’ s new transparency support.

You can even apply transparent color indexes to 256 color bitmaps, animations and JPEGs.  Walk-throughs using screen shots, animated icons and conversion of your animated GIFs for use with Help and Viewer are now a reality, opening up a wide range of new creative opportunities.


Not all help authors realize that compressing text is only part of what takes the help compiler, particularly 16 bit compilers, so long to build a project.  The compiler also compresses bitmaps, and if your helpfile is heavy on screen shots and graphics you could save more than 90 percent of the time you currently spend waiting for helpfiles to compile when you convert your projects for use with ThinHelp.  This added speed can shave whole days off the development time of bitmap-intensive procedural help, especially when developing Multimedia Viewer and Windows 3.1 Help projects.


Some 256 color WinHelp bitmap-display DLLs don’ t permit 256 color graphics in popup topics.  See for yourself how they look.  The demo helpfile provides numerous examples of 256 color embedded window .BMPs and TrueColor JPEG graphics in popups.


ThinHelp and ThinBMP allow you to include your own WAV audio files in compressed bitmap archives added to baggage, further reducing your overhead and helping to keep your help system clean and neat.


ThinHelp includes its own proprietary algorithm for intelligently dithering JPEG graphics on 16 and 256 color displays.  It offers the same versatility with BMP graphics.  Your helpfile’ s appearance is no longer at the mercy of the end user’ s screen resolution.


ThinHelp allows you to define a common 256 color palette for all bitmaps in a given topic, neatly solving the problem of palette conflicts between multiple 256 color graphics and saving you time.  The same palette-matched graphics components you use in your Web site development can now be applied to helpfiles with only a small bit of extra effort.

You can also assign dynamic palettes to JPEG bitmaps, specifying a given number of additional colors over and above the Windows system palette specifically for use by a given bitmap.  Or you can let ThinHelp handle the palette for you.


Even high-resolution JPEG graphics can now be printed from your WinHelp topics from Help’ s Print command.  ThinHelp allows you to define any bitmap you like as non-printable, further enhancing the appearance of your printed helpfile.


ThinHelp lets you define any group of bitmaps (even JPEGs) as an animation sequence and play these bitmaps back as animation frames at virtually any speed.  You can now include the same sort of animated GIFs, Java toys and server-push-style animations you’ ve been using in your Web authoring in your helpfiles, and with no messy pre-processing or filmstripping.  You can even export AVI files to component bitmaps and display them as ThinHelp animations in about the same amount of disk space as compressed AVI...and without the hassles of Video for Windows’  compatibility issues.


Some WinHelp extensions providing high-resolution bitmap support are limited to a safe maximum of 55 bitmap displays total per instance of WINHELP.EXE.  ThinHelp extends this limit to two hundred different bitmaps per topic, many times more than you’ re ever likely to need, and at display speeds comparable to or faster than the best Web browsers.  A single animation window can now handle animations up to 500 frames in length, ideal for all but the most complex animation sequences.


Using Push, the ThinHelp hypergraphics generator, to automatically convert your .SHG files to bitmaps and our proprietary .SEG format hotspot data files will insure the maximum possible reduction in compiled file size.  But if you don’ t want to convert existing SHGs you can add them, completely unaltered, to a ThinHelp compressed bitmap archive and reference them using embedded window statements.  This offers you guaranteed accurate scaling at all screen resolutions and freedom from the scaling distortion associated with printing fixed-resolution SHG files.  You can even use SHGs as watermarks, and ThinHelp will recognize and accurately process all your existing hotspot jumps, popups and macros with no changes needed to the SHG file.

You’ ll also achieve a considerable reduction in compiled file size and shorter waits for the Help compiler.  ThinHelp projects compile up to 90 percent faster than standard Help projects.

In addition, your SHG files can actually be shared by multiple helpfiles thanks to ThinHelp’ s ability to store SHGs in compressed archives located outside of the helpfile.  WinHelp was never able to handle so much data in so little space...and do it so cleanly and accurately.


ThinHelp includes a complete, fully-compatible, high-performance replacement for SHED and MVSHED... a real hypergraphics editor that actually permits 256 color and JPEG graphics with embedded hotspots and macros up to 256 characters, image enhancement filters, scaling, file conversion, and the nicest feature of all, an editing mode that lets you use your favorite graphics editor to edit the SHG’ s bitmap on the fly”.

Web image map graphics can now be transplanted directly into your helpfiles, regardless of their color resolution, with a simple copy-and-paste operation.  Existing SHG files can be edited and pasted directly from the clipboard for true high-resolution Help hypergraphics and be displayed in embedded windows for optimum performance.  You can even attach metafiles to JPEG graphics for crisp, clear banner text and logo overlays, even on 16 color systems.


The first time the registration feature of ThinHelp is used, it adds a registry entry noting the date of installation.  Using simple WinHelp macros you can prompt users for registration of your shareware or demoware, inform clients of pending updates, and display date-sensitive information.  You can even lock the user right out of the helpfile after a specified date.


ThinHelp’ s embedded window bitmap display technology accesses bitmaps compressed and stored in your helpfile’ s baggage.  You don’ t need to include separate LZH archives with your distributed helpfile unless you want to...all you need are the helpfile itself and the appropriate version of the ThinHelp DLL.


A single license to ThinHelp gives you access to all of these features, plus the right to redistribute the THNHLP, THNBMP and HLPLHA DLLs for adding their functionality to your Help and Viewer projects.  If you develop both 16 bit and 32 bit helpfiles, you can distribute the appropriate version for your helpfile.  If you develop software requiring ThinHelp’ s JPEG import filtering facility, you have rights to distribute it for that purpose too.


ThinHelp can act as a JPEG graphic import filter for C++, Visual Basic, Delphi and other compiled languages using the simple API outlined in this helpfile.


The registered ThinHelp includes both 16 bit and 32 bit DLLs you can redistribute with your helpfiles: ThinHelp 16 bit for Windows 3.1/3.11 helpfiles and ThinHelp 32 bit for use in Windows 95 and Windows NT.  The 16 bit DLLs are for use with 16 bit helpfiles and the 32 bit DLLs are for use with Windows 95 and NT.

Your registered-version package also includes two different versions of ThinHelp, one for displaying JPEG graphics and BMPs and THNBMP.DLL, which will display 256 color BMPs and perform all of ThinHelp’ s other functions in a much smaller distributed file size.


ThinHelp is one of the most cost-effective WinHelp extensions and toolkits on the market.  You may want it for only one or two of its features, but we think you’ ll find new uses for it at virtually every stage of a Help or Viewer project.

At just US$169 (DM249) it can replace several DLLs and even save you the cost of upgrading your current authoring tools just to get the features in their bundled DLL extensions.  Browse the ordering information for more details and information about special early-bird discounts.


Getting started
How does ThinHelp handle bitmaps?

This section of the guide walks you through the basics of using ThinHelp to create your first embedded Help or Viewer windows using THNHLP.DLL.

Basic concepts: baggage and embedded windows

ThinHelp and baggage

If you use ThinHelp’s ForeHelp interface and editor, the baggage-handling chores will be handled for you behind the scenes, but you should at least browse this section to get an idea of what ThinHelp needs in case you need to troubleshoot later.  If you’re not a ForeHelp user, there are a couple of concepts you’ll need to understand and a utility you’ll need to create the compressed bitmap files used by ThinHelp.

Very briefly, when ThinHelp encounters an embedded window statement telling it to display a bitmap in your Help or Viewer project, it checks your compiled file’s baggage section for a compressed LZH archive which contains the bitmaps to be displayed.  It then extracts the bitmap from the baggaged archive and displays it in WinHelp as an embedded window.  Embedded window bitmaps don’t look any different from standard Windows Help bitmaps until you begin displaying bitmaps with more than the standard 16 Windows palette colors or with features Help itself doesn’t offer...then they look much different.  Try using an ordinary nonstandard 16 color or 256 color bitmap in a test helpfile to see for yourself.

ThinHelp-compatible display formats

ThinHelp-compatible bitmap formats include standard Windows BMP files, JPEG-compressed, and SHG files (segmented hypergraphics created with SHED.EXE, SHED2, Push or MVSHEDxx.EXE) which have been generated from either WMF-format metafiles or BMP-format bitmaps.

ThinHelp itself cannot process TIF, GIF, PCX, WPG or other graphics formats, but the Push utility included with ThinHelp will quickly and easily convert many graphics formats to ThinHelp-compatible BMP-format bitmaps.

ThinHelp and external LZH archives

ThinHelp doesn’t need to use Help’s baggage file system to store its bitmap archives.  It can also load and display bitmaps which are located in compressed LZH archives stored separately on the user’s hard disk.  This means that these bitmaps can be used by more than one helpfile.  In fact, the same bitmap can be used by two helpfiles in two different windows at the same time if necessary.  Unfortunately the ForeHelp interface supports baggaged graphics archives only if you manually edit your HPJ source files and enter embedded window statements by hand (i.e. without the ThinHelp editor).

Notes, tips and issues

 If you are concerned about people decompiling your helpfile, you can rename externally-located archives to something other than LZH (for example GRAPHICS.DAT or, if you want to be sneaky, something like UTILITY.BIN) to hide the fact that it’s an LZH archive.  Just remember to reference the archive name (and path, if need be) correctly when you enter your embedded window statements into the helpfile’s RTF.  You’ll learn more about path referencing as you progress with ThinHelp.

 Try to limit your LZH archives to a maximum of about 60 files each to improve performance.  If you want truly optimum performance, you can use a 1:1 ratio of bitmaps per LZH archive, although this will usually necessitate extra project management work.

 If you want to avoid LZH files completely, you can add your bitmaps directly to the helpfile’s baggage, much the same way as you would with other embedded-window bitmap DLLs, although your resulting file will be considerably larger in size than the same file using LZH compressed bitmaps.  Direct addition to baggage is reserved for JPEG graphics only and offers a small improvement in display speed when displaying JPGs but very little improvement with BMPs under most conditions.  Here’s a sample embedded window statement for a JPEG added directly to baggage:

{ ewx THNHLP,THIN,!MYFILE.JPG }

 You’ll improve performance if you continue to use BMP or SHG files for standard 16 color Windows-paletted icons and bullets, but you won’t get the advantage of ThinHelp’s transparency or animation features or the reduced file size characteristic of a ThinHelp project.  The more bitmaps per screen that any WinHelp extension -- or even WINHELP.EXE itself -- has to handle, the greater the load on the system.  WinHelp is fastest at handling bitmaps in the normal way, and small bitmaps won’t add too much to your helpfile’s size.  It’s the big bitmaps that eat up disk space.

 When including ThinHelp embedded windows in tables, make sure that the cell size will always be large enough to display the bitmap.  This is especially important with popup topics.  “Overlap” effects possible with ordinary bitmap display may hide your text when attempted with ThinHelp.  You may wish to explore ThinHelp’s watermarking feature to achieve these effects.

 In many cases you can use ThinHelp for every bitmap in your helpfile just as we’ve done with ThinHelp’s own helpfiles, but keep in mind who might use your helpfile.  Graphics-intensive Help might be unpleasantly slow if it’s designed for a network of primarily 386-SX machines.  In cases like these, it is recommended that you try to reduce bitmap palettes to 16 colors.  Even bitmaps with nonstandard 16 color palettes will display more quickly than 256 color bitmaps.


Adding bitmaps to ThinHelp helpfiles
Adding bitmaps to ThinHelp projects

BMP files:

BMP files used with ThinHelp should be packed into an LZH compressed archive which is then placed inside your helpfile by the compiler using the [BAGGAGE] section of the .HPJ or .MVP file.  (You’ll learn exactly how to do this in the next topic.)

SHG files:

SHG files, whether generated from WMF-format metafiles or bitmaps, should be treated the same way as BMP files.

JPG files:

These files can be added directly to the baggage file system of your helpfile without being packed in an LZH archive.  However, if you want to take advantage of any additional ThinHelp features, such as hotspots, watermarking, transparency masking or metafile overlays, you must add your JPEGs to LZH compressed archives prior to referencing them in your project’s source files.

Creating archives

ThinHelp comes complete with the LzSmall archive builder and viewer for quickly creating ThinHelp-compatible LZH archives.  Simply launch it from its shortcut or Program Manager icon (shown at the start of this paragraph) and drag your bitmaps and other files for ThinHelp display onto its window.  But before adding bitmaps to your ThinHelp archive, you’ll need an archive to work with.

Open LzSmall, select File|Open/New and a dialog box will pop up.  To start a new archive, enter the name of the archive file you want to create in the File name: box of the dialog as shown below.  You can use a name other than BITMAPS as your archive’s name, but you must add the .LZH extension as shown here.

For 16 bit Windows...

For 32 bit Windows...

LzSmall will prompt you whether or not to create the archive.  Naturally you will answer “yes” here.  Now you have a new, open archive ready to accept new bitmaps.

To add new files to the archive, simply drag them onto LzSmall’s window.  LzSmall will take care of the -h0 switch, and when you’re finished adding bitmaps you can simply close the program.  Deleting bitmaps from the archive is as simple as selecting the bitmap from the list and pressing the Delete key.

When reopening archives into LzSmall for editing, you’ll need to use the File|Open/New dialog box to select your bitmap archive.  You can’t drag an existing .LZH archive onto LzSmall.

If you use ThinHelp’s ForeHelp editor and interface, this task will be handled for you by the editor.  See the online help for the editor for more information.  If you do not have ForeHelp, you’ll need to handle this chore manually.

You’ll need to take special care when creating your first few LZH archives.  ThinHelp requires the archive to be built using a special switch.  If you’re familiar with LHA.EXE and PKZIP.EXE, you’ll have no trouble with this.  If you’re not familiar with this, use the included LzSMALL archiving software as a starting point.

First load the BITMAPS.LZH archive into your archive handling software (e.g. LzSMALL).  If you use a graphical archive manager, you can simply drag and drop your bitmaps into the archive to build the file...it’s just that easy.  If you use ForeHelp, you can drag and drop files directly onto the Baggage dialog window to create new archives.

Animation frames

Take special care when adding animation frames to your LZH archive.  While ThinHelp will use all frames matching the file specification in the embedded window statement, they will always be played back in the order in which they are added to the archive.  If you modify a frame and refresh the archive later with this new bitmap, your archiving software may assign this bitmap as the last frame in the sequence, even if it was meant to be played in the middle of the animation.

ForeHelp authors can add animation frames to their currently open ThinHelp archive by dragging and dropping bitmaps from Explorer or File Manager directly onto the Files dialog window.  However it is strongly recommended that you keep a backup directory containing all the frames in a given animation in case editing of individual frames is needed later.  It is usually a wise idea to drag each file in the animation back into the archive in the desired display order after editing single frames.

Steps for creating a new bitmap archive

1. Make a copy of BITMAPS.LZH archive in your help project’s directory.  Rename it (e.g. to BITMAPS2.LZH) if you already have an archive of the same name assigned to your project.

2. Open your archive management software and drag the newly-copied LZH file onto its window to open it.

3. Drag and drop the bitmaps you want to embed in your helpfile onto the open LZH contents window of your archive manager.

4. Close the archive manager when you’ve finished building the archive.

Notes, tips and issues

 If you create your own archives, be sure to use the “header level =0” switch in LHA compression.  This switch is specified as -h0.  For LHA.EXE, the syntax for creating the archive is:

lha.exe a -h0 bitmaps.lzh [file1.bmp] [file2.bmp] [etc.bmp]

A sample command might look like this:

lha.exe a -h0 bitmap5.lzh contents.bmp hlpbuttn.bmp myphoto.bmp logo.bmp

If you use a graphical archive manager other than the LzSMALL archiving utility included with ThinHelp (LzSMALL comes preconfigured for ThinHelp), e.g. Winzip or Norton Navigator, be careful to insure that default LHA compression settings include this -h0 switch.  Also remember that subdirectories and pathnames are not permitted in ThinHelp-compatible LZH archives, so the -x switch must either be turned off or configured for use with extraction only.


Referencing bitmaps or archives in ThinHelp-enhanced HPJ/MVP files
Referencing bitmaps or archives in HPJ/MVP files

ForeHelp handling of ThinHelp archives vs. other authoring tools

The addition of archives to the project with the ForeHelp interface is handled automatically when you insert ThinHelp embedded window statements.  You do not need to manually edit your project file.  Other authoring tools will require that you manually add entries to your project file, either by loading the .HPJ or .MVP file into a text editor or by using the tool’s supplied interface for editing/adding [BAGGAGE] entries.

BMP and SHG files:

Your Help project’s .HPJ or Viewer .MVP project file must include a reference to your LZH compressed bitmap archive.  If you use a tool such as RoboHelp, Help Writer’s Assistant or HelpBreeze/ViewerBreeze, the authoring tool may help you add this baggage through a popup dialog.  If not, you will have to enter this information manually in the project’s HPJ or MVP file using a text editor.

Here’s an example from the HPJ file for THINHELP.HLP.  The boldfaced type shows the baggage section and the name of the archive used for this project, BILDER.LZH.

[OPTIONS]

TITLE=ThinHelp...the hypertext edge

[FILES]

THINHELP.RTF

[BAGGAGE]

BILDER.LZH

JPG files:

JPEG-compressed graphics don’t have to be inserted into compressed archives for normal bitmap display (“normal” meaning that no hotspots, metafile overlays or transparency masks are needed).  They can be referenced directly from your helpfile’s baggage section as long as they are listed in the [BAGGAGE] section of your HPJ or MVP file.  To insure that JPEG graphics are included as baggage in your helpfile, copy them to the same directory as your help project and add their names to the [BAGGAGE] list (you can think of it as a baggage “manifest”) as shown in the sample below.

[OPTIONS]

TITLE=ThinHelp Sample Help Project

[FILES]

THINHELP.RTF

[BAGGAGE]

BILDER.LZH
MYPHOTO.JPG
OURLOGO.JPG
PICTURE1.JPG

If you have a large number of JPEGs to add and wish to store them in a subdirectory of your project directory to simplify project organization, you must reference each baggaged file by its relative path.  In this sample HPJ file, the JPEG files are all stored in the \JPEGS\ subdirectory of the main project directory:

[OPTIONS]

TITLE=ThinHelp Sample Help Project

[FILES]

THINHELP.RTF

[BAGGAGE]

BILDER.LZH
jpegs/MYPHOTO.JPG
jpegs/OURLOGO.JPG
jpegs/PICTURE1.JPG

BMPs cannot be added to baggage without first being compressed into LZH archives.  Also keep in mind that when referencing these files in an embedded window statement, you do not use the directory path, but only the filename, since the files will be inside the compiled project, not in a subdirectory of the user’s hard disk.

Notes, tips and issues

 It is important to reference all baggage files in upper-case both within the HPJ/MVP file and in your RTF source documents.  This is especially important with helpfiles which will be compiled with the 32 bit HCRTF.EXE compiler or which may be ported later to 32 bit format.

[BAGGAGE]

MYPICTUR.JPG

OURLOGO.JPG

; unarchived JPEG graphics

BITMAPS1.LZH

; basic graphics

BITMAPS2.LZH

; other stuff added later

ICONS.LZH

; 256 color icon graphics from our Web page

SCNSHOTS.LZH

; screen shots, SEG files and SHG files for the procedural help

; NOTE: you can add comments to your HPJ or MVP file for keeping

; track of multiple bitmap archives.  Multiple archives are recommended

; for helpfiles with more than 60 bitmaps.  The compiler will

; ignore all text which appears after a semicolon in HPJ and MVP files.


Referencing bitmaps in your RTF source

Special information for ForeHelp authors

As soon as ThinHelp has been installed with ForeHelp interface extensions it will be available from the Text|Insert Special menu item.  Click the button to see the menu location for the ThinHelp interface.  Authoring ThinHelp embedded window bitmaps in ForeHelp is as easy as positioning the cursor and selecting the ThinHelp editor.  When you have finished editing your embedded window’s properties, you will usually see the results previewed in the ForeHelp window right away.

Be aware that ForeHelp is not WinHelp.  Don’t be alarmed if there are minor problems with the display of the bitmap within ForeHelp itself or within the topic test window.  You may not know for certain if your embedding worked properly until you actually attempt a compile of this topic or project.

Authoring embedded window statements

The next step is to create references to the desired bitmap in your source documents.  You don’t need to register any new macros with the HPJ or MVP file for this purpose because embedded windows don’t need registration in [CONFIG].  Pay careful attention to this syntax, and copy the sample syntax to the clipboard if you need it.  Also pay attention to the two different methods used for writing your statements.  One method is for bitmaps stored internally, the other for bitmaps stored in separate archives on the hard disk.

If you are using ForeHelp, let the editor author your embedded window statements for you.  Simply position your cursor where the embedded window needs to be inserted, click Text from the menu bar, select Insert Special from the drop-down menu and select ThinHelp from the submenu.  This calls up the ForeHelp editor.

Remember to reference all bitmap archives baggaged inside your Help or Viewer file with a “!” prior to the archive filename, and with no “!” (and preferably “./” preceding any path information) if the archive will be located outside your file on the user’s hard disk.

Referencing bitmaps from baggage

Here’s the correct syntax for the embedded window statement.  Click the individual components of the statement for detailed descriptions if you need them.  Note that commas are used to separate the first three parameters and semicolons are used to separate all parameters following the archive filename.  This sample points to a bitmap located in a compressed bitmap archive stored in the Help or Viewer file’s baggage.

{ ew[x] [MODULENAME or FILENAME], [WINDOWCLASS], [+|!][ARCHIVENAME.EXTENSION]; [FILENAME]; [DISPLAYPROPERTIES]}

Complete clickable syntax reference:

{ ew[x] [MODULENAME or FILENAME], [WINDOWCLASS], [+|!][ARCHIVENAME.EXTENSION]; [FILENAME]; [palette1]/ [palette2]/  [displaytype]/ [advanceinterval]/ [R/G/B];; [MACRO()] }

Sample embedded window statement from this helpfile:

{ ewl THNHLP,THIN,!BILDER.LZH;MAILWRI2.BMP;0/0/0/0/0/255/0 }

The statement just above is the same statement used to embed the 256 color “author” bitmap at the beginning of this topic.  Note that everything after { ewl here is formatted in upper case characters.  It’s not always necessary to reference bitmap filenames in upper case, but it’s a good habit to get into when typing embedded-window statements.

Referencing JPEGs not included in compressed archives

Referencing ordinary JPEG graphics can be done simply by adding the JPEG to baggage (no LZH compression is required in this case) and referring to it directly, as in this example, with the exclamation mark (of course) to indicate that the file is baggaged:

{ ewl THNHLP,THIN,!MYPHOTO.JPG}

ForeHelp authors should note that the ForeHelp editor adds the “!” automatically for you and assumes that all your bitmap libraries will be added to baggage.

Referencing bitmaps stored in external archives

This method requires close attention to path referencing.  If you’ve been referencing paths using methods other than the one described here, you’ll find our recommended method to be both the most reliable and the least confusing and time-consuming.

Sample embedded window statement for the “path” icon above:

{ ewl THNHLP,THIN,./BITMAPS.LZH;PATH.BMP }

 Note that the above statement uses “./” even though BITMAPS.LZH is in the current directory.  This tells Help to look for BITMAPS.LZH in the current directory, the directory containing your helpfile, even if your user is working on whole different drive.  “./” doesn’t need to be used here, but you’ll prevent a lot of potential problems if you get into the habit of adding these two extra characters.

 Also note that a front-slash was used instead of a backslash.  If you replace all backslashes in Help or Viewer path statements with UNIX/HTML-style frontslashes, you’ll find  that it works for directory paths in macros as well, and you’ll only ever have to remember to use one frontslash.  This can save a lot of unnecessary troubleshooting and memory work, since the number of backslashes needed depends on where the path statement is written but the number of frontslashes needed never varies...you only ever need one per drive/directory.

Sample statement for a bitmap in a subdirectory:

{ ewc THNHLP,THIN,./BITMAPS/SCRSHOTS.LZH;FILEMENU.BMP }

The example above shows how you would reference FILEMENU.BMP if it was located in the SCRSHOTS.LZH archive, and this archive was stored in the \BITMAPS\ directory one level below your Help or Viewer project directory.  Note that upper case is used again for everything past { ewc (which must be lower case) and that slashes are used instead of backslashes.


“Path referencing” refers to the method of typing locations of files so that a program, or a process within a program, knows not just the name of the file, but also where to find that specific file on the system.  Absolute path referencing uses the drive and all parent directories located above the file in question.  Relative path referencing uses the current directory as the “base” directory for all subsequent directories in the path.  For example, if you were working in the C:\WINDOWS directory, C:\WINDOWS\SYSTEM\USER.EXE would be the absolute path to USER.EXE, while SYSTEM\USER.EXE would be the relative path.

In authoring Help and Viewer projects, relative paths should use frontslashes instead of backslashes for maximum reliability and ease of authoring, and relative paths should be preceded by “./” to insure that the compiled project will start its search in the directory where the helpfile or Viewer title was installed.


Working with graphics databases

Special information for ForeHelp authors

ForeHelp does not support the use of external graphics databases.  If you want your project to use externally stored archives, you will need to author your embedding statements by hand without the assistance of the ThinHelp editor.

Two options for handling graphics

ThinHelp offers you a choice of how to handle your project’s graphics archives.  You can either include them internally as baggage in your helpfile or store them as separate files outside the helpfile.  How you choose to handle these libraries depends on the needs of your project.

You will want to use internal graphics archives if:

• your helpfile or Viewer title is a single-file title that will not be supported or updated

• you or your clients insist on as few files as possible in the distribution

• you want to hide the existence of these graphics libraries from the end user

You will want to use external graphics archives if:

• you intend to have separate versions of graphics or screenshots for the helpfile (e.g. one set of Windows 95 screenshots and one set of Windows 3.1/3.11 screenshots)

• you want to offer the end user an option to install 256 color or 16 color support graphics

• you are preparing a multi-file project in which the same graphics will be needed by two or more different files

• you want to be able to easily update graphics used in a helpfile without forcing the user to update a large help system or Viewer project

Working with “dynamic graphics libraries”

Externally stored ThinHelp graphics archives behave in a dynamic fashion, allowing you to display the same graphic in two different helpfiles at the same time from one common location on the user’s hard disk.  The only difference between dynamic graphics libraries and [BAGGAGE] libraries is the syntax you use to reference the archive which contains your bitmap.  Viewer authors will recognize this difference instantly: LZH archives stored inside the helpfile or Viewer title are referenced with a “!” in front of the archive’s filename.  LZH archives stored outside the file are referenced without the “!”.  Here are two examples.

{ ewc THNHLP,THIN,!BITMAPS.LZH;MYPICTUR.BMP }

...displays a bitmap included in BITMAPS.LZH which is stored inside the file as baggage.

{ ewc THNHLP,THIN,BITMAPS.LZH;MYPICTUR.BMP }

...displays a bitmap included in BITMAPS.LZH which is stored outside the file.

How ThinHelp finds bitmaps in external archives

ThinHelp depends on proper path referencing when using external bitmap archives.  You can place multiple bitmap archives in an installation subdirectory when using ThinHelp but you must insure that your paths are properly referenced when you create the embedded window statements used by ThinHelp to display the bitmaps.

You should always try to reference the file in a relative fashion rather than an absolute fashion.  For example, when referencing a compressed bitmap archive called SCRSHOTS.LZH located in a BITMAPS subdirectory, you would use ./BITMAPS/SCRSHOTS.LZH rather than C:\SUPERAPP\BITMAPS\SCRSHOTS.LZH or just BITMAPS\SCRSHOTS.LZH.  The “./” (period-slash) tells Help to start its search in the directory where the helpfile was launched regardless of where the user may be working.

This will also save you some brainwork if you author HTML, because the same relative path syntax used in HTML works when authoring Help.  Frontslash path referencing might not work from DOS or Windows command lines, but Help will handle this method quite happily.

Notes, tips and issues

Never use “./” combined with “!” to reference a bitmap archive stored as baggage.  The exclamation is only for use with baggaged archives.

 Either yourself or the person responsible for developing the software’s installation will have to insure that any externally stored bitmap archives are installed to the correct directory or subdirectory.  If a mistake is made in this area, it is highly unlikely that your installed helpfile will display properly.  When in doubt, use internal archive storage using the [BAGGAGE] section of Help or Viewer.

 Some uninstaller and system maintenance tools such as MicroHelp Uninstaller may erroneously report that externally stored LZH files needed by your project may be safely erased by the user.  If you wish to prevent this sort of problem, rename your bitmap archives so they have non-LZH extensions.  For example, BITMAPS.LZH could be renamed BITMAPS.DAT and ThinHelp will still treat it as an LZH archive.  Be aware that renaming your external graphics libraries will require you to change all references to this compressed graphics library in your source documents to reflect the new name.


Compiling and testing a ThinHelp helpfile
Compiling and testing ThinHelp projects

Special information for ForeHelp authors

ForeHelp includes its own error-checking routines which will catch most errors HelpDebug checks for, but HelpDebug is more thorough in some areas.  If you wish to use HelpDebug to check your project for errors as described below, you must first select Build from the Project menu.  You do not need to compile your project.  You only need to build the .RTF and .HPJ source files for HelpDebug to process.

Step by step

1. Run Push and load your project’s HPJ file into it.  This will automatically start HelpDebug and check your project for errors.  HelpDebug will report most of the authoring errors which the compiler reports, and will also check a substantial number of other authoring errors which are missed by all known versions of the Help compiler.  It will provide a much more comprehensive report of errors than the compiler itself, allowing you to insure your project is as close to trouble-free as possible before you run your first test compile.

2. Run HelpDebug again after fixing the reported problems and fix any additional problems you missed the first time.  Rerun HelpDebug as often as necessary to weed out all possible errors.

3. Insure that all needed LZH compressed graphics libraries are in your project’s directory or the directory referenced in the [BAGGAGE] statement in your project file.

4. Insure that the graphics library is referenced in upper case characters in your HPJ or MVP file’s [BAGGAGE] section, with the appropriate path syntax where required.

5. Compile the helpfile.  Fix any additional errors reported by the Help compiler following the compilation.

6. Run the helpfile and check all topics containing your embedded-window bitmaps and ThinHelp macros to insure that your embedded windows display correctly and that your authored jumps and popups are producing the desired results.  Actual build errors should all be discovered by HelpDebug and the compiler...provided you have insured that the compiler will produce an error report.

7. If you discover errors you don’t know how to fix, the troubleshooting section should be able to provide solutions for most of them.  Be aware that a large number of bugs exist in both the 16 bit and 32 bit Help compilers which may produce error messages which are not the result of authoring errors.  As a general rule, if the compiled file looks the way it should look and behaves as you expect it to behave, ignore any compiler errors which you do not understand.

A very important caution

ThinHelp uses sophisticated assembly-language routines to achieve its display speed and multi-modal embedded windows.  This can result in real problems under some situations, particularly in Windows 3.1/3.11 when the Win32s Help engine is used to display 32 bit helpfiles.  Improper use or referencing of ThinHelp macros, particularly in 32 bit helpfiles, may result in unrecoverable page faults, forcing the user to completely reboot the computer in order to regain any control over Windows.  If the user is in the middle of a tutorial procedure, a crash like this could affect the user’s confidence, not just their concentration.  This type of authoring error (a miscoded macro or improper bitmap reference) is unforgivable in a distributed helpfile.

Please...take your “exterminator”’s advice

Please don’t think of the “lite” version of HelpDebug included with ThinHelp as a toy.  It’s a serious debugging tool designed to help you track down and fix a large number of errors that HC31/HCP.EXE and HCRTF.EXE simply won’t report to you.


Once your skills have progressed to the point where ThinHelp becomes an important tool in your authoring toolbox, you will find it vitally important to have the compiler produce an error report after each compile, and preferably store this report on disk as a textfile.

If you use HCW.EXE as an interface to the HCRTF.EXE 32 bit compiler you can configure it to add the appropriate entries to the HPJ file and display the report when the compile is complete.  If you use HC31.EXE or HCP.EXE without HCW.EXE for 16 bit helpfiles, you may need to manually add two entries to your helpfile to produce the error report and specify the level of detail you want in that report.

You should always specify the highest level of error detail (3) and assign a name to your report to match the name of your helpfile.  For example, the appropriate entries for the ThinHelp helpfile might be:

[OPTIONS]
warning=3
errorlog=THINHELP.RPT


ThinHelp and SHG files
Working with SHGs in ThinHelp

Most of ThinHelp’s benefits with almost none of the effort

You probably have projects either in a maintenance or development stage which make use of SHED.EXE-generated .SHGs (segmented hypergraphics).  ThinHelp allows you to store .SHGs in LZH compressed archives and display them as embedded windows, resulting in compiled files smaller than Microsoft's compiler can generate and accurate printing of .SHGs regardless of the screen resolution or font size in use on the target system.

SHGs are referenced in ThinHelp embedded window statements in exactly the same way as .BMPs and .JPGs and are capable of all the ThinHelp display options available to .BMPs and JPEGs, including metafile overlays, transparency masking, animation and use as watermarks or background textures.  ThinHelp isn’t limited to displaying .SHGs that originated as .BMPs either.  It can also display .SHG files created from .WMF metafiles.

Step by step

1. Select an .SHG file for inclusion in your help project.  It doesn’t necessarily need to have hotspot information.  (In fact, if the .SHG was generated from a .BMP and has no hotspot information, you will be able to reduce its space requirement in the compiled helpfile by converting it back to a .BMP and displaying it as an embedded-window .BMP instead.)

2. Add the .SHG file to an LZH compressed bitmap archive.

3. Reference the .SHG in your helpfile’s source document using a standard ThinHelp embedded window statement, or replace the existing { bmx } statement with an {ewx} statement.  Here’s an example.  The normal bitmap syntax...

{ bmc menuscrn.shg }

...could be replaced by...

{ ewc THNHLP,THIN,!BITMAPS.LZH;MENUSCRN.SHG }

And if you wanted to make red the transparent color, you’d enter the statement as...

{ ewc THNHLP,THIN,BITMAPS.LZH;MENUSCRN.SHG;0/0/0/0/255/0/0 }

Notes, tips and issues

 As suggested, you can use the same SHG file in more than one helpfile...but make sure any jumps, popups and macros included in that SHG file point directly to the topic and file, not just the topic.  For example, when MENUSCRN.SHG is shared by both WALKTHRU.HLP and APPWORK.HLP, you will need to reference a jump to the HOW_TO_OPEN_DOCUMENTS topic by the file where it is located.  In this case, let’s assume that this topic ins in WALKTHRU.HLP.  This would mean that the hotspot reference to the topic must be authored as HOW_TO_OPEN_DOCUMENTS@walkthru.hlp so that the jump will execute properly whether the SHG file is displayed in WALKTHRU.HLP or APPWORK.HLP.

 Speaking of using @helpfilename.hlp references, you will often find that complex multi-file systems that “get lost” for no apparent reason will start to perform perfectly again when you start to add @helpfilename.hlp suffixes to all jump or popup topic context strings, even if you’re jumping to a topic in the same file.  Be aware that this type of jump makes HelpDebug’s interfile link checking critically important, since none of the Microsoft Help compilers check the integrity of interfile links.


Adding macros to ThinHelp bitmaps

Special information for ForeHelp authors

Macros are added from the ForeHelp interface using the Pick... button which calls up ForeHelp’s database and pick list of macros.  The ThinHelp macros should be available from this list immediately upon installation.  They are registered with ThinHelp as soon as you install the software and can be found grouped together alphabetically starting with “TH”.  ForeHelp’s interface will automatically check your syntax (be aware that this will not prevent all authoring errors) and ThinHelp will insure that the syntax is corrected for embedded window usage.  The ForeHelp editor will automatically insert the tilde “~” character shown below, which must be used in place of the comma character when commas are required in macros.  You do not need to worry about “~” characters when authoring macros for use in ThinHelp embedded window statements provided you author these macros through the ForeHelp editor.

Hotspotting your embedded windows

You can avoid using Push or SHG hypergraphics altogether if you only want one hotspot, or a “non-segmented hotspot”, assigned to a bitmap.  This type of hotspot is similar to the <a href="http://urldata"><img src="file.gif"></a> type of tagging used in HTML authoring, or “hotspot macros” used with link text or { bmx } statements.  You can use any valid, registered WinHelp macro as part of the embedded window statement and that macro will be executed when the user clicks the bitmap.

If you are authoring from Word or a non-ForeHelp authoring tool, be very careful of the syntax when adding your first few ThinHelp macros.  Macros added to embedded window statements must use a different syntax from normal WinHelp macros.

An example

The sample graphic below would be referenced with this embedded window statement:

{ ewr THNHLP,THIN,!BILDER;WUERZB.JPG;;;PI(`thinhelp.hlp'~`ID_DEMPOP') }

(If you check the source RTF, you’ll see that the filename is referenced as “WUER”, not “WUERZB.JPG” because this particular bitmap requires palette control to prevent palette conflicts with other 256 color bitmaps that might be displayed in the secondary window and the color distortion that usually results from such a conflict.)

Note the syntax: modulename, windowclass, archivename; filename and then three consecutive semicolons -- not one, not two, but three -- before the macro.  The first semicolon after the filename signals ThinHelp that it has parameters to process before displaying the embedded window bitmap.  Since there are no display parameters (numerical parameters), there’s nothing needed after the first semicolon.  So a second and third are tacked directly onto the end of it to signal ThinHelp to prepare to process a macro.  Next comes the macro itself, followed by the closing “}” brace.

Note the “~” character where you would normally place a comma.  This tilde character is used to replace commas in all macros added to ThinHelp { ewx } statements because embedded window statements can’t use commas in their macros.  Embedded-window DLLs each have their own method for replacing commas...some use a colon, some use a plus-sign, and ThinHelp uses the tilde.

Notes, tips and issues

Popup hotspot macros are not supported in ThinHelp and are not recommended for use in 16 bit helpfiles under any circumstances.  To repeat, you can use a PopupID() macro in an embedded window statement in a normal Help window, but you should try to avoid macro hotspots in popup topics themselves.

This warning may come as a bit of a shock if you’ve been successfully using hotspot macros in your popups, but under no circumstances do we recommend using macros in .SEGs, .SHGs or as part of embedded window statements in popup topics in 16 bit Help popup topics.  The associated troubleshooting topic discusses this issue in much greater depth.

Web links or file references that use aliasing characters (the tilde or “~”) cannot be used in ThinHelp macros.  ThinHelp needs the tilde to take the place of the comma, which is not permitted in macros used in embedded window statements.  In order to get a URL with a tilde to work, you’ll need to use the ThinHelp hotspot macro to jump to a secondary window and execute the URL-launch macro from there.

 Be very careful about using compound macros (also known as macro sequences, macro chains or multi-macros) in embedded window statements.  Test them thoroughly before distributing your helpfiles.  Separate compound macros with colons, not semicolons, when using them in ThinHelp embedded window statements.

 If you find that you cannot get your compound macros to work from ThinHelp, use the ThinHelp hotspot to jump to a topic in a secondary window and execute your compound macro as a topic entry macro (also known as a “footnote macro”), and use the last macro in the chain to close the secondary window on completion of all macros needing to be executed.  You can also use this trick to solve problems which arise from using exceptionally long macro strings in 16 bit helpfiles.

 Be sure to use the appropriate HCRTF.EXE abbreviated macro names when authoring macros for use in 32 bit helpfiles.  HCRTF.EXE won’t automatically convert JumpID to JI when it sees your macro in the embedded window statement.


Creating ThinHelp embedded-window buttons

Embedded window buttons are nothing new to Help, and static “bitmap buttons” are standard fare for most experienced Help authors.  Real depressable Windows buttons are available to all authors in Windows Help 4.0, and there are several DLLs available for text and text-plus bitmap buttons in 16 bit Help.  ThinHelp adds a new dimension to button technology in both 16 bit and 32 bit Windows...true bitmap faces up to 256 colors that don’t require editing or multiple bitmaps for “appropriate” appearance.  They can even be animated.

Embedded window buttons can be used to activate any Help macro, even custom macros from other DLLs and WinHelp extensions.  And unlike the behavior of “bitmap buttons”, they don’t react until the user releases the mouse button.  This gives the user the opportunity to back out of an action and makes Help appear a lot less static.

ThinHelp embedded-window buttons have no size limits.  You can turn an entire procedural animation using large screenshots into a giant depressable button if you like.  You’ll probably find this feature most useful for creating action buttons using custom fonts, such as the buttons used in ThinHelp’s help; for iconic buttons of the type used in ThinHelp’s demo browser; and for mimicking the look of the buttons used in your application for more accurate-looking procedural help in your helpfile.

Transparent button faces are not supported

Transparent bitmap buttons are not supported by ThinHelp.  The effect is possible but it produces visible flicker on many types of displays.  If you wish to apply this effect to your buttons, you do so entirely at your own risk.

The ForeHelp editor will automatically reject attempts to create transparent button faces.  If you insist upon using this effect in ForeHelp you will have to edit the embedding manually.

Animated buttons are a supported feature of ThinHelp, but we suggest using a neutral background color for animated icons (192/192/192, or “browser grey”, is recommended) and relatively long frame advance intervals (>200ms) to avoid flicker effects.  Flicker is most likely to occur with large 256 color animations or with JPEG animations applied to button faces.

Advantages and disadvantages

On the negative side...

ThinHelp buttons are not as versatile or as sophisticated in their behavior as ForeFront’s Help Buttons or Help Writer’s Assistant’s OSHTOOLS.DLL.  They won’t completely replace the features you may be getting from these tools.

ThinHelp cannot create plain-text buttons for 16 bit Help that look and feel like Windows Help 4.0 authored buttons.  Ninth Wave Software’s free HLP_CTRL.DLL, downloadable from popular WinHelp FTP sites, will provide this feature for 16 bit Help.

On the positive side...

ThinHelp provides more functionality in this area in less disk space than any comparable DLL available at the time it was released.

This feature can be added to any ThinHelp embedded window by changing a single numerical parameter in the embedded window statement.

The registered version of ThinHelp comes with a special version of the Graphics Gallery (for Help Authors) graphics library which includes several hundred custom-designed button faces ready for use with your Help and Viewer projects.

ThinHelp permits 256 color bitmaps, TrueColor JPEGs, and even animations to be authored as button faces.

And of course the bitmaps used as button faces in your ThinHelp projects can be LZH compressed for maximum space savings in your compiled project.

Steps

1. Create, define and reference a bitmap or animation sequence in exactly the same way you create normal ThinHelp embedded-window bitmaps and embedded window references.  You can also use 256 color icons converted from animated GIFs or disassembled .AVI files (Video for Windows) in addition to your own custom animations, provided you have the right to use these graphics.

2. Define the bitmap as a button using “2” as the third numerical parameter, or as a component of the display properties subparameter.  (If the embedded window is an animation, “2” should be added to the values of other display parameters and the sum of all parameters should be used in place of a single digit to allow multiple display properties.  You’ll learn more about this as you progress through the tutorial.)  For example, the animated calculator uses the syntax shown below.  This example uses a macro which is executed when the button is pressed.

{ ewl THNHLP,THIN,!ANICONS.LZH;CALC; 0/0/3/200;;PI(`'~`BUTTONPOP') }

This example uses an animation parameter, “1”, combined with the display-as-button parameter, “2”, for a total of 3 as the third numerical parameter.

3. Most buttons are designed for Help navigation and have no value in a printout of the Help topic.  If you want to make buttons available in the Help and have the printer ignore these images when printing the topic, add 32 to the total value of the third numerical parameter.

Notes, tips and issues

Embedded window buttons do not function within popup topics in 16 bit Help.  This is a limitation in the design of Help itself.  Buttons will work in 16 bit helpfiles loaded into the 32 bit Help engine, but this applicationuse of ThinHelp’s button feature is not recommended.  Reserve popup-topic buttons for 32 bit HCRTF.EXE-compiled help only.  See the associated troubleshooting topic for more information.

 You can now add a complete “custom font” look to your helpfiles by using bitmaps of the desired text as transparent bitmaps in the nonscrolling region and using smaller text bitmaps in the same typeface as button faces in the helpfile.

 You can achieve a “raised bitmap” effect that looks like a button but does not depress by omitting the macro from your embedded window statement.  This checkmark gives you an idea of how it looks.  It might make a nice framing effect for large bitmaps, but beware of confusing the end user who might expect it to behave as a button.


Transparent embedded window bitmaps
About transparent bitmaps in WinHelp

Special information for ForeHelp authors

ThinHelp’s integrated editor allows you to quickly select the transparent color for your bitmaps through the editor.  If you are using ThinHelp in a project and have normal Help bitmaps which you have preselected using default Help transparency, it is recommended that you add them as ThinHelp embedded window bitmaps and use ThinHelp’s much more reliable transparency technology.  If you are using Graphics Gallery graphics libraries you can determine the appropriate transparent color by clicking the Edit/View button in the Files dialog and examining the bitmap.

The good, the bad and the ugly

Windows 95’s new Help engine supports rudimentary transparent bitmaps in Help, but with some serious limitations.  Firstly, it will only permit the use of 16 color bitmaps.  Secondly, the only allowable color you can specify for transparency is white, which happens to be the most-used color in the standard 16 color palette.  Thirdly, if your user’s display uses a dithered desktop color, the transparency effect will be lost since Help will display the bitmap’s background only as a solid color.  And finally, transparent bitmaps in the nonscrolling region will not display correctly if the scrolling region uses a different background color.

If you’re a Web author or application designer as well as a Help author, you’ve come to expect reliable, high-quality transparency in your work, and limitations like those described above simply aren’t acceptable.  ThinHelp overcomes all of these limitations.

You can now display transparent bitmaps on any color background without worrying about the end user’s choice of screen colors.  You can display transparent bitmaps over watermarks and backdrops, and even use the same transparent color index in your .BMP files as you probably use for most of your .GIF files.  (Most .GIFs use 192/192/192. “browser grey”, as the transparent color, which is a standard Windows color recognized as “maskable” for transparency by ThinHelp.)  And there’s more.

Two types of transparency support

ThinHelp offers two ways to handle transparent bitmaps: color index transparency and masking.  Index transparency defines a specific color in the bitmap as transparent and applies transparency to all regions of the bitmap which use that color.  Transparency masking is the use of a two color (black and white) BMP file which is “overlaid” on the original to produce transparent regions.

Transparent JPEGs are certainly possible with ThinHelp, but the nature of JPEG graphics makes this impractical for most applications.  Transparency masking was developed specifically with the needs of JPEG graphics in mind, and is the method of choice for use with JPEGs.

“GIF-style” color index transparency

This type of transparency works exactly as it does with .GIF graphics, and if you know the color index of the transparent color in your 16 or 256 color .GIFs, you can use the same index color for your ThinHelp bitmap.  Simply convert your .GIF to a .BMP using any common graphic conversion tool (or use an existing .BMP), and add it to your help project as you would any other ThinHelp bitmap.  The only restriction is that the transparent color must be one of 16 standard Windows palette colors.

Special effects

Unlike .GIFs, .BMPs used by ThinHelp don't have to use the same transparent color all the time.  You can declare the text color of your bitmap as transparent in one bitmap, and in the very same topic declare the border or background color of the same bitmap as transparent for two completely different effects.

Transparency masking

This feature will be most appreciated by graphics professionals.  To create a mask, you simply draw a two color (black and white) “silhouette” graphic and apply it as an overlay mask on your .BMP or .JPG file.  What you see at right is an example of this effect using a speech balloon to display only a specified area of a JPEG file.  ThinHelp treats the white regions of the mask bitmap as transparent regions, while the black regions of the mask allow the underlying image to show through.

The nicest features of author-definable transparency masks are their size and speed.  They can be created in seconds using a tool as simple as PaintBrush, and these two color graphics take up only a tiny amount of space in your LZH compressed bitmap archive, typically well under 1Kbyte each.


Creating transparent ThinHelp bitmaps ”GIF-style”
Transparent bitmaps “GIF-style”

“GIF-style” transparency refers to transparency based on a specific color’s index value.  A color index is the combination of the values assigned to the red, green and blue components that make up the color desired as transparent.  This method of authoring transparent bitmaps is primarily intended for .BMP files and generally produces unpleasant results with JPEGs.  It also requires that you know how to find and identify the transparent color you wish to apply.  If you’ve done a fair bit of Web authoring, you should already be familiar with the process of finding and defining transparency indices, but if not, we’ll guide you through the process.

Steps

1. Create your BMP file either using an existing BMP file or by converting a GIF file to a BMP using your usual conversion utilty.  (PCX, TIF or any other valid bitmap format can be converted to BMP format for application as a transparent bitmap.  You are not limited to GIFs alone.)

2. Load the bitmap into your graphics software.  Use the color-picker (also known as the dropper) tool to identify the color of the transparent regions by holding the color picker over a section of the bitmap containing the color you want to use as the transparent color.  In Photoshop, Paint Shop Pro, Photostyler and similar programs, the index of that color will appear in a status bar somewhere on the screen as three numbers separated by commas (e.g. 255,255,255 is white; 0,0,255 is blue; 128,128,0 is olive or earthtone; etc.).

3. The transparent index color must be one of the 16 standard Windows palette colors.  You’ll find a handy reference chart of standard Windows transparencies under THINHELP.HLP’s Tools menu and in the main menu of the reference card helpfile.

4. If the background color you want to use in your bitmap is also needed as part of the image’s content and you want to prevent this content area from being displayed transparently, try one of these two approaches:

a) Choose an unused color from the Windows palette and use it to fill all the background regions and areas you want transparent.  For example, all the backgrounds in the globe animated icon are magenta, since magenta is never used in the animation.  Or...

b) Replace the standard Windows color you want to preserve with a near-match.  For example, in the palette RGB chart, the transparency of the chart was preserved by first expanding the 16 color bitmap to 256 colors, then replacing white (255,255,255) with near-white (248,248,248) and finally filling the background areas with true Windows white (255,255,255).  This allows the near-white to display as the sample white in the swatch.  In most cases you can simply replace one color of a 16 color bitmap without having to increase the color depth to 256 colors.

 The above technique will also work for most converted GIFs that don’t respond to transparency when used in your helpfile as BMPs.  In most cases the problem can be traced to the grey shade being 191,191,191 or 198,198,198, neither of which are acceptable as transparent colors.  Replacing this shade with 192,192,192 will usually solve the problem.

3. Jot down the index value of the desired transparent color in Notepad or on paper...you’ll need it when you write your embedded window statement.
HTML authors: note that ThinHelp, unlike GIF, does not use the index number of the transparent color in the picture’s palette to select the transparency index.  It uses the actual RGB index value of the color itself.

4. Reference the bitmap in your RTF source document, using a full-length seven-item numerical parameter in the embedded window statement.  (ForeHelp users can select from a drop-down list of standard colors.)  Here’s how the checkmark bitmaps in the Notes, tips and issues sections are referenced:

{ ewc THNHLP,THIN,!DATABASE.LZH; CHECKMRK.BMP;0/0/0/0/255/255/255 }

Note that the last parameter uses seven different subparameters separated by slashes.  The last three subparameters are reserved for the Red, Green and Blue values of the transparent color desired for this bitmap.  If you check the transparency chart in the reference card, you’ll see that it’s 255/255/255...255 for Red, 255 for Green and 255 for Blue, which are the maximum values for each of these three hues.  The last three subparameters are reserved exclusively for transparency indices, and if no transparency is needed for the bitmap the numerical parameter should be shortened to omit the transparency subparameters altogether.

Notes, tips and issues

 If you have an animation for which you cannot achieve a satisfactory display speed without producing flicker, the problem could be traceable to transparent bitmaps being displayed on the screen at the same time as the animation.  One possible solution is to use black (0/0/0) as the transparency index for the transparent bitmaps.  ThinHelp has been specially tuned to offer somewhat higher performance when black is used as the transparent color index.  You’ll have to experiment with this to see if it produces a measurable improvement in a given situation.

 If you discover that your specified transparent colors are not displaying as expected (i.e. you have transparent regions where you don’t want them), remember that you have 256 colors to work with and many of them will be close matches.  Simply load the problem image into your graphics processing software, expand the color palette to 256 colors if necessary, and fill the regions where you’re getting unwanted transparency with the closest shade in the available palette.  You may be able to reduce your bitmap to 16 colors again (be sure to select “optimized, no error diffusion”) and retain the same compressed file size and display speed you’d get from a normal 16 color Help bitmap.

 Highly detailed bitmaps may display areas of color near the edges of the graphical content as ugly outlines when the bitmap is displayed with a transparent background.  If you don’t have the skills to manage or eliminate these unwanted outlines using graphics processing tricks, you could try to paint these areas by hand in your chosen background color to achieve a proper transparency effect.  If the result is still unacceptable, add a border or “frame” to the bitmap and display it without transparency.

 Here’s a tip used by creative HTML authors.  If you want to create unusual text flow effects in your layouts that Help won’t permit, why not use small transparent bitmaps for the job?  A 20x1 transparent two color bitmap takes up almost no space in your project and can be used to define precise 20-pixel indents or spaces anywhere in your project.  A 1x20 bitmap could be used to provide the same effect for vertical spacing.

Practical examples

This transparency example uses a single frame of the “Your doorway to the archive” animation as a demonstration.  Note how way the syntax changes for the two transparent bitmaps.

Non-transparent bitmap:
(uses standard ThinHelp statement syntax)
{ ewc THNHLP,THIN,!BILDER;ANI000 }

Gray transparent:
(192,192,192...“browser grey”...used as the transparent color)

{ ewc THNHLP,THIN,!BILDER;ANI000;0/0/0/0/192/192/192 }

Black transparent:
(0,0,0)

{ ewc THNHLP,THIN,!BILDER;ANI000;0/0/0/0/0/0/0 }


Transparent bitmaps using masks

The mask method for defining transparent regions in bitmaps can be used with either JPEG or BMP format bitmaps with equal effectiveness.  It cannot be used to overlay topic text with a blacked-out region.

Steps in the transparency mask method

1. Decide on the bitmap (BMP or JPEG) that you want to use as your transparent bitmap.

2. Load the bitmap into your graphics editing software.  Create a new or duplicate bitmap (.BMP only) of the exact same dimensions as the original.  If the original bitmap was 128 pixels by 64 pixels, the mask bitmap should also be 128x64.  Custom mask sizes can be used but the resulting effect is usually undesirable.

3. Reduce the color depth of the new, blank bitmap to two colors (black and white) and make the entire bitmap either black or white.

4. Use your normal drawing/painting tools to paint in either the non-transparent regions (black) or the transparent regions (white), whichever is easiest.  If you happen to get your colors reversed on the first try, most quality graphics software offers a “negative colors” option for instantly inverting two color bitmaps.

5. Save the mask image to disk.

6. Rename the saved mask image before adding it to the LZH compressed bitmap archive.  It must be named correctly for the effect to work.  If your original bitmap is called MYPICTUR.JPG or MYPICTUR.BMP, the two color mask image must be called MYPICTUR.MSK.  The .MSK extension tells ThinHelp to treat this file as a transparency mask.

7. Reference the bitmap exactly as you would any other ThinHelp bitmap, but leave the extension off of the filename.  ForeHelp authors will need to take care that the File selection string: does not use a file extension.  Using MYPICTUR.JPG as an example, here’s how your statement would look if these files were packed in an archive called BITMAPS.LZH.

{ ewx THNHLP,THIN,!BITMAPS.LZH;MYPICTUR }


Watermarks and background textures with ThinHelp
Watermarks and background textures

  Special information for ForeHelp users

  A different type of WinHelp watermarking

  What ThinHelp watermarks can and can’t do

  The most practical uses: color control and slide shows

  The most obvious use: Web-style background textures

  The most fun use: splash screens

  Steps for using a single watermark in all topics

  Steps for using multiple watermarks in the same file

  Insuring proper color display with watermarks

  The style and position parameter

  Types of ThinHelp watermarks

  Adding hotspots to watermarks

  Watermarks and custom background colors

  Issues with using JPEG bitmaps as tiled watermarks

  Issues with wrap-to-window watermarks

  Notes, tips and issues

Special information for ForeHelp authors

Due to the way ForeHelp’s test function works, it may not be possible to see the results of your watermarking macros without performing a compile.  In order to accelerate the authoring process it is recommended that you either define watermarks as one of the first stages of the project to reduce compile delays or leave watermark testing to late in the project when other features will be tested with the compiled .HLP.

A different type of WinHelp watermarking

If you've seen or used other Help watermarking DLLs, you might discover that ThinHelp won't replace them for every application.  That’s fine...that was never the intent of ThinHelp’s watermark support.  Instead ThinHelp offers its own unique methods of applying watermarks and tiling to Help and Viewer projects.

Embedded windows versus macro-controllable watermarks

Traditionally, Help watermarks have been displayed using embedded window commands.  They may provide a “slicker” look, but the end user can’t control the appearance of the screen, and there are usually few if any author-definable options or facilities for conditional watermark display.

To our knowledge, ThinHelp is the first watermark-capable DLL which allows watermarks to actually be loaded, removed or repositioned on demand.

Scrolling versus fixed-position display

Most watermarking DLLs display the watermark bitmap or tiled texture and maintain the relative window position of the watermark regardless of how you manipulate the window.

When you select a tiling watermark for use with ThinHelp, the tiling can either remain static on the screen (the “traditional” watermark look) or scroll along with the text like backgrounds in most Web browsers.

When you select a positioned, single-instance watermark, it too can be defined to either remain static on the screen regardless of the text display or scroll with the text so that it disappears when the user scrolls the watermark off the screen.

Why scrolling watermarks?

Why scrolling watermarks when the rest of the industry leans to static, embedded-window watermarks?  In our opinion the most important concern is ergonomics.  On many systems, embedded-window watermarks create an endless flickering effect when the topic is scrolled which some users find unpleasant.  We didn’t simply take the easy way out here by allowing them to scroll.

“That flickering was the reason why I created the scrolling technology,” says Bernd Herd, the developer of the technique.  The scrolling technology is actually more difficult to achieve than static watermark effects, and it’s more ergonomically friendly to the end user.

In many ways scrolling watermarks are far less obtrusive than static display watermarks, but many other ways they’re not.  Here’s a comparison chart to help you decide how to define watermarks for your projects.

What ThinHelp watermarks can and can’t do

ThinHelp watermarks can...

 display watermarks either tiled or placed as single-instance bitmaps in any of nine window positions in the scrolling region of the topic, and in any secondary window

 allow the end user to remove or change the watermark at the click of a button or hotspot

 provide for global watermarks that remain in use through all topics, or that display for only one topic

 reduce the space requirements for watermark bitmaps as much as 98 percent (plain color or low-detail...typical size reductions for backgrounds with graphical elements are 60 to 95 percent)

 permit the use of watermark/background graphic features for procedural walk-throughs and slide shows

 wrap the window tightly around a full-window backdrop bitmap, allowing precision pixel-based window sizing without calculating DLL parameters

 allow the end user to select from a menu of background graphic choices which you can supply with the helpfile

 display JPEG backgrounds from your Web site’s HTML pages in your helpfiles with no intermediate modification or conversion required

 display watermarks faster than most other watermark DLLs...ThinHelp paints the watermark as the actual window background itself, not as a bitmap over top of the background

 provide a stock library of over 750 watermarks as starting points for creating your own textures or as ready-to-use watermarks

 let you add hotspots to a background texture or graphic, offering the potential for pane effects never before seen in Help

ThinHelp watermarks cannot...

 support transparency or animation

 be displayed in the nonscrolling region

 allow watermarks to be printed as part of the topic content.  In most cases sections of a watermarked topic printed on anything less than a top-quality color laser printer would be difficult or impossible to read if the topic contained a printable watermark bitmap.

The most practical uses: slide shows and “frame effects”

Slide shows

This application of watermarks is explained and demonstrated at this section of the slide show tutorial.

“Frame effects” in Windows Help

It’s now possible to mimic, at least to a degree, the “frames” look of Web pages in Help using watermarks with hotspots.  The secret is to design a full-window watermark with specific regions for your frame areas and position your text (or preferably bitmaps to avoid scaling problems) within the window so that .BMPs and/or (this is critical) non-embedded-window SHGs appear to “float” in the appropriate area of the window.  Jump topics can be formatted to use the same images to give a framed/paned look to your Help.

The most obvious use: Web-style background textures

Web-style tiling textures are a slightly more complex matter, something you have no doubt discovered if you’ve dabbled with HTML and particularly if you’ve wrestled with Netscape’s 256 color palette.  Mimicking this effect in normal Help involves tedious and tricky table formatting and results in slow display updates.  Windows 16 color textures, even using nonstandard palettes, display blazingly fast and with precise color accuracy with ThinHelp’s help.

256 color textures require careful attention to the palette.  Serious ThinHelp users will eventually want to learn how to manage and match palettes when using multiple 256 color bitmaps.  However, if all your topic bitmaps use the standard 16 color Windows palette, palette-matching should never be a problem and you can be as creative as you like with your backgrounds.

The most fun use: splash screens

Adding splash screens to Help or Viewer projects is a snap with ThinHelp.  Simply define a secondary window which pops up when the helpfile or Viewer title opens, use a bitmap tile or wrap-to-window backdrop bitmap for the watermark, add Push (or SHED) hotspots as needed, and center your welcome text in the topic window.  You can create professional-quality splash screens from Help in five minutes or less.

Steps for using a single watermark in all topics

1. Create an LZH compressed bitmap archive for the texture you want to use.  This archive should contain no other bitmaps.

2. Register ThinHelp’s watermark macro in the [CONFIG] section as shown below:

RR(`THNHLP',`THWaterMark',`UuuUSSU')

3. Add the name and path of the compressed archive containing your watermark bitmap to the [BAGGAGE] section of your .HPJ or .MVP file.  (ForeHelp users can use the ThinHelp interface to create the archive.)

4. Add the appropriate macro to the [CONFIG] section of your .HPJ/.MVP file or use it as a topic-entry macro (also known as a “footnote macro”) in your RTF source document.

Here’s how to reference a “global watermark” bitmap from a sample WATERMAR.LZH archive if this archive is to be included as part of your project’s baggage.  Note that you only need to reference the archive, not the bitmap inside, and that no .LZH extension is needed.

THWaterMark(hwndContext,0,0,coBackground,qchPath,`!WATERMAR',0x0000)

Steps for using multiple watermarks in the same file

1. Create an LZH compressed bitmap archive containing all the textures you want to use.  For speed and simplicity of organization, it is recommended that your watermark archive be used only for watermarks, backdrops and background textures.

2. Register ThinHelp’s watermark macro in the [CONFIG] section as shown below:

RR(`THNHLP',`THWaterMark',`UuuUSSU')

3. Add the name and path of your compressed watermark archive to the [BAGGAGE] section of your .HPJ or .MVP file.

4. Reference your watermark bitmaps using the appropriate topic-entry macros in the topics where you want to display these watermarks.  Here’s a sample macro that displays the tiled logo bitmap from THINHELP.HLP’s BILDER.LZH archive in one topic only:

THWaterMark(hwndContext,0,0,coBackground,qchPath, `./BILDER.LZH;THWATER.BMP',0x0001)

The meanings of the digit values in the last parameter are outlined below.  Note that this macro displays the watermark for one topic only, and this is the preferred method for use in all topics in a multiple-watermark file.  More information is available on this issue in Notes, Tips and Issues.

Insuring proper color display with watermarks

256 color watermarks will require no special handling if they’re the only high-resolution bitmaps in your helpfile, and the only high-resolution bitmaps you expect your user to see for as long as your helpfile or Viewer title is open.  But it’s unlikely that this will be the case in all but the rarest of circumstances.

Windows Help is not exactly sophisticated in its palette handling.  It has to be coaxed into displaying proper color palettes over and above the standard 16 color palette.  For example, switching from a main window topic to a secondary window with a different 256 color bitmap or watermark will result in palette distortion when you switch back to the main help window.  This conflict has to be handled through the use of palette-defining bitmaps in topics using watermarks with nonstandard 16 color palettes, 256 color watermarks or TrueColor JPEG watermarks.

Using palette definition bitmaps with watermarks

ThinHelp will do the coaxing if you provide a tiny bit of incentive.  That “tiny bit of incentive” is a 256 color, 1-pixel-square, transparent embedded window bitmap displayed in the same topic as the watermark.  This tiny bitmap can be positioned so that it never interferes with your layout and is only ever used by ThinHelp to “force” proper palette display for the current window.

Steps for creating watermark palette-definition bitmaps

1. Open the watermark bitmap into your graphics editing software.

2. Reduce it in size to a 1x1-pixel bitmap.

3. Save the bitmap and rename it so that it has a .PAL extension.  (Most graphics software will force you to save the bitmap as a .BMP and rename it later.)  ThinHelp treats files with .PAL extensions as palette definition files, not as actual embedded window bitmaps.  Add the saved .PAL file to a compressed bitmap library.  In most cases your .PAL file will need to be saved to the same directory as the .JPG file with which it is associated, but in the case of watermarks you can store it in any archive in the project.

4. Add a reference to the palette-defining bitmap in every topic where the watermark in question is to be displayed.  If the topic has a nonscrolling region, the .PAL should be referenced there rather than in the scrolling region.  This bitmap will have no effect whatsoever on the graphical layout of your topic.  Here’s how we referenced the palette defining bitmap to insure proper palette handling for the JPEG in the Table of Contents topic:

{ ewc THNHLP,THIN,!BILDER.LZH;TR007.PAL}

The style and positioning parameter

The positioning parameter functions as four separate subparameters.  The parameter is written as 0x[n1][n2][n3][n4] where n1 is the watermark type, n2 is the horizontal position, n3 is the vertical position and n4 is the status of the watermark (global or one-topic-only).  There are no optional digits in this parameter.  You’ll find a watermark positioning chart in the reference card which demonstrates how the parameter should be calculated.

Types of ThinHelp watermarks

Unlike watermark DLLs which use a window class name to define the watermark’s position, ThinHelp uses a numerical macro parameter in the last (seventh) position, offering you the widest range of watermark positioning options available in a Help/Viewer extension.  Here’s a rundown.  (The n stands for a digit that can be author-defined when using this type of watermark, as explained in the first example.)

Tiled watermarks

Tiled watermarks can be displayed in one of two ways: scrolling or nonscrolling.  Scrolling tiles will scroll when the user scrolls the topic.  These watermarks use 0x000n as their style/position parameter.  0x0000 displays a tiling client-region watermark until the next THWaterMark() macro is executed, and 0x0001 displays it only for the topic where the macro is executed.

Nonscrolling tiled watermarks behave much like watermarks provided by embedded window watermark DLLs.  The positions of the tiles on the screen will not change when the user scrolls the topic.  These watermarks are authored using 0x100n as the style/position parameter.  Nonscrolling tiled watermarks function in the client region only.  They are not available in the nonscrolling region.  Note that some flicker may be observable in nonscrollable watermarks when the topic is scrolled.  Generally speaking, the slower the system and the higher the graphic resolution, the greater the degree of flicker.

Full-screen, wrap-to-window backdrops

When a single bitmap is used as a backdrop to the entire topic and no non-scrolling region is needed, 0x200n tells ThinHelp to wrap the window snugly around the watermark bitmap for the cleanest-looking display possible at all screen resolutions regardless of the predefined window size.  This parameter must not be used in the same topic as a window sizing macro.  Use either the auto-sizing (0x200n) parameter or your own specified window dimensions, but not both.

Positioned, single-instance watermarks

Information on this watermark type is displayed just above this subtopic.  Parameter values are listed in the reference card for each of the nine possible positions.

Pane-effect watermarks

Unsupported in this version...you’ll have to experiment with this implementation on your own.  Parameter values are supplied in the reference card.

Adding hotspots to watermarks

ThinHelp watermarks also provide hotspot capability.  You can actually load your watermark into Push, define hotspots, and have areas of the watermark linked to macros.  There are some issues you’ll need to keep in mind when authoring this type of watermark:

 Push-hotspotted watermarks must be handled with care when they occur in or near the same window area as a Push-hotspotted embedded window.  ThinHelp gives priority to embedded windows and will ignore watermark hotspots if two hotspots should overlap.

You can: use hotspotted watermarks in the nonscrolling region and hotspotted embedded-window bitmaps in the client region or vice versa.

You can: use normal ThinHelp bitmaps with macros (e.g. buttons) in the same topic window as watermark hotspots.

You can: use SHED.EXE-generated .SHGs with hotspots provided you are displaying these .SHGs normally.

You can: add hotspots to a tiled watermark...provided you accept the fact that only the top left instance of the tile will contain the hotspots.

You cannot: use standard hotspotted .SHGs alongside hotspotted watermarks when the .SHG is being displayed by ThinHelp.

You cannot: use ThinHelp embedded-window bitmaps with Push hotspots in the same topic area as hotspotted watermarks.  The two types of hotspots cannot overlap.  Be cautious of possible overlap of an SHG or embedded-window button and a ThinHelp watermark hotspot.  One of the hotspots will be lost.  Test your formatting in large and small fonts, in multiple screen resolutions and with manually resized windows to insure that no such overlapping occurs.

Watermarks and custom background colors

THWaterMark() can provide both background color control and watermark support in the same macro for 16 bit helpfiles.  Background color control will most commonly be used in situations such as contents topics where you want both a positioned (usually centered or lower right) watermark and a custom window color to match it, or in watermark-based slide shows where a custom background color such as black might be desirable to “darken the room”, so to speak, for the slides.

Popups normally take their background color from the color of the window where they are called.  Using complex Windows API macro calls to change 16 bit Help background colors (not supported by ThinHelp) or SetPopupColor (32 bit Help) will affect the color of your popups.  Using ThinHelp THWaterMark() macros to change background colors will not affect popup color.

More information on THWaterMark()’s background color control can be found at the topic linked to the help button.

Issues with using JPEG bitmaps as watermarks

ThinHelp allows you to use the same JPEG tiles used in HTML pages as Help/Viewer watermarks, but you should be aware of some of the issues involved in using JPEGs as Help watermarks.

Pay close attention to palettes.  The topic on color palettes and JPEGs contains information for using JPEG graphics in embedded windows, but watermarks can be handled a little more elegantly.  All you need to do is create a palette definition file such as you would for a 256 color BMP watermark and apply it in the same fashion described in the subtopic above.

JPEG watermarks meant for use in the contents topic should probably be cached to the user’s hard disk so that the helpfile will open more quickly after the initial display of the topic.  Use your own judgment about caching other JPEG watermarks.  Information about the caching option can be found in the technical reference at the topic linked to this button.

As a general rule, photorealistic images and highly-detailed raytraces will compress better as JPEG graphics than as LZH compressed BMPs.  Patterns and textures such as those generated by Kai’s Power Tools, Fractal Design Painter or Photoshop will very often compress better if converted to 256 color BMPs, but try saving lower-quality JPEGs from Push first to see if you can get a better result.

Our recommended tool for achieving the best balance of appearance and small file size with JPEG graphics is CJPEG.EXE, a program that runs from DOS.  It provides optimizing parameters unavailable in Windows tools such as Paint Shop Pro or Push, and it’s free software from the same people who developed the JPEG specification.  This button will load the WinHelp Internet Resources page which offers an auto-search link to the Alta Vista search engine which will produce a list of several choices of download locations for this software.

Issues with wrap-to-window watermarks

JPEG decompression time

There are a couple of points to keep in mind when using single-instance full-window watermarks.  The first is JPEG compression.  Decompressing JPEG graphics takes time, and it may be advisable to cache the JPEG to the user’s hard disk so that it will load more quickly once the topic has been displayed for the first time.  CD-ROM installations may need to consider sacrificing JPEG’s TrueColor accuracy (especially when used with photorealistic images) for BMP’s speed when using JPEGs as backdrop graphics.  The difference may be negligible on Pentiums but it could be much more noticeable on 486-DX systems and downright uncomfortable on 386s.  Embedded-window JPEGs, of course, will work like they do in your Web browser...they’ll display topic text first and uncompress the JPEG after the text has appeared on the screen.

Large JPEG watermarks meant for use in the contents topic will almost always benefit from being cached to the user’s hard disk so that the helpfile will open much more quickly after the initial display of the topic.  Use your own judgment about caching other JPEGs.  Information about the caching option can be found in the technical reference at the topic linked to this button.

Topic layout problems

Topic layout needs to be handled carefully with wrap-to-window watermarks.  If the topic scrolls beyond the bottom of the screen, the watermark will scroll as the user scrolls the topic window, resulting in a “filmstripped” appearanced that may be undesirable.

Bitmap size and screen resolution

While you may author at 800x600 or 1024x768 screen resolution, remember that a very large percentage of users never alter their default 640x480 resolution.  If you author a 640x480 watermark into a helpfile using the 0x200n positioning parameter, the results will be less than kind to users of 640x480 systems.  Depending on how the graphics driver handles this situation, the user could see the bitmap as you intended but have no access to Help’s menu or button strip, and thus no obvious way to close the helpfile.  Or they could see part or all of the window borders and controls scroll off the edge of the screen.

Like it or not, Help authors must support 640x480 as the base resolution unless there are specific reasons not to.  This means that you must insure that backdrop graphics don’t take up the entire screen.  Taking into consideration the fact that many users will have large fonts installed or window borders larger than the standard four to six pixels, and the possible need for a scroll bar in the topic, it's usually wise to limit backdrop bitmaps to a safe maximum of about 580x400 pixels.  This will insure enough room on all sides for the window components the user may expect to see.

The Windows 95 task bar

The third issue is the Windows 95 task bar...and this is an issue you can’t easily resolve without additional Help extensions.  At this writing ARSENAL.DLL, a commercial extension, was the only Help-compatible DLL available which automatically moved and resized Help windows away from the task bar.  If the task bar is set to Auto hide, this won’t be a problem, but if it’s set to Always on top and the end user has positioned it at the right or left screen edge, part of your helpfile will be obscured when it is launched.

This is a problem with most applications, not just Windows Help, and we do not recommend that you take any special measures to accommodate the task bar.  You simply cannot know where the user will set the task bar or how thick it will be.  Anyone using a thick left-edge task bar set to Always on top has already learned to live with constantly resizing their application windows.  Your helpfile won’t be any different.

Button wrap

The final issue with wrap-to-window watermarks concerns helpfiles with several custom buttons on the button bar, and this is something you’ll need to experiment with.  There is a possibility that ThinHelp’s redraw routines may not wrap your button bar or resize the window properly when using a long strip of buttons.

In order to insure that your authored button bar displays properly, check the compiled file in both Windows 3.1 large font mode and Windows 95 large font mode to force the widest possible button widths in the most typical situations your project is likely to encounter on target systems.  You may also want to try tests using both the fastest and slowest available test systems to see how a customized, two-line button bar behaves with your watermark.

Notes, tips and issues

 Secondary window splash screens are a breeze to create with ThinHelp.  Simply create a secondary window topic containing your splash bitmap and use either the 0x2001 positioning parameter to “wrap” the window borders snugly around the bitmap or size the window using THWaterMark()’s sizing parameters to create a snug, centered fit.  Use Push to add hotspots to the bitmap if you like.  A single CloseWindow() macro hotspot covering the entire watermark works wonderfully.  Alternately, you can set up a different helpfile altogether as your splash screen helpfile and make it a one-topic helpfile.  The hotspot macro in this case would look more like this one:

EP(`winhelp.exe -i [context ID string of the contents topic] [your helpfile].hlp',0);Exit()

In 32 bit helpfiles replace EP() or ExecProgram() with equivalent EF() (ExecFile()) syntax or the 32 bit Help engine may not execute your macro properly.

 Pay careful attention to bitmap size when creating or converting tiled watermark bitmaps.  The larger the bitmap, the fewer times ThinHelp needs to redraw it, and the faster the topic will display.  Give some thought to who will be viewing your work when determining an appropriate watermark size...large JPEG watermarks on a network of primarily 386 or 486-SX machines are not appropriate.  Large .BMPs may take up more space but will display much more quickly and require far less disk space than cached JPEGs.

 If you plan to use a wrap-to-window backdrop bitmap as your watermark and you want the user to be able to print it, add a clickable link which jumps to a topic where the bitmap is displayed by itself as a normal embedded-window bitmap and recommend that the user print this topic instead of the topic where the bitmap is used as a watermark.

 You can’t guarantee that ThinHelp’s watermark will match the background colors selected by your user.  There is a possibility that strange color schemes could render your topic text unreadable.  If you think this might be a problem, consider converting the topic text for that topic to a transparent bitmap with all text displayed n the desired color and displaying the text content bitmap either as part of the watermark itself or as a sequence of one or more transparent bitmaps.  This effect is often used in promotional Help to produce formatting effects in helpfiles which Help alone cannot achieve.  Simply format the desired topic text in Word, WordPad or Write, use a screen capture program to capture the formatted text, and set the screen-captured text’s background color as the transparent color for the bitmap which you will create from that text.

 If you want to insure accurate watermark control throughout your Help or Viewer title, use THWaterMark() macros with “1” as the last digit of the last watermark parameter for every main window topic in which a watermark will be displayed, even if you have a long sequence of topics using the same watermark.  This will insure that your user sees the appropriate watermark or color even if they jump to a topic from a Windows 95 contents or search tab.

 You may have problems when attempting to combine, for example, a D2HTOOLS.DLL, HDKANIM.DLL or HLP256.DLL watermark in the non-scrolling region with a ThinHelp watermark in the main window.  Generally speaking it is not a good idea to use two textured bitmaps in the same topic anyway, since this can produce a “cluttered” look, but when this is necessary try to use the same DLL for all needed watermarks.


Creating animations from ThinHelp bitmaps
Creating animations with ThinHelp

Special information for ForeHelp authors

Once inserted as an embedding, ForeHelp will display your ThinHelp animations while you author.  This can become extremely annoying.  If you want to work in a less distracting environment, insert place-holder text in the topic at 36 points (or text large enough and colorful enough that you can’t possibly miss it) at the position where the animation is desired.  Replace this placeholder text at compile time with the appropriate embedding.

ThinHelp’s frame animation

ThinHelp doesn’t play AVI or FLI animations.  It’s designed for applications where this type of video is either unnecessary or difficult to distribute.  You’ll probably find it most useful for embedding simple frame-by-frame bitmap animations like the small animated icon shown here.  Animations require a little more authoring and graphical skill than simple embedded-window bitmaps, but the rewards for this effort can be substantial.

ThinHelp frame animations require no “filmstripping” or special preparation.  Any set of bitmaps of the same or similar size can be used as frames in an animation.  They’re not limited in display speed, and frame advance rates well beyond the 30 frames-per-second rate of true full-motion video are achievable even on relatively slow systems.  Frame advance intervals higher than one frame per hour are available for application in slide shows, demonstrations, kiosks and other situations where infrequent frame advance is required.

ThinHelp animations are extremely system-friendly.  Icon animations such as this one display just as smoothly on 386-DX systems as on Pentium Pro powerhouses, which is something you can’t say about the animated GIFs decorating the Web.

Basic animation step by step

This section outlines only the most basic steps to authoring a frame animation sequence in a helpfile.  If you wish to explore this technique in more depth, try out some of the many options described in the section devoted to advanced animation techniques

1. Create or select a series of bitmaps for use as animation “frames”.  .BMP files are recommended for most applications.  JPEGs can be animated for slide shows and presentations but decompression usually takes too much time for comfortable frame advance rates in motion video emulations.

2. Name the bitmaps in sequence.  For example, the frames used in the icon animation in THINHELP.HLp’s contents topic are named WORLD001.BMP, WORLD002.BMP etc. through WORLD025.BMP.  This naming is more for your convenience than ThinHelp’s.  You’ll see in a moment how it simplifies project management.

3. Add all frames in the animation to the same LZH archive.  For the sake of organization and top performance, LZH archives used for animations should contain no other bitmaps.

Take special care when adding animation frames to your LZH archive.  ThinHelp will use all frames matching the file specification in the embedded window statement, but they will not necessarily be played back in the order in which you named them.  Instead they will be played back in the order in which they are added to the archive.  This means that if you modify a single frame and update the archive by copying it back into the existing .LZH archive, your Windows archive shell may treat this modified bitmap as the last file added to the archive, and ThinHelp will display it as the last frame in the sequence even if it was meant to be played in the middle of the animation.  Try a brief test with your preferred archiving shell to see how it responds to having a slightly modified animation frame copied back into the archive.  If it does not behave as you expect it to, configure it to freshen your archives rather than update them when you copy modified frames back into an animation archive.

4. Add the compressed graphics archive to your project’s HPJ or MVP file so it is part of the compiled helpfile or viewer title.

5. Reference the animation sequence in your RTF source by using a partial filename corresponding to the filenames of the animation in the archive.  For example, if your animation sequence files are named, for example, FILE001.BMP, FILE002.BMP, FILE003.BMP etc., you can reference the entire animation in the embedded window statement as FILE and ThinHelp will treat all files whose names begin with FILE as frames in the animation and play them in the order in which they were added to the archive.

Here’s how the animated icon sequence above is referenced in this helpfile:    (0/0/0/0 tells ThinHelp to use default display parameters and /255/0/255 tells it to use magenta as the transparent color.)

{ ewc THNHLP,THIN,!ANICONS.LZH;WORLD;0/0/0/0/255/0/255}

Once again here’s the complete clickable syntax reference for the embedded window statement:

{ ewx MODULENAME, WINDOWCLASS, !ARCHIVENAME.EXTENSION; FILENAME.EXTENSION;; [palette1]/ [palette2]/ [displaytype]/ [advanceinterval]/ R/G/B }

Notes, tips and issues

 As you see above, ThinHelp can also create transparent animations.  If you have GIF Builder, Alchemy Mindworks’ shareware GIF Construction Set or a similar tool for managing animated GIFs, try disassembling an animated GIF and turning it into an animated BMP...with a lot less system slowdown on 486s and 386s than a Web browser will produce.  You can extract the GIF frames from an animated GIF or Java applet for use in your animation, but don’t forget to fill the bitmaps with a proper background color from the standard Windows system palette.  Be aware, however, that ThinHelp animations always take their transparency mask from the first frame in the sequence.  If you have animations where the transparent regions in one frame differ from the transparent regions in the first frame, you should not author this animation as transparent.

 You can configure ThinHelp to play a WAV audio file in conjunction with your animation by executing the THSndPlaySound() macro either from a jump hotspot or as a topic entry macro.  However, you should not rely on ThinHelp to perfectly synchronize the audio to the video.  Voice-overs work well, but synchronizing speech with an on-screen image of the speaker is not likely to produce the kind of synchronization you can achieve with Video for Windows, MPEG or other forms of true A/V technology.

 It is essential that all files needed by a single animation sequence be located in one [BAGGAGE]’d LZH archive.

 Animations are limited to 500 single bitmap frames, which you’ll find more than sufficient for most purposes.

 You can have more than one animation in an archive file (even more than one animation in a topic...although performance drops with each additional animation in a single topic) provided each animation is referenced properly in the embedded window statement.

 Why not convert your existing slide shows to WinHelp or Viewer 2.0 slide shows?  WinHelp slide shows let you distribute “rolling demos” that take up less disk space than virtually any other demo format and require no runtime software other than WINHELP.EXE (which the end user already has) and the appropriate ThinHelp DLL.  Add appropriate controls so that users can speed up or slow down the display and you’ll have all the flexibility you’ll normally ever need.

 Animations can also make use of Push-generated hotspots, although this is not usually desirable in animation sequences since only one set of hotspots can be applied to the animation window.


Animation: advanced techniques

Once you’ve created your first ThinHelp frame animation, you’ll want some control over its behavior and appearance.  Here are several techniques for adding flexibility and pizzazz to animations.  Click the help button at any time for a quick guide to the display properties subparameter.

  Special information for ForeHelp authors

  Altering the default animation speed

  Multiple animations in the same topic

  Looping and play-once animations

  Stopping a looped animation

  The “Replay” hotspot

  Adding a “step-through” scroll bar to animations

  Transparencies in animations

  Defining custom animation sequences

  Faking pauses in the action

  Adding metafile banners to animations

Special information for ForeHelp authors

Due to the way ForeHelp’s topic test function works, it will not be possible to see the results of some of these tips and tricks without performing a compile.  In order to accelerate the authoring process it is recommended that you author interactive animation controls as one of the first stages of the project to reduce compile delays OR leave animation control testing to late in the project when other features are tested with a compiled .HLP.

Altering the default animation speed

There are two methods of defining the frame advance interval, or the speed of the animation.  The method you’ll use most often is to author the frame advance interval into the embedded window statement itself.  But in cases where you want to give control over the advance rate to the end user, or define a single speed for use by all animations, ThinHelp provides the THSetAnimationSpeed() macro for altering the default animation speed used by all animations which do not have a specified speed.

THSetAnimationSpeed()

This macro has only one parameter, a number which is the number of milliseconds between frames.  For example, the demo for this section uses hotspots to generate these two macros:

THSetAnimationSpeed(200): allow 200ms per frame (fast)

THSetAnimationSpeed(2000): allow 2 seconds per frame (slow)

You can preconfigure the default frame advance interval from your .HPJ or .MVP file using the following pair of macros:

RegisterRoutine(`THNHLP',`THSetAnimationSpeed',`u')

THSetAnimationSpeed(n)

...where n is the number of milliseconds per frame you want between frames of animation as the default speed.

THSetAnimationSpeed()’s defined frame advance interval will remain in effect until the next instance of this macro is executed, or unless a different speed is specified in the embedded window statement.  This means it can be used to control the speed of all animations authored without preset speeds.

The following is an example of an embedded window command with no specified frame advance interval.  It will use whatever rate was specified in the last THSetAnimationSpeed() macro.  If no THSetAnimationSpeed() macro is executed, it uses a default 300ms frame advance interval.

{ ewc THNHLP,THIN,!BITMAPS.LZH;DEMO_A}

Author-defined frame advance interval

The embedded window statement reserves the fourth numerical subparameter for the frame advance interval, and the same values used by THSetAnimationSpeed() can also be used for this value.  This subparameter, which is used only by animations, overrides all previous THSetAnimationSpeed() macros.  Keep this in mind, because when you author a specific frame advance interval into the embedded window statement, THSetAnimationSpeed() macros will not function for that animation.

{ ewc THNHLP,THIN,!BITMAPS.LZH;DEMO_A;0/0/0/150}

...has the same effect as using THSetAnimationSpeed(150) as a topic entry macro and authoring the the animation as {ewc THNHLP,THIN,!BITMAPS.LZH;DEMO_A}...but with one exception.  THSetAnimationSpeed() macros have absolutely no effect on animations whose frame advance intervals are authored directly into the embedded window statement.

Multiple animations in the same topic

As mentioned earlier, you can have multiple animations in the same topic, and even have several animations onscreen at the same time, each one playing at a different speed.  The demo menu provides an example of several animations each running at different speeds...and surprisingly enough, all running from within a popup.  Practically speaking, it is not usually wise to embed more than nine animations in the same topic, even small animations, due to the strain this places on Windows resources.

Multiple animation sequences in the same topic might hit a “performance wall” on slower systems as the system attempts to keep up with ThinHelp’s screen redraws.  Newer Pentium machines can probably display two simultaneous 30 frames per second real-motion video clips in frames up to 300x300 pixels in dimension.  80386-SX’s, on the other hand, may produce jerky animations with anything larger than a couple of simple icon animations at the same 30fps speed.

Looping and play-once animations

The default setting for a ThinHelp animation is looping, or continuous-play.  You can also have an animation play once and quit.  Here’s the syntax for the embedded window statement.  The display properties subparameter, “1”, is the one we’re interested in here, and it’s used to tell ThinHelp that this is a play-once animation.

{ ewc THNHLP,THIN,!ANICONS.LZH;world;0/0/1/0/255/0/255)}

Play-once animations always stop at the last frame in the sequence.  They do not return to the first frame the way .AVI animations commonly do.  If you wish the first frame of the animation to be the one the user sees upon completion of the animation sequence, then you must add a second copy of that frame to the archive as the last frame added to the LZH archive.

Stopping a looped animation

This is an unsupported feature of ThinHelp.  Herd Software Development assumes no responsibility if it fails to function to your satisfaction.

There’s no way to actually stop a looping ThinHelp animation once it has started, but there is a work-around solution which might serve the purpose.  As with all work-arounds, it’s a “hack”, and whenever you’re hacking you are venturing into unproven territory.

The trick is to connect hotspot link text or a linked bitmap “button” to a THSetAnimationSpeed() macro whose value is so high that it won’t advance frames until long after the user has left the topic.  THSetAnimationSpeed(900000), for example, will wait fifteen minutes before advancing to the next frame.  By this time your user will almost certainly have moved on to a new topic.  Such a value might be ideal for making an animation appear to have stopped completely.

Drawbacks

This figure should stop most animations within a second or two.  However, if you have already specified a relatively slow animation speed, such as a slide show advance interval of 15000ms, it may take as long as 30 seconds for the animation to actually stop.

Another drawback to this technique is that restarting the animation, or resetting the timer value for an animation in a different topic that depends on THSetAnimationSpeed() macros, might fail.  If you are going to use this technique to stop an animation, we recommend that it only ever be used to stop animations whose frame advance intervals are specified in the embedded window statement, and that you not allow any animations in your project to depend on THSetAnimationSpeed() to define their frame advance intervals.

The “Replay” hotspot

ThinHelp animations that play once and then stop can be replayed by the user by having them click anywhere in the animated window area...provided the animation is not being used as a macro hotspot.  If you add a macro to the embedded window statement, it will take precedence over the replay function.  This is a feature you may want to point out in your topic text.

Adding a “step-through” scroll bar to animations

There will be times when you want to create embedded window animations that look or behave more like slide shows or AVI animations than simple ThinHelp animations.  You may want the viewer to be able to step through several screen shots or slides in sequence without moving to a new topic.  ThinHelp provides you this functionality by displaying an on-demand scroll bar with working scroll buttons at the bottom of the animation window.  They’re no substitute for the full-featured controls used by Video for Windows or embedded .AVI controls but this technique is an elegant solution to many tricky animation display problems.

The scroll bar is created by adding a value of “8” to the sum of all other values used in the display properties subparameter of the embedded window statement.  When the animation is displayed, clicking the scroll buttons moves the user forward or backward a frame at a time, and using the scroll bar itself works just as you might expect.

You will rarely use “8” as the actual display properties subparameter.  Stepping through an animation usually presumes that the animation has stopped.  The effect of a step-through animation which starts at the beginning is is best accomplished using 8 (scroll bars please...) + 16 (start only when clicked) + 1 (play once) for a total of 25 as the third numerical subparameter.  If you use “9” as the subparameter your user will be left with a finished animation and have to scroll back to the start to flip through it an image at a time.

When using “25” as the display properties subparameter you’ll need to resolve the dilemma of an animation that starts playing if the user accidentally clicks the image area.  The easiest way to deal with this is to add a PopupID() or THMessageBox() macro to the embedded window statement which pops up a simple help message for the scroll bars themselves, such as “Click the left and right arrows to advance frame by frame through the animation.”

Transparencies in animations

ThinHelp also allows you to define transparent regions in your animations.  The globe icon on the contents topic, for example, uses magenta (color index 13, or RGB 255,0,255) from the standard Windows palette as the transparent color.  The ThinHelp demo browser provides examples of correct and incorrect use of transparencies in animations.

Be aware that in its present form, ThinHelp won’t be a perfect fit for all your animated icon requirements.  When its transparency feature is applied to animations, it defines a mask region based on the transparent region of the first bitmap in the sequence.  This can result in ugly “shadowing” effects if later frames require transparent regions different from the regions needed for the first bitmap.

This problem may be addressed in an update to ThinHelp (your input on the user survey could make the difference here), but for the time being you will need to insure that transparent animations display properly by testing the helpfile prior to release.  Very often a non-transparent animation with a colored background and a simple black border can be just as effective as a true transparent animation.

Defining custom animation sequences

There may be occasions when you want to use the same bitmaps for more than one animation sequence.  This is a relatively limited function in ThinHelp 1.0 and may not have the versatility you need.  If it doesn’t suit your requirements, let us know what you require in the way of custom sequencing.

ThinHelp allows you to define several specific files, or groups of files, for an animation sequence to be played consecutively.  Unfortunately, at this time you cannot specify the order in which they will be played using embedded window statement syntax.  The bitmaps will be displayed in the order in which they were added to the LZH compressed graphics library, and only one .LZH archive may be specified in the embedded window statement.  The demo animation for this section shows how the same embedded window statement is used to display several icon animations in sequence and demonstrates some of the authoring strategies you’ll need to consider to get it to work.

You can use bitmaps of different sizes in the same custom animation sequence, but be aware that the animation sequence will define its embedded window size based on the dimensions of the first frame in the animation.  If necessary you can use a “Now Playing” or theatre-marquee-style bitmap as the first frame of your animation to insure that an appropriate embedded window size has been defined for all subsequent frames in case the first bitmap in the sequence is smaller than some of the others.

Custom animation sequences cannot define the same bitmap for display at two different points in the animation.  If you need the same bitmap displayed twice at different points in the animation, you’ll need to make a copy of this bitmap, give it a different name and add this copy in the appropriate order to your .LZH archive.

Faking pauses in the action

Pauses in ThinHelp animations can only be generated by inserting additional frames in the animation.  ThinHelp 2.0 doesn’t allow for “control block” style information for timing specific frames the way that GIF animations do.  All frames take the same amount of time.

Let’s assume that you want to make an animation advance at ten frames per second (100ms) but stop for a half-second or so halfway through the sequence.  In order to achieve this effect you would need to create five copies of the bitmap which is displayed at the point you wish to pause frame with the pure white globe and add them to the animation in the proper order for display.  The addition of extra copies of certain frames is how we achieved pause effects in THINHELP.HLP’s globe animation, and for short or iconic animations.

When adding “pause frames” to animations, always keep in mind that ThinHelp processes frames in the order in which they are added to the LZH archive.  If you want to add frames in the middle of an animation and insure that they play in proper sequence, remove all frames from the archive (or start with a new archive) and manually add the frames back in again one at a time.  If you attempt to add all frames at once after creating new frames, your LZH compression software may not add them in the proper sequence, but this behavior varies from program to program.

Adding metafile banners to animations

ThinHelp also allows you to add a WMF format metafile to a Push-generated hotspot which you can display over top of the very last frame of a play-once animation.  This feature could be used for displaying an animated corporate logo or cartoon and having the same animation display descriptive text on the last frame telling more about the product, procedure or section of the project.  You are limited to one .SEG file per animation so if you want to use multiple effects you’ll need to use multiple animation archives or a custom animation sequence.

Metafile overlays on animations are probably most useful with JPEG page-flip animations or slide shows where an overlay will be more effective than actual bitmap data painted on the bitmap.  When authoring .BMP-based animations, you may find it easier to simply paint your overlay information on a copy of the last frame of the animation.

Metafile banners and overlays are activated by adding “4” to the total value of the display properties subparameter.


Display properties subparameter reference

This is the third numerical subparameter.  It is calculated as a word as opposed to the usual single variable.  Options for this parameter include:

0 	loop endlessly

1 	play once

2 	display the bitmap as a depressable button if a macro is included in the embedded window statement or display as raised, nondepressable bitmap if no macro

4 	display a metafile over the last bitmap in the sequence

8 	show scroll bars

16 	start animation by clicking the embedded window

32 	disallow printing for this embedded window (usually reserved for buttons and navigation components)

These can be added together to apply multiple display properties for the same embedded window, e.g. 3 (1+2+32=play once, buttonize and disallow printing), 21 (16+4+1=start animation by clicking, play once, and display metafile over last frame), 24 (16+8=play once and display scroll bars).  Range: any sum of 0, 1, 2, 4, 8, 16 and 32.


Developing slide shows with ThinHelp

  Introduction

  Steps for generating standard ThinHelp slide shows

  An alternative method: watermark-based slide shows

  Adding hotspots to watermark-style slides

  Notes, tips and issues

  Fine tuning

Introduction

ThinHelp makes slide show development a breeze.  After all, when you think about it, what is a slide show except a slow form of animation?  With ThinHelp a single Help topic can serve as the shell for slide show demos, allowing you to construct even elaborate demos with no more difficulty than embedding a normal ThinHelp bitmap or stock animation sequence.  Your bitmap “slides” can be made up of either LZH compressed 16 or 256 color .BMPs or TrueColor JPEGs, offering you the smallest possible compiled file size.  The only things you need to include in the distribution are the helpfile and the appropriate ThinHelp DLL.  Video playback software, proprietary shells and runtime modules simply aren’t needed.

Expect your first ThinHelp slide show to take an hour or two to assemble from an existing set of bitmaps.  Once you understand the process you’ll be able to assemble new slide shows from your own RTF, bitmaps and .HPJ or .MVP templates in as little as ten minutes.

Steps for generating standard ThinHelp slide shows

1. Edit your bitmaps or JPEG graphics as complete slides.  Paint or draw all needed text, circles, pointers etc. right on the bitmaps.  This includes JPEGs since you cannot use separate metafile overlays for different bitmaps.  Animation sequences are only allowed to use a single metafile overlay.

2. Author a simple helpfile with only one or two topics (two if you want a menu or introductory topic, one if you don't).

3. For one-topic helpfiles, use one topic to display your bitmaps with a single embedded window statement of the same type used for displaying animations.  Reference the archive and animation bitmaps accordingly.

4. Create an LZH archive containing your “slide” bitmaps, making sure that they are added to the archive in the order in which you want them displayed.

For optimum control over the behavior of the slide show, it is recommended that you preset the speed of the animation from your embedded window statement using the frame advance interval value in the display properties parameter, instead of the THSetAnimationSpeed() macro.

This sample statement sets up an animation which uses a display speed of one frame every eight seconds, plays once, and starts the animation contained in SLIDSHOW.LZH only when the user clicks in the embedded window region.  (16 for play-once and 1 for start-when-clicked = 17 for the displaytype subparameter.)

{ ewc THNHLP,THIN,!SLIDSHOW.LZH;SLIDES;0/0/17/8000 }

5. Compile the helpfile and test the slide show.  Tweak the frame advance interval to values appropriate for your project, keeping in mind that the more text-heavy or graphically detailed the slide show, the longer the frame advance interval will need to be.

If you want to offer your user some control over the frame advance interval of the slide show, add the following button macros to the HPJ or MVP file.  Click here to auto-copy these macros to the clipboard and follow the guidelines in the demo.

RegisterRoutine(`THNHLP',`THSetAnimationSpeed',`u')

CreateButton(`bstop',`Stop',`THSetAnimationSpeed(900000)')

CreateButton(`bstrt',`Start',`THSetAnimationSpeed(8000)')

CreateButton(`bfast',`Fast',`THSetAnimationSpeed(2000)')

CreateButton(`bslo',`Slow',`THSetAnimationSpeed(15000)')

These macros will register the frame advance speed macro and add four buttons to the button bar to let the user speed up the animation to one frame per two seconds, or stop it by elevating the frame advance interval to a very slow speed setting.  Feel free to edit the frame advance values in these macros to suit the needs of your project, or to add additional hotspots or buttons for even more control over animation speed, but please be aware of the issues and limitations involved in stopping and restarting animations.

An alternative method: watermark-based slide shows

ThinHelp’s watermarking feature offer a unique alternative method for creating slide-show-style presentations in WinHelp and Viewer.  ThinHelp uses macros instead of embedded window statements to create its watermark effects, meaning that you can change the watermark in the current topic simply by having your user click a hotspot.  You can define several hotspots, each of which will display a different bitmap in the area of the screen you have defined as your “slide show area”.

Drawbacks

This technique has one distinct drawback: the bitmap will always display flush to the top, bottom, right or left edge of the topic window with no margins.  You can add a black or white margin area to the individual bitmaps themselves, but you will need to take care that your background colors are not nullified by the application of nonstandard Windows 95 background displays by the end user.  Watermark bitmaps cannot be given transparent regions.

It also has a fairly serious practical drawback: printability.  Watermarks are nonprintable graphics in ThinHelp projects, meaning that the individual frames will need to be displayed sequentially in a different topic if you wish to provide print support for your slide show.

One other thing to watch for is window sizing.  This type of slide show almost always benefits from the use of precision pixel-based window sizing to insure crisp, trouble-free topic window layouts.

One final warning...keep your topic text short.  The watermark will not scroll when the user scrolls the screen, so each time the user’s screen position changes, the next watermark “slide” will position itself based on the appearance of the window at the moment the macro was executed.  Ideally there should never be so much text in a watermark slide show topic that the user has to scroll the topic window.

How to author slide shows using watermarks

Let’s assume for a moment that you want to present a list of available slides in the right half of the topic window and display a series of images on the left.  Here’s how to set up your project.

First, format your topic as a table two columns wide by one row high and set the row alignment to “centered” so that the table resizes itself automatically regardless of the eventual window size.  You won’t need to add anything to the left-hand cell since this cell’s screen area is reserved for displaying the watermark bitmaps.  All your authoring for this slide show will be done in the right-hand cell.

Next, enter your list of available slides in the right-hand cell and provide hotspots for each listing.  Link those hotspots to THWaterMark() macros which have been coded to display the appropriate image (it can be a 16 or 256 color .BMP or a JPEG) left-aligned and centered.  The demo for this section shows how this effect might look in your compiled project and how the macros should be written.

That’s all there is to it...simply add a “Next page” button to the bottom of the topic and you can have your user flip through the helpfile like a paper catalog, displaying several slides per page.

Adding hotspots to positioned-watermark slides

ThinHelp allows you to add hotspots to slides which are intended to be displayed watermark-style, and each watermark bitmap can have its own hotspots.  No hotspots were used in the demo, but you could easily add Push hotspots to your slides to show off product features, zoom in on areas of screen shots or perform other interesting functions.  The hotspots change dynamically, so each time a new “slide” is loaded the hotspots will be updated as they were authored for that individual slide.  You can even use your existing .SHG files for the job if you like without changing a thing...just add them to the appropriate .LZH archive and reference them in the project.

Extra care should be taken to avoid overlapping hotspots when adding hotspots to positioned-watermark slide bitmaps.  The help button leads to more information about these issues, and keep in mind that if you’re using a tiled watermark in the same window as a positioned watermark slide show, you’ll lose the tiled watermark when the user clicks the first slide hotspot.

Notes, tips and issues

 Using the extremely long 900000ms delay time will produce considerable end-user delays if they attempt to restart an animation or change speeds from a THSetAnimationSpeed() hotspot.  You may want to inform your user of this fact through a popup or message box.

 If you have a particularly lengthy text description for a slide, you can “fake” a display of that slide for twice as long as normal by using the same bitmap twice in succession in your animation.  “Fake delay” effects were used in several of the demo animations to produce this effect.

 Be aware that different users will have different screen resolutions.  Be sure to format the paragraph containing the embedded window statement or watermark macro in such away that scrolling will be avoidable at all resolutions.  If necessary ThinHelp embedded window animations can be placed in the non-scrolling region for a “cleaner” look.

 When developing slide shows using THWaterMark() to display slides in a given region of the window, you must take care to size your window so that your text does not overlap too far onto your bitmap display area.  If you want a tightly-fitting display in all screen resolutions, use the window sizing parameters of the THWaterMark() macro to insure proper topic layout at all screen resolutions, keeping in mind that ThinHelp’s window sizing always centers the Help window on the user’s screen.

Fine tuning

For a little extra pizzaz, format the embedded window bitmap centered, make it non-scrolling, and set the color of the window background to black in your .HPJ or .MVP file.  You might also wish to set up the topic window to display full-screen in all resolutions by coding your main Help window as shown below.  (The “1” as the third parameter forces the helpfile to display maximized (full-screen) in all resolutions, and the 0’s as color values result in a pure black Help window, perfect for most slide show backdrops.)

[WINDOWS]
main="Slideshow demo",(100,100,800,800),1,(0,0,0),(0,0,0)

Finally, you can add a touch of class by removing all menu items from the slide show, leaving nothing but the button strip, by adding this set of macros to your HPJ or MVP file’s [CONFIG] section exactly as they are shown here.  This sequence works in both Windows 3.1 and Windows 95.  Click here to copy this macro sequence to the clipboard for pasting into your .HPJ file.

RR(`user.exe',`GetMenu',`u=u')

RR(`user.exe',`GetActiveWindow',`u=')

RR(`user.exe',`DestroyMenu',`u=u')

RR(`user.exe',`SetMenu',`uu')

DestroyMenu(GetMenu(GetActiveWindow()))

SetMenu(GetActiveWindow(),0)


Playing Compressed WAVE-Files from the Baggage
Compressed WAV audio support

WAVE-format digital audio files, usually referred to as .WAVs, are the Microsoft standard file format for digital audio playback in Windows.  These files use a .WAV file extension and tend to be extremely large.  Even the short, noisy DING.WAV system beep included with Windows is a whopping 11k in size.

There is no built-in WinHelp functionality to play WAV audio.  You can access the Windows API directly to perform this function using MMSYSTEM.DLL’s sndPlaySound() command, but this could result in occasional problems especially with larger .WAV files.  Most Help authors who make extensive use of .WAV files in Help eventually discover that ,WAV playback is more stable under more conditions when it’s initiated and controlled by a DLL, even if that DLL does nothing but pass the exact same sndPlaySound() command to MMSYSTEM.DLL that your custom macro is intended to pass.

Advantages of using DLLs for WAV audio playback

Using ThinHelp or another WAV-aware Help DLL for audio playback offers the additional advantage of allowing you to add your .WAV file to the project’s baggage, reducing the number of files in your distribution.  ThinHelp offers the additional benefit of allowing you to compress the .WAV file.  If you use ThinHelp’s dynamic databasing feature you can even have the same compressed .WAVs available to multiple helpfiles in the same Help system.  No modifications to INI files or Windows’ registry are required to enable THSndPlaySound() audio playback.

Be aware that compression ratios for WAV files vary widely.  The sample WAV files. used in the ThinHelp demo browser, for example, compressed by less than 20 percent when added to the .LZH archive.  It’s a significant space savings but hardly spectacular.

Steps

1. Create or specify a .WAV file to include in your helpfile.

2. Add the .WAV file to an existing bitmap archive or create a separate .LZH archive just for sound files.

3. Register the ThinHelp macro for playing the .WAV file in your .HPJ or .MVP file as follows:

RegisterRoutine(`THNHLP',`THSndPlaySound',`SUSSU');

4. Link a THSndPlaySound() macro to the appropriate hotspot or topic in your helpfile.  This table shows how the five parameters are applied in the macro:

Parameter	Type	Description
qchPath	String (S)	Filename of the .HLP or .MVB file containing the .LZH archives in its baggage.
LzhFileName	String (S)	Name of the LZH compressed baggage file containing the .WAV file, for Example “BILDER.LZH”
ArcFileName	String (S)	Name (or the beginning of the name) of a .WAV file contained in the LZH compressed archive file specified in LzhFileName.
fuOptions	DWORD (U)	Option flags.  (These are the same flags used in the Windows sndPlaySound function.)
		0:  Wait until the .WAV file is played before allowing user interaction with Windows (system modal playback) 1:  Do not wait for the .WAV file to be entirely played before allowing user interaction with Windows 9:  Loop the .WAV file (play repeatedly) 16:If another .WAV file is being played, allow it to finish before starting this one.
Here’s how the .WAV file hotspot above was referenced in this example.  This example is “live”...clicking it will play the sound.

THSndPlaySound(qchPath, `BILDER.LZH’,`THINHELP.WAV’, 0)

Notes, tips and issues

 Both the compressed .WAV file from the archive and the uncompressed .WAV file to be played by Windows must be in memory at the same time.  In practical terms, this means that compressed .WAV playback through THSndPlaySound() requires more memory than standard .WAV audio playback.  Try to limit your THSndPlaySound() .WAV files to less than 300Kb when distributing files meant for use on low-powered systems.

 You must have a license to distribute your .WAV file.  You cannot simply copy sound samples from copyrighted CDs or existing software packages.  If you are not sure whether a given sound file is copyrighted, don’t use it.  Either create your own sounds, record your own voice, or find samples you can use or license from a provider of commercial music.

 MMSYSTEM.DLL is the system module accessed by ThinHelp to play sound samples.  Some systems do not have this module installed as a default system driver.  If ThinHelp encounters a system without this DLL, no sound file will play and no error message will be generated.  (No message should be needed unless the sound sample is critical to the topic being displayed.  The end user will already know that they don’t have digital audio playback.)

 The compression rate for .WAV files varies widely.  Eight bit, 11kHz voice tracks and complex musical samples will rarely compress by more than 15 percent.  Some digital sound samples from synthesizers and optimized samples designed for compression can be reduced by up to 70 percent.

 Microsoft supports a compressed audio format, ADPCM (Advanced Delta Pulse Code Modulation), but you will have to insure that the correct driver is installed on the client’s system if you wish to use this type of audio file in your THSndPlaySound() macros.  If they have a relatively new (1994 or later) sound card or Video for Windows 1.1 or higher, then they probably have this driver installed.  But unless you want to use THFileExist() to check for the existence of the ADPCM driver, ADPCM audio is not recommended for inclusion in your ThinHelp projects.


ewx:

Think of this as Embedded Window X(-marks-the-spot).  It has three possible options...the “x” used here and in other Help tutorials simply points out that this can be one of several characters, none of which is an actual “x”.  Here are the three available options.  Click here for a very important caution about embedded window statements.

ewl positions the bitmap to the extreme left of the page or table cell, and text will flow around it.  Use this for bitmaps positioned at the start of paragraphs or for flush-left graphics next to headings.

ewr positions the bitmap to the extreme right of the page, and is most useful for embedding screen shots or diagrams in topics where text should flow around image and to its left.  Whenever embedding a bitmap to the extreme right, remember that you have no margin between the bitmap and the edge of the help window unless you format the paragraph to use a margin.  Add a \ri125 command in your RTF source if you code manually, or indent the paragraph Right: 0.10” if you use an authoring tool, to create an appropriate margin between the bitmap and window edge.

ewc positions the bitmap as if it were a character of text.  It’s the most versatile method of positioning bitmaps.  A bitmap embedded as ewc can be used alone in a paragraph, centered, inserted in a table or at any point in your text.


A caution regarding { bmx } and { ewx } statements

If you’re a Web author first and a Help author second, you probably understand how <img align=> tags function in HTML formatting.  There are two differences to keep in mind about { bmx} and { ewx} statements.

Firstly, whenever you want to create a graphic image flush to the right of a paragraph, e.g. { bmr}, and have text flow around it, you must place your bitmap reference or embedded window statement at the beginning of the paragraph.

Secondly, whenever you position bitmaps flush-right, your bitmap will butt against the scroll bar or window border.  In order to create a margin you must add an indent from the right-hand side of the page of approximately 0.10 inches to create an appropriate margin between the bitmap and the edge of the help window.

Click here to return to the { ewx } explanatory topic.


MODULENAME or FILENAME:

The module name is the internal name of the DLL.  The filename is, of course, the name of the DLL used to create the embedded window.  Which name you use in your embedded window statements and RegisterRoutine() macros depends on which ThinHelp DLL you will be distributing with your helpfile.

For the sake of simplicity and full compatibility, bith filenames and modulenames can be referenced in upper case characters in both the project file and your RTF source documents.  If you choose to use a filename rather than a module name, you do not normally need to include the file’s extension as long as the software is properly installed.

For THNHLP.DLL, the module name required for embedded window statements and RegisterRoutine() macros is THNHLP.  For THNHLP32.DLL the filename is THNHLP32 or just THNHLP.  For THNBMP.DLL the module name is THNBMP and the filename is normally THNBMP or THNBMP32.

  Take special care  with the preparation and installation of your helpfiles if you expect them to be used on Windows NT.  This topic provides an in-depth discussion of possible compatibility issues and recommends ways to prevent or overcome them.


[+|!]ARCHIVENAME.EXTENSION:

This is the name of the LZH compressed archive file containing the bitmap you want to display.  You do not need to use both parts of the filename here provided the file has an LZH extension.  If you wish to change the extension to hide the file’s purpose from users who may have helpfile decompilers, remember to use the whole filename instead of a partial filename (e.g. GRAPHICS.DAT instead of just GRAPHICS or GRAP) so that ThinHelp can find the file.

  Note the semicolon between the archive name and the filename.  This is critical.  You cannot use a comma here...it must be a semicolon.

 Be careful when referencing your bitmaps that you make correct use of the “!” character.  The name of your archive file should always be preceded with “!” (e.g. !BITMAPS.LZH) when referencing an LZH file which will be included as baggage.  The exclamation should be left off if you intend to use the LZH compressed archive as an external graphics library.

Also watch for the use of the “+” caching flag...it’s only ever needed with JPEGs and should never be applied to embedded window references to .BMP files.


FILENAME.EXTENSION:

This is the name of the bitmap file you want to display.  Although you only need to include the first part of the filename (e.g. for OURLOGO.BMP or OURLOGO.JPG you would only need to type OURLOGO), get used to using the full filename if you only want to reference a single bitmap.  This will often save you confusion or “debugging” later, especially with large projects using dozens of bitmaps and options such as masks, .SEG hotspot data files and metafile overlays.  As you gain more experience with ThinHelp you can explore its filename completion capabilities in more depth, but try to focus on stability and consistent authoring while you’re in the learning stage.

This part of the statement is subject to several conditions which you will learn about in the animation, palette and macro-handling sections of the ThinHelp tutorial.  You will often want to omit the extension from the filename to achieve certain effects.


WINDOWCLASS:

DLLs that create embedded windows in helpfiles use a unique “window class” for each type of embedded window they can create.

In the case of THNHLP.DLL or THNHLP32.DLL, you use the THIN class, referenced in upper case, for both bitmaps and animations.

When using THNBMP.DLL in your projects, you’ll use the THINBMP class, referenced in upper case, again for both bitmaps and animations.

  Note carefully...that’s THINBMP with an “I” as the classname, and THNBMP without an “I” as the module name.


DISPLAYPROPERTIES:

ThinHelp permits a number of parameters to be used in the authoring of embedded window statements, among them WinHelp macros, animation speed, palette handling, transparency index, display flags and animation timer speed.  You’ll learn more about these as you progress through the tutorial, but if you’re already familiar with authoring Help/Viewer embedded window statements, consult the display parameter reference for a complete list.


MACRO():

Any valid Help macro, either from Help’s own library of functions or from special macros registered in [CONFIG], can be used here to turn the bitmap or animation into a clickable macro hotspot.

  Note carefully: commas cannot be used in macros in ThinHelp embedded window statements.  Replace all commas with tildes (the “~” character) in your embedded window macros.  If your macro requires a tilde as one of its characters you will have to reference it in some other way.


[R]/[G]/[B]:

These three optional subparameters of the embedded window statement determine which color, if any, will be used as a background or “transparent” color by the bitmap being displayed.  You should always use all three parameters or none at all...never just one or two.  R, G and B stand for [R]ed, [G]reen and [B]lue, the three primary colors of light-generated color.  (Light uses these primary colors, known as hues, whereas colors created by solids such as paint, ink and pencil leading use Red, Yellow and Blue, known as shades.)  Standard CRT (TV-type) monitors use three different electron guns to illuminate the screen, and the amount of energy emitted by each gun is controlled in software by the RGB or Red/Green/Blue values of the pixel, or screen area, being illuminated.  More information on this process is available in the technical reference.

 Be careful when using THWaterMark()...it requires colors to be entered as BGR (blue/green/red) values, not RGB.  If you find yourself having frequent difficulties with BGR and hexadecimal color values, try using the THRGB() macro to translate these values for you from the standard RGB syntax used by Help.


[palette 1]

This is the first of two subparameters used by custom, user-defined palettes.  It is only needed for JPEG bitmap display.  If you are using a .PAL file you won’t need to use this parameter.  ThinHelp ignores this parameter when displaying .BMP files.

A complete explanation of this parameter’s usage is provided in the topic on JPEG bitmap display using custom palettes.


[palette 2]

This is the second of two subparameters used by custom, user-defined palettes, and it is only needed for JPEG bitmap display.  If you are using a .PAL file you won’t need to use this parameter.  ThinHelp ignores this parameter when displaying .BMP files.

A complete explanation of this parameter’s usage is provided in the topic on JPEG bitmap display using custom palettes.


[displaytype]

This subparameter calculates and applies the special properties to be used for the specified bitmap or animation.  It is constructed as a “word”, which means that the numerical values of all the needed parameters are added up to produce a sum total which is entered as the subparameter’s value.  Valid component values for this subparameter include:

0 	loop endlessly

1 	play once

2 	display bitmap as a depressable button if a macro is included in the embedded window statement or display as raised bitmap if no macro

4 	display a metafile over last bitmap in the sequence

8 	show scroll bars

16 	auto-start animation by clicking the embedded window

32 	don’t allow printing of this embedded window... usually used for buttons

Example of a summed parameter: “11” tells ThinHelp that this embedded window is an animation which plays once (1), displays the bitmap frame as a depressable button (2), and adds a scroll bar to the bottom (8).  Combining the three parameters, 1+2+8=11 so “11” is entered as the third numerical subparameter in the embedded window statement.


[advanceinterval]

This subparameter is used only by animations and slide shows.  It controls how rapidly the frames will advance for this particular animation.

The value of this parameter is entered in milliseconds, or thousandths of a second.  A value of 100 produces a frame advance rate of ten frames per second.  A value of 8000 produces a frame advance rate of one frame per eight seconds.

Practically speaking, there is little value in using frame advance intervals below 30ms.  This produces 33 frames per second (33fps) display which is full-motion video.  Rates as high as 9000000 (nine million milliseconds or 2-1/2 hours) have been tested successfully.  High values can be used to mimic “stopped” animation but must be applied with caution and tested thoroughly.

This subparameter overrides any THSetAnimationSpeed() macros.  However, if THSetAnimationSpeed() is activated from a hotspot, button or menu item after the animation has begun playing, the speed defined by the macro will override the speed defined in the embedded window statement, but only when the current sequence or frame has finished playing.  The behavior of interactive speed controls for animations could be erratic if high advance interval values are used so test thoroughly prior to distribution.


JPEG graphics in a popup topic...

This popup shows a JPEG without palette control.


JPEG graphics in a popup topic...

This popup shows a JPEG whose display is controlled by a palette control (.PAL) file.  The .PAL is a small bitmap (usually 1x1 pixels) which has been referenced in the same embedded window statement or topic as the JPEG which it is intended to control and contains an optimized 256 color palette for use with this bitmap.


Dummy macros

 “Dummy macros” are Help macros designed to perform no useful action.  Paradoxically, the fact that they do nothing is precisely what makes them so useful.

Dummy macros are usually intended to prevent another type of action from taking place.  Using a dummy macro in a { bmx} statement, for example, overrides any hotspots in an .SHG, allowing you to display .SHGs as hypergraphic bitmaps in one topic and as non-hotspotted bitmaps in another.

In order to be useful as a dummy, the macro must be virtually invisible to the end user, so that even if the mouse cursor changes to a pointing finger, the macro will appear to have no effect if the hotspot is clicked.  SaveMark(`nul') is a “transparent” macro that can be used as often as necessary, does nothing the average user will ever know or care about, and should never interfere with any other marks or macros you may use in your helpfile.  (How often have you used “nul” as a mark?)


About to launch Help to RTF...

All files in ThinHelp’s help system include complete, uncrippled functionality with our Help to RTF conversion software for allowing you to create Word-compatible documentation from helpfiles including all bitmaps and embedded window objects.  This feature is reserved exclusively for helpfiles included with Herd Software Development software products.  For complete functionality with all helpfiles you will need to own a license to Help to RTF Standard or Help to RTF Pro.

You can use the evaluation version of Help to RTF included in this package to create printable documentation from any of the included helpfiles and optionally load the appropriate helpfile directly into Help to RTF by selecting the Print Some or All Topics... item from each helpfile’s File menu.

Select one of the following:

Launch Help to RTF        Learn more about Help to RTF


HLPLHA.DLL: the solution to "baggage overload"
HLPLHA.DLL: the solution to “baggage overload”

HLPLHA.DLL is a bonus extension DLL included as part of the registered ThinHelp package.  It’s available as a 16 bit DLL only at this time, but even in this form it can solve a large number of Help and Viewer problems and offer far greater reductions in compiled file sizes over normal Help/Viewer baggage in helpfiles compiled with high compression.  HLPLHA.DLL is an unsupported bonus feature of ThinHelp.  Use of this DLL is entirely at your own risk.

Quite simply, HLPLHA.DLL lets you extract files from an LZH-compressed archive stored either on the user’s hard disk or inside the file as baggage.  Cumbersome word processing documents no longer need to take up mountains of disk space in your helpfile prior to use.  Registration key files can be extracted to disk from a baggaged LZH archive by clicking a “hidden hotspot”.  Individual bitmaps may be extracted to disk for use by the end user.  Almost any baggage you need included in a Help or Viewer title can now be reduced by anywhere from 10 to 95 percent in size.

  HLPLHA.DLL step by step

  Notes, tips and issues

  A free tip for unregistered users

HLPLHA.DLL step by step

1. Add the appropriate registration macros to your helpfile.  HLPLHA.DLL requires that the following three macros be added to the [CONFIG] section of your HPJ or MVP file:

RegisterRoutine(`HLPLHA.DLL',`MMHelpFileSystem',`')

MMHelpFileSystem()

RegisterRoutine(`HLPLHA.DLL',`LHAExpand',`SSSUUU')

The first two macros are needed to set up HLPLHA.DLL to use MMYSTEM.DLL as an intermediary between Windows’ file functions and WinHelp’s own file functions.  The second and third macros are WinHelp-specific and should not be used with Multimedia Viewer since they are not needed.  The third is the actual LZH extraction function.

2. Compress the files you want to include as baggage into LZH archives.  Remeber to  use the same -h0 switch that you use for your baggage archives to avoid possible “Broken archive” errors.  Using this switch will also allow you to add ThinHelp bitmaps to the baggage archive if you wish.

3. Add the LZH-compressed baggage archive or archives (you can use as many as you like) to your helpfile’s baggage by listing them in the [BAGGAGE] section of your .HPJ or .MVP file the same way you would with a ThinHelp compressed graphics library.

4. Add the appropriate macros to your project for extracting the compressed, baggaged files.  Here’s the syntax for the extraction macro:

LHAExpand(`[FILENAME.HLP+][ARCHIVENAME.LZH]', `[EXTRACTIONPATH]', `[FILETOEXTRACT]', 3,0,0)

FILENAME.HLP is the name of the helpfile which contains the compressed baggage archive.  This is optional and not needed if the LZH archive is sitting loose on the user’s hard disk rather than stored in baggage.

ARCHIVENAME.LZH is the name of the LZH archive which contains the file to be extracted.  If this archive is located in a subdirectory or parent directory, the path to the appropriate directory is prepended here UNIX-style, e.g. `../ARCHIVENAME.LZH' looks for the archive in the parent directory and `./OTHRSTUF/ARCHIVENAME.LZH' looks for the archive in a subdirectory called OTHRSTUF.

EXTRACTIONPATH is the destination path for the file to be extracted.  This too is referenced using UNIX-style frontslash syntax  If it is to be extracted to the same directory as the helpfile, simply use `./'.  Files can be extracted to floppy disks or other logical drives using the appropriate path syntax for this parameter.

FILETOEXTRACT is the name of the file to be extracted from ARCHIVENAME.LZH. This can either be a complete or partial filename.  A partial filename acts as a wildcard, allowing you to extract multiple files with the same macro.  HLPLHA.DLL does not provide DOS and Windows style asterisk/question mark wildcard character support in this version.

3,0,0: All uses of HLPLHA.DLL in this version require 3,0,0 as the last three parameters.  Additional functionality may be provided for these parameters at a later date.

Here’s a sample macro to show you how HLPLHA works with an LZH file in baggage:

LHAExpand(`THINHELP.HLP+BAGFILES.LZH',`./',`MOREHELP.DOC',3,0,0)

The first parameter is the helpfile which contains the LZH-compressed baggage plus the name of the baggage file.  The second is the path to which you want to extract the file.  The third parameter is the file you want extracted from the archive  This example extracts the file MOREHELP.DOC to the same directory as the helpfile.  The “./” dot-slash is used to insure that the default extraction directory is the same directory where the helpfile is located.

You can extract files from LZH archives sitting loose in the helpfile’s directory by using this syntax:

LHAExpand(`./[ARCHIVENAME].LZH',`./',`[FILENAME]',3,0,0)

In many cases you won’t need to use the RegisterRoutine(`HLPLHA.DLL',`MMHelpFileSystem',`') and MMHelpFileSystem() macros in [CONFIG].  If you only want to access LZH archives sitting loose on the disk, HLPLHA.DLL never needs to access the helpfile’s special internal file structure and RegisterRoutine(`HLPLHA.DLL',`LHAExpand',`SSSUUU') will be the only [CONFIG] macro required in your project.

Notes, tips and issues

 It’s important to reference the baggaged file’s name in upper case characters when entering it both in the [BAGGAGE] section of the HPJ and in the macro to insure compatibility with all Windows versions.

 If you’ve gotten used to using wildcards with your compression commands, remember that they won’t work with HLPLHA.DLL.  You’ll need to use at least a partial filename, even if it’s just the first character, to extract a series of files.  If the series of files have different first letters, you’ll need to use multiple executions of the macro to extract them all.

 If you have compressed archive files sitting in another helpfile, you can extract them “remotely” from the helpfile which is currently open.  Simply use the name of the other helpfile as the first half of the first parameter.

A free tip for unregistered users

This application of LHA.EXE in Help is offered for information purposes only and is neither supported or endorsed by Herd Software Development.

You don’t necessarily need to register ThinHelp if all you want is LZH-compressed baggage.  You can add one and only one LZH-compressed archive as baggage to any helpfile and extract one or more files from it using the free LHA.EXE program.  LHA.EXE has the unexpected ability to treat the entire helpfile as if it was an LZH archive...provided that the LZH archive is the very first file listed in the [BAGGAGE] section.

You can run LHA.EXE from an ExecProgram() or ExecFile() macro, for example EP(`lha.exe -e myfile.hlp mydoc.doc',0) to extract MYDOC.DOC from any LZH file added to MYFILE.HLP’s baggage.  (The filename of the LZH archive is unimportant for this application.)

Just be aware that LHA.EXE is a DOS program, so your user will see a DOS screen executed from a Windows program.  It’s a far less elegant solution than HLPLHA.DLL, but it works.

Also note that “0” should be used as the second parameter in ExecProgram() macros.  “1” will hide the LHA.EXE extraction messages from the user, offering a slicker appearance to the process, but it will not properly alert the user if LHA.EXE encounters any errors.

And finally, while you can distribute LHA.EXE free of charge, you must include a prominently-placed copyright statement which credits the author of the software.  You’ll see an example of a proper LHA.EXE copyright credit underneath the animated globe icon in the contents topic of THINHELP.HLP.


Creating distribution packages with ASETUP

Installation packages in five minutes

ThinHelp comes complete with a special script you can modify in minutes to create simple, serviceable, ultra-compact installation packages for disk-based or downloadable distribution.  Simply follow the steps, edit a copy of the APPSETUP.INF file found in \ASETUP\ subdirectory of your ThinHelp installation to suit your project, and in minutes you can develop reliable installation packages for your Help or Viewer titles.  Click here to view or edit this file in Notepad now.

The freeware version of ASETUP included with ThinHelp is provided as a courtesy.  Support for ASETUP is not included with your ThinHelp license.  Support for ASETUP is available only with a paid license to the Witch. the drag-and-drop installation workshop for ASETUP.

Asetup installations step by step

1. Decide which files to include in the distribution.  All you may want to include is a single HLP file and the appropriate version of the ThinHelp DLL.  Icons, executables, additional documentation and software components are entirely optional.

2. Add these files to an LZH archive called INSTBIN.LZH in the same way you create LZH-compressed graphics archives for your ThinHelp projects.  (See the sample APPSETUP.INF in the \ASETUP\ directory for more details about INSTBIN.LZH.)

3. Copy APPSETUP.INF, INSTBIN.LZH, SETUP.LZH and SETUP.EXE from ThinHelp’s ASETUP subdirectory to a fresh directory where you can work on the installation.

4. Load APPSETUP.INF into Notepad.  Follow the comments there and edit the appropriate entries to create your own installation.  Try the sample installation in the \ASETUP\ subdirectory to see how it looks.

5. Test your installation.  If you miss a period or a quote somewhere, or forget to change an entry in APPSETUP.INF, you’ll see the results when you try a test installation.

6. a) For electronic distribution, compress APPSETUP.INF, SETUP.EXE and SETUP.LZH into a new ZIP archive using Winzip, PKZIP or a similar tool, and you’re done.  (LZH archives are not recommended for electronic distribution.  ZIP is the current standard.)

b) For disk-based distribution, copy APPSETUP.INF, SETUP.EXE and SETUP.LZH to a master floppy disk and you’re done.

Self-extracting, self-starting installations

If you distribute your help systems, Viewer titles or other software over the Internet, you’ll really appreciate this feature of ASETUP.  It gives you the ability to create self-extracting, self-starting, Win95-compatible installations from your working ASETUP distribution packages with just two more simple steps.

It is vitally important that you first insure that your install script is functioning properly.  Do not attempt to create self-extracting install packages until you have thoroughly tested the install script.  Once you have tested it ands insured that it performs as you expect, here’s how to turn your installation package into a self-extracting, self-launching installation archive:

1. Copy the INSTBIN.LZH archive containing your install files and your APPSETUP.INF file into SETUP.LZH.  (That’s right, pack your custom-built LZH file and installation script right inside the supplied SETUP.LZH file.)

2. Drop to DOS or use a Windows prompt that permits DOS commands, change to the directory containing your setup project files and type this command at the DOS prompt exactly as shown here:

copy /b setup.exe+setup.lzh setupb.exe

3. Rename setupb.exe to whatever you like, remembering to keep the .EXE extension.  For the “Real Help” sample project, you’d probably want to call it realhelp.exe.

4. Test the installation by running your new, renamed .EXE file.  If your previous installation worked, this should too.

Notes, tips and issues

 Try to follow the sample APPSETUP.INF file as closely as possible for simple installations.  It can assist you to your first successful installation in less than ten minutes, even if you’ve never written an install script before.

 You cannot add subdirectories to the INSTBIN.LZH archive.  You may add individual files or additional LZH archives, but LHA.EXE archived subdirectory support is not available in this version of ASETUP.

 If you’d like a little more control over your installation or a more professional look and feel to your installer’s “splash screen”, download the latest version of the full ASETUP package from CompuServe, Winsite, or from links at the Herd Software Development home page.  ASETUP can add transparent bitmaps to the opening screen, write registry information, create multiple-disk installations and much more...the APPSETUP.INF file included here shows off only a few of its features.


Graphic import filtering is no longer available

First make sure you are attempting to use this feature in the right manner.  If you just upgraded to Windows 95, THNHLP.DLL will not function as a graphic import filter for your 32 bit applications.  It is a 16 bit filter and only functions with 16 bit applications or 32 bit applications that support 16 bit MS Graphic Import filters.

If filtering was available and has suddenly disappeared, either your THNHLP.DLL file has been moved or erased, or your WIN.INI entry pointing to this file has been altered.

To install THNHLP.DLL as a graphic import filter for 16 bit applications, insert an entry in the [MS Graphic Import Filters] section of WIN.INI (you cannot use the registry for this job) which reads as follows, insuring that a copy of THNHLP.DLL exists at the location specified.

Segmented Hypergraphic(.SHG)=[drive]:\[path]\thnhlp.dll,SHG

You must close your currently open application and reopen it for the change to take effect.  Windows will not update import type lists in open applications.


The selected transparent color will not display transparent
The selected transparent color will not display transparently

This problem is usually caused by an incorrect guess” at the transparent color of the bitmap, a transparent color index which is not the exact index of the transparent color you specified, or incorrect macro coding.  Here is a checklist to guide you to a solution to this problem.

 Improper syntax: First things first...have you thoroughly checked the embedded window statement syntax?  This should never be a problem with the ForeHelp interface, but if you are coding your embedded window statements manually you are likely to make occasional errors.

 Invalid transparent color: This is most likely to occur when converting Web GIFs to transparent ThinHelp BMPs, and the usual culprit is grey.  There are three common grey shades in use as GIF transparent shades: 191/191/191, 192/192/192 and 198/198/198.  Only the second, 192/192/192, is a valid shade for displaying transparently with a ThinHelp embedded window bitmap.

This error could also occur if you used an optimized color reduction in Push or another graphics processor.  Check to make sure that the desired transparent color is the actual background color of the bitmap and not just a close approximation.  Close isn’t good enough...it has to be exact.  If necessary, fill the background regions with a shade you know is compatible with ThinHelp (0/255/0 or lime green is usually a good choice for converted GIFs and PCXs and also works for most BMPs).

 Bad guess: Load the bitmap into your favorite graphics processing software and use the dropper or picker tool to find out the exact index value of the background color.  You should see the color index in the program’s status bar at the bottom of the window as you pass the dropper over the desired color.  Be sure to move the dropper around a little in the background region to insure that you are not just checking the color of one pixel.  Sometimes your bitmap’s background will be dithered to many nearly identical variations of the same color.  (If this should be the case, you may have little choice but to take the time to undo the dithering or display the bitmap non-transparent.)


Troubleshooting embedded window problems
Topic displays Unable to display bitmap” error or black spot

There are many possible causes for this problem.  Here are the most common:

 Improper syntax.  Solution: check the syntax for your embedded window statement.  Does it follow the conventions required by ThinHelp for the type of embedded window you want to display?  Be especially careful of the placement, and the number, of colons and semicolons.

 RLE-compressed .BMPs.  If you’re sure that your embedded window syntax is correct and the embedded window reference is not used in a table, then you have probably inherited an RLE-compressed bitmap and tried to display it as an embedded window.  RLE-compressed bitmaps import beautifully into Push, but they’re not compatible with the ThinHelp DLLs.  Load the bitmap into Push and save it, unaltered, as a .BMP using Save Picture As... to find out for sure.  If the saved file is larger than the original .BMP, you more than likely tried to embed an RLE-compressed bitmap without realizing it.  If there is no change in file size, try repacking the saved file into the LZH archive and recompiling anyway.  There may have been a bogus byte” somewhere in the file and the load-and-save operation could have repaired it.

 Improper spelling.  Does the bitmap exist in your project as you spelled it in the source?  If so, did you get the spelling of the other parameters correct?

 Low system resources (especially Windows 3.1/3.11).  Solution: restart Windows or shut down other graphics-dependent software.  Office-type applications are notorious resource hogs.  If resources were low the bitmap will display properly on restart.  This is a problem with Windows itself and occurs even in normal helpfiles when the system is overstressed or critical areas of memory are fragmented”.

 DLL not in helpfile directory.  The ThinHelp DLL used to display the embedded windows must be visible to Windows Help.  It should be placed either in the helpfile’s directory or, less preferably, in the \WINDOWS\ or \WINDOWS\SYSTEM\ directory.  If you plan to use a different directory, see the section on cross-version compatibility for tips on how to deal with this with the least possible inconvenience to yourself and the end user.  Note that the ThinHelp setup will install the DLLs in a way that you should never have to worry about their locations while you are authoring, but you must include the appropriate DLL(s) in your distribution.

 Improper table formatting.  When inserting ThinHelp-embedded bitmaps into tables, make certain the cell is large enough to show the bitmap.  If you use Word, import the bitmap directly into the RTF source document, resize the cell border to fit properly, then delete the bitmap and add your { ewx } statement.

 The -h0 switch was not preserved in the LZH file.  There are rare cases in which the needed -h0 switch is not preserved when you update your archive using a graphical Windows archive shell such as Winzip.  In cases like this you will need to use Haruyasu Yoshizaki’s LHA.EXE for the job and create your archive manually in DOS using the syntax shown below.  See the topic on referencing bitmaps for more information.

lha.exe a -h0 bitmaps.lzh [file1.bmp] [file2.bmp] [etc.bmp].

 Wrong module in memory.  You may experience strange effects if you run more than one version of ThinHelp on your machine at one time.  If you installed a Beta version of a future ThinHelp release and you want to return to your old version, you may have to rerun the setup.  Be aware that these effects are highly unlikely to be reflected in compatibility issues with future versions of ThinHelp.


Bitmaps or animations in formatted tables won’t display

If you’ve already checked your syntax, chances are you’ve run across a bug in embedded  window handling by WinHelp both in 16 bit and 32 bit helpfiles.  This problem occurs if certain types of formatting follow one another, and it is not consistent, meaning these bitmaps may appear at some times and not at others.

There are two fixes for this problem, one quick-and-dirty, the other clean and a little more complex.

Solution 1: quick and dirty

Part of the problem stems from having { ew as the first characters in the paragraph. Remember you’re dealing with bitmaps here, and it’s not always critical to have absolute flush-right alignment.  Simply add a space to the start of the paragraph and reduce that space to one-point text.  You’ll have a tiny one-point indent and your missing bitmaps won’t be missing any more.

Solution 2: clean and fiddly

Change your paragraph formatting in all locations where bitmaps go missing. If you use { ew as the first characters in the paragraph and the paragraph below uses a different spacing, then a bug in WinHelp will cause the graphic to get lost.  Change the paragraph spacing of the previous paragraph to be the same as the paragraph with the embedded window statement.

In troubleshooting this bug, we discovered a unique effect you might want to try, and a bug you should watch out for.  The one-point space works fine for correcting table formatting problems, but if you later do a style conversion and the space gets enlarged to, say, ten points, 16 bit Help will start the display of your left- or right-aligned bitmap on the second line of text, not the first.  It’s a neat effect, but it might also be unwanted in your authoring.


Statement and macro templates copied from ThinHelp helpfiles won’t paste properly

These templates are designed primarily for use with Word-based authoring tools.  Word accepts these pasted strings but your authoring tool may not.

ForeHelp users should use these template strings as examples for working with the ForeHelp interface.  The status bar at the bottom of the interface window will give you an exact readout of the string you are authoring so you can compare it to the template example.  (Naturally it won’t have the parameter cues” enclosed in square brackets that the ThinHelp demo browser provides.)

Users of other WYSIWYG authoring tools will need to adapt the string syntax to the method used by that authoring tool.


Macros won’t work in 32 bit helpfiles

Check your macro syntax and make sure you are a) using a macro that the Windows 95 help compiler understands, and b) referencing it correctly.

Get used to using the abbreviated names for Win95 Help macros and you will have a lot fewer problems with ThinHelp and other Help authoring applications.  JumpID, for example, should be referenced as JI.  The compiler automatically shortens JumpID, ExecProgram, SaveMark etc. to their abbreviated equivalents when it finds them in your RTF, but it cannot shorten macros used in embedded window statements, .SEGs or .SHG files.

You’ll also need to remember to convert EP (ExecProgram) to EF (ExecFile) syntax for Windows 95’s compiler.

Finally, insure that all custom Windows API macros in 16 bit helpfiles using SHELL, KERNEL and USER registrations are changed to reflect the appropriate 32 bit Windows modules which contain the equivalents for these macros.  Windows 95 will thunk” to force proper function of macro references to `shell.exe', `user.exe' and `krnl386.exe', but these macros will fail with Windows NT and it's likely that they'll also fail in future Windows versions.


Macros won’t work in 16 bit helpfiles

If the macro was coded properly into your source document, .SEG file or .SHG graphic, there is likely to be only one cause for this problem: you are trying to execute this macro from a hotspot in a popup.

Although macros do not function as topic-entry (footnote) macros in popup topics, they are supposed to function from popup topic hotspots.  Supposed to” doesn’t necessarily mean they will.  We have encountered a number of situations in which hotspot macros in popups, even simple macros from WinHelp’s own built-in macro set, either won’t work at all or stop working after certain actions have been taken in the helpfile.  Windows 95’s Help engine seems to address this problem, but to our knowledge it was never even acknowledged as a problem with 16 bit Help.

This behavior is so erratic that we make the following blanket recommendation: do not use macros from hotspots in popup topics.  If you need a popup topic to provide macro functionality, make the hotspot into a jump hotspot that jumps to a secondary window, performs the needed function as a topic-entry macro and then closes the window as needed.

Since all jumps and popups permitted by ThinHelp in .SHG, .SEG-file and whole-bitmap hotspots are either coded as -- or functionally identical to -- JumpID() or PopupID() macros, ThinHelp does not support ThinHelp macros of any type if they execute from bitmaps in popup topics.

So while they may appear to work on your system, this use of ThinHelp is neither recommended nor will it be supported by Herd Software Development.


Windows reports ";" Expected

If you work with ThinHelp for any length of time eventually you’ll see this error...it’s almost a badge of honor, and it’s easy to trace and fix.  It means you have tried to add a macro to a ThinHelp embedded window statement and gotten the syntax wrong.

There are two ways to get this message.  The first is an incorrect semicolon usage.  Remember...one semicolon after the archivename, one after the bitmap name, two after the display parameters, and three if you need a macro without display parameters.  Here are examples of correct and incorrect syntax, with the errors highlighted in red and the corrections in green.

Plain embedded window:

{ ewc THNHLP,THIN,BITMAPS.LZH,MYBITMAP.BMP }
(incorrect)

{ ewc THNHLP,THIN,BITMAPS.LZH;MYBITMAP.BMP }
(correct)

Embedded window with macro, no display parameters:

{ ewc THNHLP,THIN,!BITMAPS.LZH;MYBITMAP.BMP;; JI(`help.hlp>2nd',`topic') }
(incorrect)

{ ewc THNHLP,THIN,!BITMAPS.LZH;MYBITMAP.BMP;;; JI(`help.hlp>2nd',`topic') }
(correct)

Embedded window with macro and display parameters:

{ ewc THNHLP,THIN,!BITMAPS.LZH;MYBITMAP.BMP;;0/0/2/0; JI(`help.hlp>2nd',`topic') }
(incorrect)

{ ewc THNHLP,THIN,!BITMAPS.LZH;MYBITMAP.BMP;0/0/2/0;; JI(`help.hlp>2nd',`topic') }
(correct)


Macros won’t work properly in watermarks

If HelpDebug didn’t report a faulty macro sequence when diagnosing your Help project, then you may have tried to place a Push-generated hotspot onto your watermark and then used a .SEG hypergraphic elsewhere in the topic.  Push hotspots on metafiles will not work in topics that have other Push-enhanced bitmaps sitting on top of the watermark.  Here’s how to solve the problem:

Try to convert your .SEGs back to normal Help .SHGs, and do not use ThinHelp to display them.  Instead, reference them as standard Help .SHGs.  These will function properly and allow your watermark hotspot to function as it should.

If this isn’t possible, perhaps you can break up” your Push-enhanced graphics somehow and attach embedded-window macros to the pieces rather than use actual Push hotspots.

Here’s an HTML hacker’s trick that will solve the problem when you can’t solve it any other way: create a pure, transparent ThinHelp bitmap, overlay it in the regular topic text, and use it to hold your hotspot rather the watermark itself.  Two color (monochrome) bitmaps, all-black, with black (0/0/0) defined as the transparent color will achieve this effect.


Jumping to a topic from a popup displays the wrong background color or watermark

This occurs when you click a popup in a main or secondary window topic, then click a link in the popup that jumps to another topic in the same helpfile.  The watermark or background color remains as it was for the topic you were originally browsing.  It generally occurs only when jumping from popups called from the contents topic.

To fix this, reference the popup directly to the helpfile using an interfile link rather than using a standard context string link.  For example, if you were referencing the link simply as jump_topic_from_popup, you would need to reference it instead as jump_topic_from_popup@[filename].hlp.

Occasionally this won’t work either, and in this case you’ll need to use a JumpID() macro, for example JI(`[filename].hlp’,`jump_topic_from_popup’).  This is a last resort, though, since macro hotspots in popups are notorious for breaking without an apparent cause.


ThinHelp causes a GPF on entry to a topic

In most cases you can trace this to too many characters, or the wrong characters, used to reference a bitmap in your embedded window statement.  It could occur if ThinHelp conflicts with a DLL on your system.

ThinHelp was designed from the ground up to conform to the Windows DLL specification and it is highly unlikely that ThinHelp alone could produce this kind of error.  The trick is to discover what DLLs might also be in memory at the same time as THNHLP.DLL and, if possible, work around the conflict.

For purposes of testing WinHelp DLLs it often helps to have a utility for unloading DLLs from memory.  As long as the DLL is still in memory, you will need to reboot Windows in order to make software using that DLL function properly.  Once the DLL is unloaded from memory, it should return to normal functioning.  Try a Web search on unload DLL” at http://www.shareware.com to track down several DLL unload utilities.


Hotspots disappear from SHGs displayed as embedded windows

This can occur when attempting to use a hotspotted .SHG which originated as a .WMF metafile graphic.  You may need to export this file from Push as a bitmap, reload it into Push and reapply the hotspot data to the new .BMP in order to get it to work.  You may also need to reference the new bitmap-based .SHG (or .BMP plus .SEG) as a transparent bitmap to restore lost transparency effects when the metafile was converted to a bitmap.


Animation frames display out of order

You need to repair the LZH archive containing the bitmap frames in the animation.  The easiest way to do this is to copy all frames out of the archive, remove these bitmaps from the archive, and then copy them back into the archive one at a time in the exact order in which you want ThinHelp to play them.


Watermarks show palette errors when switching windows

This occurs due to Windows Help’s method of getting and using Help and it must be handled in your authoring through the use of a tiny palette-definition bitmap in topics using watermarks with nonstandard Windows colors.

Click here to jump to the tutorial topic which explains how to insure palette compatibility with watermarks using colors other than the standard 16 color Windows palette.


Helpfile shows no WinHelp or Viewer error but does not display bitmap

This is either a problem with your embedded window statement or an error in the bitmap itself.

 If the bitmap is not correctly referenced in the { ewx } statement, it will not be displayed by ThinHelp.

 If the bitmap is damaged, which is rare but could happen, it will need to be replaced in the archive file.

 .RLEs are not compatible with ThinHelp.  Compressed .BMPs will only be compatible if the end user has the appropriate drivers on their system, which is something you should not depend upon and is not supported by ThinHelp.  Only JPEG, standard Windows .BMPs and SHED.EXE or Push-generated .SHGs are supported.

 Some users have reported problems with specific .BMP files saved by some programs being incompatible with ThinHelp. The bitmap import routine of ThinHelp is quite simple, otherwise the whole bitmap would need to be recopied to memory, with a resulting time delay.  Therefore not all varieties of BMP files can be displayed by ThinHelp.  If you encounter problems using a BMP file in ThinHelp, load it into PaintBrush, BitEdit, ImageEdit or a similar approved Microsoft bitmap editor and resave it as a 256 color or 16 color bitmap.


Topic window display is taking too long

There are many reasons why this could be occurring.  Here are the most common:

Solution 1: check ThinHelp’s memory consumption

If you are using ThinHelp’s THSetCacheSize() macro to control ThinHelp’s memory consumption, you may have set too low a figure...or you may not need it at all.  The default cache management settings in ThinHelp are set to insure optimum performance on the widest possible range of systems.

There are instances where THSetCacheSize() can improve performance, but you’ll have to carefully weigh the benefits of increased performance on some systems against the potential of reduced performance on others.  The THSetCacheSize() technical topic discusses this in more depth.

Solution 2: reduce the load on Help

The simplest, kindest thing you can do for ThinHelp’s display speed is to simplify your page layout.  Simple layouts require fewer redraws of the Help window and will display faster.  If there’s a way to display the topic without a table, for example, try this before resorting to more extreme measures.

Solution 3: reduce the load on ThinHelp

The next thing to try is to reduce ThinHelp’s workload.  If you’re using background textures, try reducing them to custom 16 color palettes from 256 color .BMP or JPEG if you can.  If you’re using  transparent bitmaps, try to make black the transparent color...ThinHelp is optimized for top performance with 0/0/0 (black) as the transparent color.

Solution 4: reduce the load on graphics devices

What do you have going on in the background while ThinHelp is running?  If you have a bitmap browser such as LView or ACDSee open, plus PaintBrush, plus your Web browser, plus a ThinHelp-enhanced Help or Viewer title, you have several programs all competing at once for Windows’ graphic display software...and your video memory.  On a 386-DX40, this combination of programs will slow any system to a crawl, with or without ThinHelp, and even fast 486-DX100’s will suffer significant screen-redraw delays especially if palette changes force all programs to redraw their windows.

How many large bitmaps are you using in the same topic?  JPEG graphics in particular will require time for any software to decompress them prior to display, and the more graphics onscreen, the longer the wait for screen updates.  ThinHelp has been optimized on an ongoing basis for more than 15 months but you will still encounter slow-display problems with sophisticated layouts and multiple high-resolution bitmaps.

If your Help or Viewer title depends on other graphics-dependent software being open, try to replace as many ThinHelp bitmaps as is reasonably possible with standard WinHelp bitmaps or metafiles.  You’ll lose the compression advantage of ThinHelp, but you may get back the screen-redraw performance you need for the application.

Solution 5: reduce the load...period.

How many embedded windows or window-control DLLs are you trying to use?  If you have a combination of -- for example -- Interactive Help, NextHelp, OSHTOOLS.DLL, HDKANIM.DLL, WINSIZE2.DLL, Help Buttons, D2HTOOLS.DLL, FormHelp or HLP256.DLL and ThinHelp working together in the main window, you may have to compromise on one of the embedded-window DLLs for the sake of end-user comfort.  Help is no different from HTML authoring in this regard...all this new technology is exciting and fun, but it’s often too easy to carry your creativity to (or beyond) the bleeding edge”.  In fact, some of the topics in THINHELP.HLP rub up very close to the comfort boundary, even after extensive reformatting and graphical tweaking.

Solution 6: no solution in sight

Recent (1996) industry surveys have demonstrated that while computers have become more powerful, software is increasing in complexity at a much more rapid rate.  The result is the wide availability of extremely sophisticated software which is all too often overmatched to the system on which it is used.  Even though 1996’s Windows programs are far more sophisticated, they often perform their work more slowly on 1996 consumer-class machines than 1989’s most powerful DOS programs did on consumer-class machines of that era.

This trend showed no sign of reversing at the time this file was published.


Bitmap colors are distorted

You have a palette conflict.  More detailed information on palette conflicts is available in the section on palette handling in ThinHelp.

 Wrong bitmap type.  You may have tried to use a 256 color bitmap, metafile or SHG in a topic rather than a ThinHelp embedded window bitmap.  Even SHED-compressed WMF files using the standard Windows palette will suffer color distortion if you switch to another 256 color application and back to your helpfile again.  Try to make sure that all 256 color bitmaps are referenced by ThinHelp rather than { bmx } statements.

 Mismatched palettes.  You will need to use a graphics tool to match the palettes of the bitmaps in this topic or else turn all bitmaps into this topic into JPEG-compressed bitmaps which ThinHelp will handle automatically.  See the section on palette handling in ThinHelp.  An easy way to match palettes is to reduce the bitmaps to 16 color nonstandard-palette Windows bitmaps (this can be done with no loss of quality with a wide range of converted GIFs and PCX/WPG clip art), and then have ThinHelp do the analysis and palette assignment for you.

 Paint Shop Pro was used to create the bitmap.  Paint Shop Pro uses a nonstandard 16 color palette which has been a major source of grief for Help authors.  We recommend creating a palette file for use in Paint Shop Pro which includes a proper 16 color windows  palette (i.e. with navy blue referenced as 0,0,128 rather than Paint Shop Pro's default 0,0,191) and loading this palette using Nearest color into all bitmaps and screen shots created using Paint Shop Pro or JASC Pro Capture.  Create this palette file by saving the palette of any 16 color bitmap generated by PaintBrush as a Paint Shop Pro palette file.  See Paint Shop Pro’s helpfile for more information about palette files.


ThinHelp support

Support for ThinHelp is available from both Herd Software Development and D:\Mystify Software.

Herd Software Development can be contacted directly at:

Herd Software Entwicklung

Bernd Herd

Ruldolf-Virchow-Str. 8

D-68642 Bürstadt

Germany

Tel:	+49-6206-79222	from march 1997 on: +49-6206-707775

Fax:	+49-6206-79222	from march 1997 on: +49-6206-707776

Email:	herdsoft@aol.com

WWW:	http://members.aol.com/herdsoft/index.htm

CompuServe:100545,3001

For English-language or North American support, contact:

D:\Mystify Software

c/o Cub Lea

104 N. Grosvenor Ave.

Burnaby, BC

CANADA

V5B-1J2

Tel:	(604) 298-6415 or (604) 240-0506

Fax:	(604) 444-3575

Email:	cublea@cyberstore.ca

CompuServe:103076,1667

Prior to contacting either party for product support, please be sure you are aware of your rights and limitations concerning after-sale support.

Authoring errors

Issues involving authoring errors are not the responsibility of Herd Software Development or D:\Mystify Software.  Although you may be given help with these problems, no-cost support for authoring errors is by no means warranted or included in the price of your software.  We understand there is often no way to know for sure what sort of error you are experiencing until a solution is found, but be aware that support for this type of problem will likely be limited.  In most cases it will be just as easy for us to tell you how to solve your problem as it would be to deny non-billed authoring assistance.  In such cases we will usually provide you with solutions to authoring errors at no cost.  Extensive troubleshooting of author-generated errors, however, will be billed at consultation rates.

Compatibility issues

A great deal of work went into insuring the maximum possible degree of compatibility between ThinHelp and all possible installations and implementations of Windows.  There is always the chance that a potential combination of hardware and software will produce a problem.  In such cases it shall be left to the discretion of Herd Software Development whether to support the desired implementation.  Relatively common or new configurations or installation situations are likely to be supported with updates; obscure configurations may not be subject to support.

Software design errors

While every attempt was made to insure that this software was fit for the purpose intended when shipped to you, the ThinHelp package comprises a highly complex set of extensions and tools.  There is always the possibility that errors in design will make it into the production run of any software of this level of complexity.

Any issue relating to design errors or flaws in the software itself will be addressed if possible by Herd Software Development with bug fixes and updates.  Herd Software and/or its authorized agents will attempt to keep registered users of the software informed of bug fixes and updates through email bulletins and World Wide Web page postings of updates, patches and fixes.

No warranty is made in regard to response time for dealing with bug fixes.  Most flaws in earlier builds of ThinHelp and JPANI have been addressed within 72 hours of receipt.  We will attempt to continue with this level of support, but no such guarantee of performance is either implied or expressed in this software or its documentation.

Documentation errors

The complexity of the software and its application necessitated an extensive and detailed Help system.  While every effort has been made to insure the accuracy of the documentation as provided, it is possible that errors may have found their way into the completed documentation.

D:\Mystify Software, as developers of the online documentation for ThinHelp, Push, HelpDebug and HLPLHA.DLL, will attempt to keep registered users of the software informed of documentation errors, updates and enhancements to the documentation through email bulletins and World Wide Web page postings of corrections and appendices.

No warranty is made in regard to response time for dealing with bug fixes.  Most flaws in D:\Mystify documentation have been addressed within 12 to 24 hours of receipt.  D:\Mystify will attempt to continue with this level of support, but no such guarantee of performance is either implied or expressed in this software or its documentation.