Developing Macros for More Than One Platform

The WordBasic macro language is shared across platforms, but there are a few things to take into account when developing cross-platform macros. This section organizes cross-platform issues into three areas:

Using platform-specific instructions and arguments
Handling platform-level differences
Moving cross-platform macros between platforms

Most of this section deals with differences between the Macintosh and Windows platforms. There are very few WordBasic differences between the Windows 3.x, Windows 95, and Windows NT versions of Word. For the most part, you don't need to worry about Windows differences unless you're declaring external functions, which may need to be declared differently in Windows 95 and Windows NT (see "Using the Declare Statement to Call External Routines" later in this section).

You use the AppInfo$() function to return the name of the current platform. In Windows, AppInfo$(1) returns a string containing "Windows," "Windows 95," or "Windows NT" and the version number; on the Macintosh, it returns a string containing "Macintosh" and the system software version number. After you've determined the platform, you use a control structure to run the appropriate block of instructions for that platform.

The following example uses InStr() to determine whether the string returned by AppInfo$(1) contains the word "Macintosh"; if it does, the flag variable, MacintoshFlag, is set to 1. A control structure then tests the value of the MacintoshFlag variable to determine whether to run instructions for Windows or for the Macintosh.

If Instr(AppInfo$(1), "Macintosh") <> 0 Then MacintoshFlag = 1
If MacintoshFlag = 0 Then
    ChDir "C:\WINWORD6\TEMPLATE"
    FileOpen "ARTICLE.DOT"
Else
    ChDir "HD:MICROSOFT WORD 6:TEMPLATES"
    FileOpen "ARTICLE TEMPLATE"
End If

Using Platform-Specific Instructions and Arguments

WordBasic includes a number of statements and functions that are specific to a particular platform. A statement or function intended for use on one platform only will produce an error if run on another platform. In addition, some dialog-equivalent statements take arguments that are valid on one platform only. Once you use AppInfo() to determine which platform the macro is running on, you can use a control structure to ensure that platform-specific statements, functions, and arguments run only when the macro is running on the appropriate platform.

The following paragraphs describe significant areas where Windows and Macintosh statements differ. For a complete list of Macintosh- and Windows-specific statements and functions, see "Language Differences Across Versions of Word" in Part 2, "WordBasic Reference."

Differences in Page Setup

Because of differences in printing and page setup in Windows and on the Macintosh, the FilePageSetup statement is available only in Windows. A separate set of statements is provided for page setup on the Macintosh: FileDocumentLayout, FileMacPageSetup, FileMacCustomPageSetupGX, and FileMacPageSetupGX. On a Macintosh with QuickDraw™ GX installed, use FileMacCustomPageSetupGX and FileMacPageSetupGX instead of FileMacPageSetup.

You can use the GetSystemInfo$() function to determine whether QuickDraw GX is installed. The return value of GetSystemInfo$(519) is "Yes" if QuickDraw GX is installed and "No" if it is not.

Custom Dialog Box Accelerators

When you display a custom dialog box on the Macintosh, accelerators specified in the dialog box definition do not appear with an underline. However, the accelerators do work as expected. After the user presses the COMMAND key, an underline appears under the specified characters.

To automatically display accelerators in a dialog box (without the user pressing the COMMAND key), add a MenuMode instruction to the macro before displaying the custom dialog box, as shown in the following macro:

Sub MAIN
MenuMode
Begin Dialog UserDialog 320,144, "Microsoft Word"
OKButton 10, 6, 88, 21
CancelButton 10, 30, 88, 21
CheckBox 150, 84, 100, 18, "C&heck Box", .CheckBox1
End Dialog
Dim dlg As UserDialog
n = Dialog(dlg)
End Sub

Differences in WordBasic Sort Order

The ANSI character sort order differs between the Macintosh and Windows. The specific sort order of ANSI characters is relevant when you write WordBasic macros that compare strings. The sort order is predictable for alphabetic and numeric characters (for example, "A" comes before "B" and "3" comes before "4"). However, the sort order for the remaining characters is not predictable. To determine whether "!" is greater than or less than "?" on the current platform, you can create an array of those characters and use the SortArray() function to sort them.

Screen Updating

In Windows, the ScreenUpdating statement turns off screen updating so that changes to document and application windows are not displayed on the screen. On the Macintosh, changes within document windows are not displayed, but changes to the document window frame are displayed. For example, if a document window is moved while screen updating is turned off, the document window frame is shown in the new position. Likewise, if a document is opened while screen updating is turned off, the document's window frame will be displayed (the document itself will appear blank until screen updating is turned on, or until the macro ends).

Using SendKeys

On the Macintosh, a SendKeys instruction can send no more than 10 keystrokes, and can send them only to Word; SendKeys cannot be used to send keystrokes to another application. You can send a SHIFT key combination using the plus sign (+), but you cannot send key combinations including OPTION or COMMAND. For a list of keystrokes supported by SendKeys, see Part 2, "WordBasic Reference."

Differences in Custom Dialog Box Capabilities

On the Macintosh, you can store the picture displayed in a picture dialog box control in a "resource fork" (you can use Picture or DlgSetPicture to specify a resource fork as the storage place). Also available on the Macintosh are two instructions, DlgStoreValues and DlgLoadValues(), with which you can store and load custom dialog box settings. In Word version 6.0 for the Macintosh, Word version 6.0 for Windows NT, and Word version 7.0, you can use a single DlgVisible instruction to show or hide a range of controls (in Windows 3.x, a single DlgVisible instruction can affect one control only).

The DlgFocus statement does not change the focus in a Word version 6.0 for the Macintosh custom dialog box.

The following commands, which control the size or position of custom dynamic dialog boxes in the Windows versions of Word, are not available and generate errors in Word version 6.0 for the Macintosh: AppSize, AppMove, AppWindowHeight, AppWindowWidth, AppWindowPosTop, AppWindowPosLeft

Making a Network Connection

In Windows, you can use the Connect statement to connect to a network drive; on the Macintosh, you can use the MountVolume statement. You can use Connect to display the Connect dialog box; MountVolume does not have a dialog box associated with it.

Handling Platform-Level Differences

Even when a WordBasic statement or function has the same result on all platforms, the code may need to be different. Different platforms have different system-specific functionality such as file-naming conventions that need to be considered in cross-platform macros.

Specifying Filenames and Paths

In Windows, you use the question mark (?) and asterisk (*) wildcards to specify a group of files. Wildcards are not accepted on the Macintosh, but you can use the MacID$() function to specify files of a certain type. A Macintosh file type is a unique four-letter label assigned to every file created by a Macintosh application (you can use the FileType$() function to determine a file's type).

The following example creates a list of all the text files in a folder (the MacintoshFlag variable has been set earlier in the macro):

If MacintoshFlag = 0 Then
    textfilename$ = Files$("*.TXT")
Else
    textfilename$ = Files$(MacID$("TEXT"))
End If
Insert textfilename$
While textfilename$ <> ""
    textfilename$ = Files$()
    Insert textfilename$
Wend

MacID$() can also be used to specify file types with the FileOpen and Kill statements. The following instructions display the Open dialog box showing a list of all the template files in a folder (the MacintoshFlag variable has been set earlier in the macro):

Dim dlg as FileOpen
GetCurValues dlg
If MacintoshFlag = 0 Then
    Chdir "C:\WINWORD\TEMPLATE"
    dlg.Name = "*.DOT"
Else
    Chdir "HD1:WORD:TEMPLATES"
    dlg.Name = MacID$("WTBN")
End If
choice = Dialog(dlg)
If choice Then FileOpen dlg

Note

Although MacID$() appears to return a string, it actually returns a value that doesn't correspond to any WordBasic data type. Consequently, MacID$() should be used only with the statements described here that accept the internal value it returns. In addition, you cannot concatenate the value returned by MacID$() with a path string; instead, you use ChDir to change the current folder.

You can use MacID$() with a Macintosh application signature to specify an application. MacID$() can be used to specify an application with the following instructions: AppActivate, AppClose, AppCount, AppGetNames, AppGetNames(), AppIsRunning(), and Shell. MacID$() provides a more reliable way to specify an application than the application name, because the user may change the application name but is not likely to change the Macintosh application signature. The following example uses MacID$() with AppIsRunning() and Shell to determine whether Microsoft Excel is running, and to start it if it isn't.

If AppIsRunning(MacID$("XCEL")) = 0 Then Shell MacID$("XCEL")

Note that you don't need to specify a path or folder when you use MacID$() to specify an application.

Using Settings Files

There are a few differences to be aware of when working with settings files in Windows 3.x and on the Macintosh.

If you don't specify a path in the filename for SetPrivateProfileString or GetPrivateProfileString, Word stores or looks for the file in the Windows folder in Windows or the Preferences folder on the Macintosh.
In Windows, settings files are text files and they can be opened by a text editor like any other text file. On the Macintosh, settings files are not text files; they can be edited directly using the ToolsAdvancedSettings command or the ResEdit program.
The Macintosh does not include an equivalent of the Windows WIN.INI file that can be accessed by SetProfileString and GetProfileString$().
In Word version 6.0 for Windows, settings are stored in a settings file called WINWORD6.INI; in Word version 6.0 for the Macintosh, they're stored in a file called Word Settings (6). You can use SetPrivateProfileString and GetPrivateProfileString$() to change settings in WINWORD6.INI or Word Settings (6). For example:
```
a$ = GetPrivateProfileString$("Microsoft Word", "USER-DOT-PATH", \
    "Word Settings (6)")
```

Note

Windows 95 and Windows NT do not use the settings files WIN.INI and WINWORD6.INI. Instead, settings are stored in the registry. For information about returning and setting values in the registry, see "Accessing the Windows Registry" earlier in this chapter.

Working with DDE

When an application runs on more than one platform, the same application may have a different application name in Windows and on the Macintosh. For example, in Windows, the DDE application name for Microsoft Word is "WinWord," whereas on the Macintosh, it's "MSWord," although "WinWord" is also accepted.

The instructions used to initiate DDE conversations are the same in Windows and on the Macintosh, but since DDE application names may be different on different platforms, separate instructions may be necessary for each platform. Also, it's a good idea to use MacID$() to specify an application on the Macintosh if you use the AppIsRunning() and Shell instructions when initiating a DDE conversation. In the following example, a different block of instructions for each platform is used to initiate a DDE conversation with Microsoft Excel (the MacintoshFlag variable has been set earlier in the macro). Note that Microsoft Excel has the same DDE application name in Windows and on the Macintosh, so separate DDEInitiate() instructions are not needed.

If MacintoshFlag = 0 Then
    If AppIsRunning("Microsoft Excel") = 0 Then Shell "EXCEL.EXE", 4
    chan = DDEInitiate("Excel", "System")
Else
    If AppIsRunning(MacID$("XCEL")) = 0 Then Shell MacID$("XCEL"), 4
    chan = DDEInitiate("Microsoft Excel", "System")
End If
chan = DDEInitiate("Excel", "System")
topics$ = DDERequest$(chan, "Topics")
Insert topics$

Using the Declare Statement to Call External Routines

In Windows, you can use the Declare statement to call routines stored in a dynamic-link library (DLL) or a Word add-in library (WLL). On the Macintosh, only routines stored in a WLL can be called. When a macro created in a Windows version of Word is converted to Word version 6.0 for the Macintosh, any Declare statements that refer to Windows DLLs will return the WordBasic error 543, "Unable to open specified library."

Declare instructions in macros ported from Word version 6.0 for Windows to Word version 7.0 or Word version 6.0 for Windows NT need to be modified. Because you cannot declare an external routine in a 16-bit library from a 32-bit application, such as Word version 7.0 or Word version 6.0 for Windows NT, you must update macros that declare routines in 16-bit libraries to identify the 32-bit versions of those libraries. Also the names, locations, and parameters of many Windows 3.x operating system routines (often referred to as API calls) changed in Windows 95 and Windows NT. You must update macros that declare Windows 3.x API calls to declare the correct routines in Windows 95 or Windows NT. Windows 95 and Windows NT function libraries are documented in the Microsoft Win32 Software Development Kit.

Unlike routine names in Windows 3.x, routine names are case-sensitive in Windows 95 and Windows NT. In addition, some routines need to be declared with different variable types in Windows 95 or Windows NT: INT return values or parameters must be declared as LONG; handles must be declared as LONG. For more information on using the Declare statement, see "Calling Routines in DLLs" earlier in this chapter.

Moving a Cross-Platform Macro Between Platforms

There are two potential problems that can occur when you move a macro with platform-specific instructions between Word version 6.0 for Windows and Word version 6.0 for the Macintosh. These problems occur when one version of Word does not recognize instructions that are supported in another version. Specifically, Word version 6.0, 6.0a, and 6.0c for Windows do not support the Macintosh-specific WordBasic statements and functions available in Word version 6.0 for the Macintosh. In this situation, the following two problems can occur:

If you develop a macro in Word version 6.0, 6.0a, or 6.0c for Windows and then move the macro to Word version 6.0 for the Macintosh, instructions specific to the Macintosh version of Word will produce an error — error 124, "Unknown command, subroutine, or function" — until the macro is edited on the Macintosh (the macro must be "dirtied").
If you develop a macro in Word version 6.0 for the Macintosh, move the macro to Word version 6.0 or 6.0a for Windows, and then edit and save the macro in Windows, Macintosh-specific keywords will be removed from the macro; they will not be restored if the macro is moved back to the Macintosh. (The macro should still run correctly in Windows, since the Macintosh-specific instructions should not run on the Windows platform anyway. But the macro will no longer run correctly if it is moved back to the Macintosh.) Note that this problem does not occur in Word version 6.0c for Windows.

Note

These problems do not occur if you develop cross platform macros in Word version 7.0 or Word version 6.0 for Windows NT.

Typically, a cross-platform macro is developed on one platform and then tested on the other platforms for which it is intended. If you're working with Word version 6.0 or 6.0a for Windows, you need to avoid editing the macro on more than one platform. That is, once you choose a platform for developing a Word 6.0 or 6.0a cross-platform macro, you must stick with it; if you edit the macro on more than one platform, you may encounter problems.

If you develop cross-platform macros in Word for Windows, you need to make sure the macros run properly on the Macintosh before you distribute them. You may want to distribute your cross-platform macros in execute-only format so that they cannot be edited (you use the MacroCopy statement to make a macro execute-only). If you don't want to distribute your cross-platform macros in execute-only format (that is, if you don't want to disable editing), you run the risk that a user will edit the macro.

Moving a Macro with Extended Characters Between Platforms

In Windows and on the Macintosh, different character codes are used to represent international characters. If you create a macro that contains string values with international characters in them (for example, á, ç, and ö), these characters will change when the macro is opened or run on another platform. To avoid this result, use the following steps to move the macro between platforms:

1. Copy the text of the macro from the macro-editing window into a new document and save the document.

2. Open the document on the other platform, save it in Text Only format, close it, and then open it again.

3. Copy the text from the document into a new macro-editing window.

Note that distributing a macro as execute-only does not correct this behavior. If you need to distribute a macro with extended characters in string values, you must create separate templates with unique versions of the macro for each platform.