Statements and Functions

WordBasic instructions are composed of statements and functions, which are defined as follows:

A statement carries out an action. For example, opening a file, selecting text, and scrolling through a document are all actions. Virtually every action you can perform in Word has an equivalent WordBasic statement.
A function retrieves information. A function sometimes also performs an action, but the primary purpose of a function is to return information to the macro. A function can determine the character formatting of selected text, whether a document is in outline view, whether a toolbar is displayed, and many other things.

When you begin working with WordBasic, it's very helpful to get a sense of the different statements and functions available to you. A good way to do this is to browse through "Language Summary" in Part 2, "WordBasic Reference," which classifies WordBasic statements and functions according to the tasks they accomplish.

Statements

Most WordBasic statements are equivalent to Word commands. For example, the following instruction, which uses the EditFind statement, is equivalent to choosing the Find command from the Edit menu and searching for "Yours truly":

EditFind .Find = "Yours truly", .Direction = 0, \
        .MatchCase = 0, .WholeWord = 0, .PatternMatch = 0,\
        .SoundsLike = 0, .FindAllWordForms = 0, .Format = 0, .Wrap = 1

Each option in the Find dialog box has a corresponding argument in the EditFind statement. For example, the Match Case check box is represented by the .MatchCase argument. Arguments that correspond to dialog box options begin with a period (.) and are separated by commas (,). Each argument has a value associated with it, which may be a number or text enclosed by quotation marks. For example, .MatchCase takes a numeric value, while .Find takes a text value.

The syntax for each statement in Part 2, "WordBasic Reference," indicates the values that arguments require. You can see the same entry in Help by positioning the insertion point in the EditFind statement in the macro-editing window and pressing F1 (Windows) or HELP or COMMAND+/ (Macintosh). In the entry for EditFind, the syntax line shows all the available arguments for the statement with the values they require:

EditFind [.Find = text] [, .Replace = text] [, .Direction = number] [, .WholeWord = number] [, .MatchCase = number] [, .PatternMatch = number] [, .SoundsLike = number] [, .FindAllWordForms = number] [, .Format = number] [, .Wrap = number]

The syntax also indicates which arguments are necessary and which are optional; brackets ([ ]) enclose optional arguments. For complete information on how to interpret syntax lines, see the introduction to "Statements and Functions" in Part 2, "WordBasic Reference."

Controlling Where Lines Break in Long Instructions

In a WordBasic macro, every instruction ends with a paragraph mark. Most instructions are less than a line long, but some WordBasic statements have many arguments and can't fit on a single line. When you record one of these instructions, Word wraps it onto a second or third line as needed. For example, if you record changing information on the User Info tab in the Options dialog box (Tools menu), Word inserts an instruction like the following one in the macro you're recording:

ToolsOptionsUserInfo .Name = "Lucie Caselli", .Initials = "LC", .Address = "Aperture Film"

You can make multiple-line instructions such as this one more readable by adding line breaks. To do so, place the insertion point at the location where you want to break the line, type the backslash ( \) character to indicate to Word that the instruction continues into the next paragraph, and then press ENTER. For example, here's how you could rearrange the preceding ToolsOptionsUserInfo instruction by inserting a line break and some tab characters:

ToolsOptionsUserInfo .Name = "Lucie Caselli", .Initials = "LC", \

.Address = "Aperture Film"

Functions

WordBasic functions do not correspond to Word commands as neatly as statements do, but they provide many types of information about documents and the current state of Word. For example, the Font$() function returns the name of the font where the insertion point is located. Often, the information that a function returns is placed in a variable, which is a kind of storage container. Variables are described in the "Variables" section later in this chapter.

A function is easily distinguished from a statement because it ends with parentheses. Here are some examples:

Font$()
Selection$()
CharColor()
CountStyles()
ViewOutline()
BookMarkName$()

Note that some functions include a dollar sign ($) character just before the ending parentheses. These functions return information in the form of text, or strings. The other functions return numbers. Strings and numbers are described in the following section.