Extending WordBasic with AppleScript

When combined, AppleScript and WordBasic can be used to customize the Macintosh in many ways. A script can control Word and other scriptable applications, while WordBasic can run scripts that in turn do work and return data to Word. With AppleScript recording turned on, you can easily record scripts from within Word. You can also write simple macros and customize the Word interface to expose external scripts, so any user can take advantage of compiled script applications without leaving Word.

Recording Scripts

AppleScript can record Word. That is, Word will generate Apple Events for all user actions when recording has been turned on for an entire Macintosh. These events can then be recorded by AppleScript.

In Word, AppleScript recording is based on the internal WordBasic recording mechanism. Because of this, WordBasic macros and AppleScript scripts cannot be recorded at the same time. If Word is in the process of recording a WordBasic macro, it will ignore requests to record from AppleScript. Similarly, if Word is recording Apple Events, the user will not be able to start WordBasic macro recording.

Just as a subset of the functionality in Word is exposed to AppleScript, only a small segment of user actions are recorded as native AppleScript. That is, most simple editing, formatting, and file manipulation actions will be recorded as one of the basic events acting on an Apple Event object (for example, opening a file or setting the style of the selection to bold). All other actions are recorded as Do Script events with the appropriate WordBasic instructions, much as the actions would be recorded within a WordBasic macro.

Using the Do Script Event

Much of Word's functionality is not exposed directly to AppleScript because the standard suites are meant to be a common interface for objects across many applications. However, scripts can still control Word completely by using the Do Script event. With Do Script, a script can run the same WordBasic instructions that Word macros use to control the application. This effectively gives a script access to all the functionality of Word.

WordBasic is the native programming language of Word, and Word is optimized to use WordBasic. Therefore, to get the fastest performance from Word, AppleScript programmers should consider using Do Script events to control Word as much as possible.

Here is the syntax for the Do Script event:

do script WordBasic$

Note that WordBasic$ is either one instruction to execute or a list of instructions. The result of a Do Script event in a script is either one value, if Word was passed one WordBasic instruction, or a list of values, if Word was passed a list of instructions.

For example, here is a simple WordBasic macro:

Sub MAIN
    FileOpen "Hard Drive:Microsoft Word:Sample Document"
    EditFindStyle .Style = "Heading 2"
    EditReplaceStyle .Style = "Heading 3"
    EditReplace .Direction = 0, .ReplaceAll, .Format = 1, .Wrap = 1
    FileClose 1
End Sub

In AppleScript, scripting commands and objects could be used to duplicate the functionality of the original WordBasic macro, as follows:

tell application "Microsoft Word"
    open "Hard Drive:Microsoft Word:Sample Document"
    set countpara to count paragraphs of document "Sample Document"
    repeat with n from 1 to countpara
        if paragraph style of paragraph n = "Heading 2" then
            set paragraph style of paragraph n to "Heading 3"
        end if
    end repeat
    save document "Sample Document"
    close document "Sample Document"
end tell

However, an AppleScript script can use a single Do Script event to take the most advantage of the internal functionality of Word to duplicate the original macro:

tell application "Microsoft Word"
    Do Script Ø
        "FileOpen \"Hard Drive:Microsoft Word:Sample Document\"
        EditFindStyle .Style = \"Heading 2\"
        EditReplaceStyle .Style = \"Heading 3\"
        EditReplace .Direction = 0, .ReplaceAll, .Format = 1, .Wrap = 1
        FileClose 1"
end tell

Attaching Scripts

A limited form of AppleScript "attachability" within Word is provided through the WordBasic MacScript statement and MacScript$() function. With these, any interface element in Word that can be attached to a macro (for example, menu commands and toolbar buttons) can run a script.

Note that this does not provide arbitrary script object attachability. Word does not provide for attachment of scripts to any object. Thus, it is not possible to write a script which handles particular Apple Events for an attached object. For example, a script cannot be attached to a window so that the script can handle the Close event.

Here is the syntax for the MacScript statement:

MacScript Script$

MacScript accepts a string parameter which may be either a path to a file, or a portion of text in the default scripting language. If the string is a path to a compiled script file or standalone script application, that file is opened and the first script resource is run. Otherwise, the string itself is passed to the default scripting language for compilation and execution.

Here is the syntax for the MacScript$() function:

MacScript$(Script$)

MacScript$() performs exactly as MacScript, except that it returns a string value. If the executed script returns a value, it is coerced into a string and returned. If the executed script does not return a value, an empty string ("") is returned.

For more information, see MacScript in Part 2, "WordBasic Reference."