nYou have the widest range of options for positioning the picture with text. For example, you can treat the picture as a text character, or you can wrap text around the left or right edge of the picture.To achieve finer control over the placement of a picture, you can place a bitmap reference in the topic. The bitmap reference is like a coded message that tells the compiler the name of the bitmap file and how to position the picture with respect to the topic text. When Windows Help encounters a bitmap reference, it inserts a reference to a central location in the Help file where the picture is stored. The Windows Help application uses this referenced information provided by the Help compiler to display the picture.
You can use bitmap references to display a variety of pictures in Help, from tiny bullet characters to full-screen illustrative art. The advantages to using bitmap references are:
nYou have the widest range of options for positioning the picture with text. For example, you can treat the picture as a text character, or you can wrap text around the left or right edge of the picture.
nYou should not notice any change in the performance of Word for Windows; bitmaps included by reference do not affect it any more than text does.
nYou can change the graphic as often and as much as you like without changing the reference in the topic file. The references are simply pointers to the actual bitmap files.
nYou can use hypergraphics (pictures with hot spots) in your topic files. In fact, hypergraphics must be included by reference. For more information, see Chapter 11, “Creating Hypergraphics.”
nYou can use any text editor that produces RTF files to create your Help topics, including Word for the Macintosh.
The disadvantages are:
nYou can’t see the graphic when you are working in the word processor.
nYou must tell the compiler where to find the actual bitmap files referenced in the topic files when you build the Help file. Although this is a simple task, mistakes in this process will cause errors when you compile the Help file.
Including Bitmaps by Reference
To include bitmaps by reference in a topic file, you must make the following changes to the topic and Help project file:
nEnter a reference command in the topic file where you want the picture to appear.
nMake an entry in the Help project file that tells the compiler where to find the bitmap files referenced in the topic files.
Help supports three different positions for bitmaps included by reference—character, left-aligned, or right-aligned. Each position defines how the bitmap is placed with respect to text, and each position requires a slightly different command reference in the topic file:
character
left-aligned
right-aligned
Positioning Character-Aligned Bitmaps (bmc)
Windows Help treats a bmc bitmap as a text character. It aligns the bitmap on the baseline of the type in exactly the same place in the paragraph where the reference command occurs. Because the bitmap is treated as text, any paragraph formatting properties assigned to the paragraph also apply to the bitmap. Text coming before or after the bitmap does not wrap around the bitmap, but it may appear slightly higher on the line if any white space is saved at the bottom of the bitmap image.
Help files use bmc bitmaps in many ways. For example, you might include a bitmap in the explanation of an interface element. Figure 10.x shows how Word for Windows displays the bitmap reference in the topic file.
Note:
Don’t specify negative line spacing for a paragraph that has a bmc bitmap reference. If you do, the bitmap might appear on top of the succeeding paragraph when Windows Help displays the topic.
After you compile your topic file, Windows Help displays the referenced bitmaps, as in Figure 10.x.
Positioning Left-Aligned Bitmaps (bml)
Windows Help places a bml bitmap along the left margin, with text wrapping along the right edge of the image. Text is aligned with the upper-right corner of the bitmap, so any white space saved at the top of the image affects the way text appears in relation to the bitmap.
You normally place bml references at the beginning of a paragraph to ensure proper wrapping of text around the right edge of the bitmap. For example, a typical bml reference is formatted as follows:
Paragraph text follows the bitmap reference...Figure 10.x shows how a bml reference appears in the Word for Windows topic file.
Note:
Do not put any space characters between the bml reference and the paragraph text unless you want the first line of text indented from the rest of the text that wraps along the right edge of the bitmap.
After you compile the topic file, Windows Help displays the referenced bitmap to the left of the text, as in Figure 10.x.
You can also put a bml reference at the end of a paragraph, as in this example:
...Paragraph text precedes the bitmap reference.Figure 10.x shows how this type of bml reference appears in the Word for Windows topic file.
When you include a bml reference this way, Windows Help wraps the text to the paragraph end and then displays the bitmap. After you compile the file, the bitmap appears under the text and to the left, as in Figure 10.x.
Positioning Right-Aligned Bitmaps (bmr)
Windows Help places a bmr bitmap along the right margin, with text wrapping along the left edge of the image. Text is aligned with the upper-left corner of the bitmap, so any white space saved at the top of the image affects the way text appears in relation to the bitmap.
You normally place bmr references at the beginning of a paragraph to ensure proper wrapping of text around the left edge of the bitmap. For example, a typical bmr reference is formatted as follows:
Paragraph text follows the bitmap reference...Figure 10.x shows how a bmr reference appears in the Word for Windows topic file.
Note:
Do not put any space characters between the bmr reference and the paragraph text unless you want the first line of text indented from the left topic margin.
After you compile the topic file, Windows Help displays the referenced bitmap to the right of the text, as in Figure 10.x.
You can also put a bmr reference at the end of a paragraph, as in this example:
Paragraph text precedes the bitmap reference.Figure 10.x shows how this type of bmr reference appears in the Word for Windows topic file.
When you code a bmr reference this way, Windows Help wraps the text to the paragraph end and then displays the bitmap. After you compile the file, the bitmap appears under the text and to the right, as in Figure 10.x.
Each of the bitmap reference commands, bmc, bml, and bmr, has alternative forms ending with wd. Bitmaps positioned using the bmcwd, bmlwd, and bmrwd commands look the same as bitmaps positioned using the bmc, bml, and bmr commands. However, the commands ending in wd store the bitmap data differently in the Help file.
When you use the bmc, bml, or bmr command, the bitmap data is stored separately from the Help file text. A single copy of the bitmap is used for all bmc, bml, or bmr commands that display the same bitmap. Using these commands can therefore reduce the size of your Help file if you reference large bitmaps more than once in a file. The disadvantage is that Windows Help must retrieve the bitmap from the disk before displaying it in the topic, so these bitmaps may display more slowly than those referenced with the wd commands, especially if the Help file is stored on a CD-ROM disc.
When you use the bmcwd, bmlwd, or bmrwd command, the bitmap data is stored in the same location in the Help file as the text. The bitmap data becomes part of the Help file, and this data appears in the location given by the command. When the bitmap is stored inline with the text, Windows Help may display it faster than if it were positioned using the bmc, bml, or bmr command because it doesn’t have to retrieve information from different locations on the disk. Reading data from different locations on a CD-ROM is very time consuming, and it can also be slow on magnetic media.
Moreover, storing bitmaps with data maximizes the benefits of using the OPTCDROM option in the Help project file. Help keeps up to 12K of compressed topic text in memory. Since bitmaps with data are kept with the topic text, they take advantage of this buffering. So, generally, topics less than 12K after compression do not need to be re-read from disk when the window is resized or redrawn.
The primary limitation of the wd commands is that each bmcwd, bmlwd, or bmrwd command stores a separate copy of the bitmap. That means your Help file will be larger if you use bitmaps stored with data than if you use the commands without wd, especially if you reference larger bitmaps more than once. Large bitmaps that are referenced using wd may also cause “out-of-memory” error messages when compiled under MS-DOS.
Another limitation is that bitmaps stored with data cannot be more than 64K after compression. If the compression reduces the size of the bitmap to less than 64K, then you can store it with data. How much compression is achieved depends on the bitmap. That means you can have two different bitmaps that are 80K before compression, and one may compress to less than 64K and the other may not. Therefore, Help claims a 64K limit for bitmaps stored with data, even though the actual limit may vary slightly.
Because the Windows bitmap format does not include any compression, all bitmaps are compressed during the build by the Help compiler. If you want a quick way to determine how large the bitmaps will be when they are put into Help, you can use Hotspot Editor or Multi-Resolution Bitmap Compiler, since they compress bitmaps using the same mechanism as the Help compiler. If the bitmap is still too large, you may have to reduce its size or complexity.
Use the following guidelines to decide whether to use the normal or wd versions of these commands:
nUse bmc, bml, and bmr for all bitmaps that appear frequently in your Help file.
If a bitmap is used frequently, not placing it “with data” may be more appropriate, unless the performance benefit outweighs the size factor.
nUse bmcwd, bmlwd, and bmrwd for small bitmaps (less than 64K) that appear only once or infrequently in your Help file.
Bitmaps with data use extra disk space only when the same bitmap is used more than once in the Help file.
nUse bmc, bml, and bmr for large bitmaps (greater than 64K).
Large bitmaps stored with data may worsen performance if the topic is drawn twice to remove unnecessary scroll bars. If the topic is over 12K, it will be read, laid out, and then read a second time as it is laid out without the scroll bars. Because bitmaps cause most topics to exceed 12K, this problem is likely to occur if you store bitmaps with data. Bitmaps not stored with data, on the other hand, are kept in a different location from the text, so they are read from disk only once if the topic text is less than 12K.
nUse bmc, bml, and bmr for bitmaps that appear in two or more topics normally displayed in sequence (for example, in a browse sequence).
Help caches in memory the 50 most recently accessed bitmaps that are not stored with data. This means that a bitmap may only have to be read from disk once if two Help topics reference it successively. Unlike bitmaps stored with data, these cached bitmaps have to be re-read only if they’re moved out of the cache by 50 new bitmaps, or by low memory conditions.
Cached bitmaps not stored with data degrade performance if they are displayed only once. Since they are stored in a different location from the topic text, Help requires an additional seek to locate them. This cost, if incurred, is generally negligible on magentic disks but high on CD-ROM. Nonetheless, this performance cost may be less than the cost of reading the topic twice if the topic is larger than 12K.