Positioning Embedded Windows

Embedded windows are displayed within a topic paragraph. Often, the topic paragraph contains text to be positioned in relation to the embedded window element. Help supports three different positions for embedded windows—character-aligned, left-justified, or right-justified.

The following table describes the position attributes that control the placement of an embedded window in relation to the paragraph text.

Each position defines how the embedded window is positioned with respect to the topic text, and each position requires a slightly different command reference in the topic file:

character{ewc DLL-name, window-class, author-data}

left-aligned{ewl DLL-name, window-class, author-data}

right-aligned{ewr DLL-name, window-class, author-data}

Character-Aligned Embedded Windows (ewc)

The ewc (embedded window character) command causes Windows Help to treat the window as a text character. It aligns the window on the baseline of the type in exactly the same place in the paragraph where the command occurs. Because the window is treated as text, paragraph formatting properties assigned to the paragraph also apply to the window. Text coming before or after the window does not wrap around the window. Help adjusts the height of the line containing the embedded window to allow enough space for the embedded window.

Figure 9.x shows how Word for Windows displays the embedded window reference in the topic file.

After you compile your topic file, Windows Help displays the embedded window, as in Figure 9.x.

You can display multiple character-aligned embedded windows on the same line. Help adjusts the line height to allow for the tallest embedded window.

Note:

Don’t specify absolute line spacing (also called “negative line spacing” or “exact line spacing”) for a paragraph that has an ewc reference. If you do, the embedded window might appear on top of the succeeding paragraph when Windows Help displays the topic.

Left- and Right-Justified Embedded Windows (ewl, ewr)

The ewl (embedded window left) command and ewr (embedded window right) command cause Windows Help to place the embedded window along the left or right paragraph margin and wrap the paragraph text around the edge of the embedded window. Text is aligned with the upper-right or upper-left corner of the window.

You normally place ewl and ewr references at the beginning of a paragraph to ensure proper wrapping of text around the right edge of the window. For example, typical ewl and ewr references are formatted as follows:

{ewl FADE, AmfWnd, clipbrd.amf}Paragraph text follows the embedded window reference...
{ewr FADE, AmfWnd, clipbrd.amf}Paragraph text follows the embedded window reference...

Figure 9.x shows how ewl and ewr references appear in the Word for Windows topic file.

Note:

Do not put any space characters between the ewl or ewr 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 window (ewl) or from the left topic margin (ewr). To ensure that text wraps correctly around an embedded window, insert a soft carriage return at the end of each line of text.

After you compile the topic file, Windows Help displays the embedded window to the left or right of the text, as in Figure 9.x.

You can also put an ewl or ewr reference at the end of a paragraph, as in this example:

Paragraph text precedes the embedded window reference.{ewl FADE, AmfWnd, clipbrd.amf}
Paragraph text precedes the embedded window reference.{ewr FADE, AmfWnd, clipbrd.amf}

Figure 9.x shows how this type of embedded window reference appears in the Word for Windows topic file.

When you include an ewl or ewr reference this way, Windows Help wraps the text to the paragraph end and then displays the embedded window. After you compile the file, the embedded window appears under the text and to the left or right, as in Figure 9.x.

Left and Right Margins

The paragraph indent determines the distance between the window border and the left or right edge of the embedded window.

Note:

Within tables, the paragraph indent determines the distance between the cell border and the left or right edge of the embedded window.

Help reformats paragraphs when the user changes the horizontal width of the window. The resulting changes in word wrapping can change the position of embedded windows within the paragraph.

For example, in Figure 9.x, the right margin setting determines the distance of the right-aligned embedded window from the window border.

In Figure 9.x, the user has reduced the width of the window, and the embedded window has changed position:

Note:

The Word Keep Lines Together attribute, used to prevent Help from word-wrapping a paragraph, does not prevent Help from moving a left- or right-aligned embedded window in relation to the window border. The window will move when the window is sized, but the paragraph text won’t move.

Vertical Positioning

The vertical position of a left- or right-aligned embedded window depends on the insertion point of the element within the topic paragraph. Help uses the following rules to determine the vertical position:

nIf the element is the first item in the paragraph, the embedded window is displayed in the first line of the paragraph.

nIf the element is not the first item in the paragraph, the embedded window is displayed in the line immediately below the insertion point.

Left- and right-aligned windows are displayed with their top edge aligned with the tallest character in the line. The top edge of the embedded window is aligned with the top edge of the line, and the rest of the embedded window extends down into the paragraph. Figure 9.x shows a left- or right-aligned embedded window is positioned in a line.

Note:

Because character-aligned embedded windows are treated as large characters, they can increase the height of a line. This will affect the positioning of left- or right-aligned embedded windows displayed in the same line.

Figure 9.x shows three topic paragraphs displayed in Word and in Help. Each paragraph has identical content and Word formatting, but the insertion point of the embedded window changes from one to the next. In this example, the three embedded windows are left-aligned.

<three paragraphs in Word and Help, with elements in three different positions: first char, after first word, and last char>

In Figure 9.x, the three embedded windows are right-aligned.

<three paragraphs in Word and Help, with elements in three different positions: first char, after first word, and last char>

Help cannot display multiple left- or right-aligned embedded windows in the same vertical position. If you have multiple left- or right-aligned embedded windows inserted in the same position within the paragraph, Help displays the windows in different vertical positions within the paragraph. For example, Figure 9.x shows a topic paragraph displayed in Word and in Help.

<Word paragraph. Callouts identifying icons as left- and right-aligned bitmaps>

Using Tables to Position Embedded Windows

If you need to display multiple embedded windows in the same vertical position, you can use tables to position the embedded windows. Table formatting lets you more closely control the position of embedded windows within a paragraph. For example, you can position two or more left- or right-aligned windows within the same vertical plane. Or you can place an embedded window in the center of a paragraph. Paragraphs within tables are not reformatted when the window is sized.

Left- and right-aligned embedded windows are aligned with the cell borders. The word-wrapping of paragraphs in tables is not affected by changes in window size position, so if you want to prevent an embedded window from moving with the window border, you must place the containing paragraph in a table cell.

Figure 9.x shows a Help topic that uses tables to create some sophisticated paragraph layouts.