Common WordBasic Techniques

So far, this chapter has presented the building blocks needed to construct macros with WordBasic. This section describes a few widely used WordBasic techniques that employ some of those building blocks.

Inserting Text into a Document

To insert text, special characters, and even nonprinting characters like tab characters, you use the Insert statement. The Insert statement is the macro equivalent of typing at the keyboard; anything you can type, a macro can insert with Insert. For example, the following instruction inserts the phrase "Sincerely yours" into a document:

Insert "Sincerely yours"

Notice that the statement doesn't specify where "Sincerely yours" is to be inserted. Just as when you type, the phrase is inserted into the active document wherever the insertion point is currently located. If there is a selection, Insert will replace it (assuming the Typing Replaces Selection check box on the Edit tab in the Options dialog box (Tools menu) is selected).

The Insert statement inserts plain text into a document. The text you insert takes on the formatting of the text that precedes it. If you want to insert text with a different format, you place instructions to apply that formatting before the Insert instruction, just as you would turn on formatting before typing text. The following example turns on italic formatting just before inserting text and turns it off just afterward:

Italic 1                                'Turn on italic
Insert "Love's Labour's Lost,"        'Insert text
Italic 0                                'Turn off italic
Insert " by William Shakespeare"        'Insert more text

You can insert many special characters and nonprinting characters with Insert by typing them and enclosing them in quotation marks, as you would other text. For example, the following instruction inserts a tab character:

Insert "        "                        'Insert a tab character

Just looking at this instruction, though, it's difficult to tell whether you intend to insert a tab character or several spaces. In general, it's a better practice to use the Chr$() function with Insert to insert nonprinting characters:

Insert Chr$(9)                        'Insert a tab character

To insert paragraph marks, use InsertPara.

If you want to insert text into a document that isn't active, you include statements in your macro to open the document or switch to it. The following example activates the document associated with the variable LetterDoc$ and moves the insertion point to a bookmark called "Closing" before inserting text:

Activate LetterDoc$                'Switch to the LetterDoc$ window
EditGoTo "Closing"                'Move the insertion point to a bookmark
Insert "Sincerely yours"            'Insert text

Working on Part of a Document

Quite often, you want a macro to operate on only part of a document. For example, a macro that creates a table and inserts information into the table should operate just within the table. Or a macro may be designed to perform a series of formatting and editing operations on a particular paragraph.

The most useful tool Word provides for identifying discrete parts of documents is bookmarks. A simple use for bookmarks is just to mark a selection or location in a document. The following instruction marks the current selection (or the current location of the insertion point if there is no selection) with the bookmark "temp":

EditBookmark .Name = "temp", .Add

You can also use bookmarks to select text between two arbitrary locations in a document, as shown in the following example. It marks the current location with the bookmark "temp" and then pastes text from the Clipboard into the next paragraph. The ExtendSelection instruction activates extend mode, and the EditGoto instruction returns to the "temp" bookmark, selecting all the text between the end of the inserted text and "temp" as it does so.

EditBookmark .Name = "temp", .Add        'Insert bookmark "temp"
ParaDown                                    'Move to next paragraph
EditPaste                                'Paste from Clipboard
ExtendSelection                            'Activate extend selection
EditGoto "temp"                            'Return to "temp"; select text

Word provides a set of predefined bookmarks for macros. These bookmarks do not appear in the list of bookmarks that appears in the Bookmark and Go To dialog boxes (Edit menu), but a macro can use them in the same way it can use other bookmarks. Here is the list of predefined bookmarks.

For a more detailed description of the predefined bookmarks, see "Operators and Predefined Bookmarks" in Part 2, "WordBasic Reference."

The following example places a tab character in front of every paragraph in a table cell. The first instruction uses the predefined bookmark " \ Cell" to select the current cell (assuming the insertion point is already within a cell). The EditReplace instruction then replaces every paragraph mark with a paragraph mark and a tab character. After the replace operation, each paragraph except the first paragraph (since it isn't preceded by a paragraph mark) begins with a tab character. The CharLeft instruction then moves the insertion point to the start of the cell and inserts a tab character in front of the first paragraph.

EditGoTo "\Cell"
EditReplace .Find = "^p", .Replace = "^p^t", .Direction = 0, \
            .ReplaceAll, .Format = 0, .Wrap = 0
CharLeft
Insert Chr$(9)

You can use the SelInfo() function to test whether the insertion point is within a table. The following example uses SelInfo() to control a While loop that moves through a table and inserts information into each cell. When the macro reaches the last cell of the table, it stops.

EditGoTo .Destination = "t"                'Go to next table
While SelInfo(12) = - 1
    'Series of instructions to run while in the table
Wend

For more information, see SelInfo() in Part 2, "WordBasic Reference."

Reading Text from a Document

Frequently, a macro needs to "read" text from a document. For example, if a macro is moving through a document, it may need to check its location by checking the contents of a selection.

You use the Selection$() function to return the contents of the current selection. If no text is selected, Selection$() returns the character following the insertion point. The following example determines whether or not a paragraph contains text or just consists of a paragraph mark. If the selection is just a paragraph mark (Chr$(13) is equivalent to a paragraph mark), the message "This paragraph is empty" is displayed.

EditGoto "\Para"                            'Select paragraph
If Selection$() = Chr$(13) Then            'Test selection
    MsgBox "This paragraph is empty."
Else
    MsgBox "This paragraph contains text."
End If

You can also use the GetBookmark$() function to return text marked by a bookmark. For more information, see Selection$() and GetBookmark$() in Part 2, "WordBasic Reference."

Testing for the End of a Document

You often need macros to perform a series of operations on every instance of a particular element in a document. For example, you might want a macro to change the capitalization of every heading formatted with the Heading 5 style. A common way to set up this sort of macro is to have the macro start at the beginning of the document and stop when it reaches the end of the document.

Word provides several ways to test for the end of the document. The most straightforward is the AtEndOfDocument() function, which returns a true value,
–1, when the insertion point is at the end of the document. The following loop operates until the insertion point reaches the end of the document:

While AtEndOfDocument() <> -1
    'Series of instructions to run until the end of the document
Wend

The LineDown() and ParaDown() functions return a false value, 0 (zero), when they are unable to move the insertion point, which occurs only when they are at the end of a document. The following loop moves through the document a paragraph at a time until the insertion point reaches the end of the document:

While ParaDown()
    'Series of instructions to run until the end of the document
Wend

The end of a document is defined as the location just in front of the final paragraph mark in the document. The functions AtEndOfDocument(), LineDown(), and ParaDown() will not return a value indicating the end of a document unless the insertion point is at that location. It is not enough for the insertion point to be somewhere on the last line or somewhere in the last paragraph of a document.

You can also use CmpBookmarks() to test for the end of of the document, as shown in the following example:

While CmpBookmarks("\Sel", "\EndOfDoc")
    'Series of instructions to run until the end of the document
Wend

The EditFind and EditReplace instructions do not directly test for the end of a document, but you can use them to perform a task for as long as something is found. The following example changes the capitalization of each Heading 5 paragraph in a document. After the first search for a heading, the While¼Wend loop repeats the search until no more headings formatted with the Heading 5 style are found:

StartOfDocument
EditFindClearFormatting
EditFindStyle .Style = "Heading 5"
EditFind .Find = "", .Direction = 0, .Format = 1, .Wrap = 0
While EditFindFound() = - 1
    ChangeCase 2                'Capitalize first letter of each word
    RepeatFind
Wend