External functions in a library are called add-ins, or add-in functions. Add-in functions for Word are faster and more efficient than equivalent WordBasic macros because they are written in C and compiled, and can take advantage of the full functionality of the operating system. You can declare and call external add-in functions in a WLL from WordBasic, or they can be registered with Word using the functions in the Word API.
In Windows, a Word add-in library (WLL) is a stand-alone dynamic-link library (DLL) with the filename extension .WLL (once built, the DLL filename extension is renamed to WLL so that the file can be identified as a Word add-in library). On the Macintosh, a WLL is a WDLL code resource, which is designed especially for Word. The rules for compiling, linking, and building a WLL are the same as those for creating a DLL (Windows) or code resource (Macintosh). What sets a WLL apart are the special functions that Word looks for and calls automatically when the WLL is loaded and unloaded: wdAutoOpen and wdAutoRemove.
Word uses these two functions as automatic points of entry into a WLL. Word calls the wdAutoOpen function when the WLL is loaded. This is where the WLL should register its functions and customize Word so that the functions can be called from menu items or toolbar buttons. After doing so, the function returns a value to Word indicating success or failure (on the Macintosh, the function must return the value to the main routine, which in turn returns the value to Word). Here is the syntax:
// Windows short FAR PASCAL wdAutoOpen( short DocID ); // Macintosh short wdAutoOpen( short DocID );
Word calls the optional wdAutoRemove function, if included, when the WLL is being unloaded, either by the user or when Word shuts down. Here is the syntax:
// Windows void FAR PASCAL wdAutoRemove( void ); // Macintosh void wdAutoRemove( void );
This function can be used to free dynamically allocated memory when the WLL is unloaded. In addition, if your WLL makes permanent changes to the Normal or active template, you should include the wdAutoRemove function to remove any customization that you don't want the template to retain. If your WLL does not specify permanent changes, the Normal or active template is not "dirtied" by the WLL; all customization is temporary and is automatically removed when the WLL is unloaded. In that case, the wdAutoRemove function is not necessary.
For descriptions of the other WLL-specific functions that Word makes available through the Word API, see "Word API Functions" later in this appendix.
For the most part, there's a one-to-one correspondence between the statements and functions in WordBasic and those that can be called from an add-in function in a WLL. However, the Word API is intended to provide word-processing functionality rather than to duplicate WordBasic functionality. Therefore, elements of the WordBasic language such as control structures, variable declarations, basic file I/O, and custom dialog boxes cannot be called from an add-in function in a WLL. Also note that you can run existing WordBasic macros through the Word API just as you would use the WordBasic ToolsMacro statement, but you cannot access the functionality of the WordBasic Call statement to pass arguments or run specific subroutines or functions.
In addition to wdAutoOpen and wdAutoRemove, described earlier, there are a handful of Word functions that are available only to WLLs through the Word API. For information on these Windows and Macintosh functions and their use in WLLs, see "Word API Functions" later in this appendix.
There are several ways to load a WLL, either directly by the user or automatically when Word is started or a WordBasic macro is run.
From the File menu, choose Templates. Word displays the Templates And Add-ins dialog box. Under Global Templates And Add-ins, choose the Add button. In the Add Template dialog box, select Word Add-ins in the list of file types, and then select a WLL. Choose OK to add the WLL to the list of selected add-ins. When you close the Templates And Add-ins dialog box, Word loads the WLL.
From the File menu, choose Open. Type the path and filename
of the WLL to load it. To see a list that includes all WLLs in the selected folder, type *.wll in the File Name box and choose OK (Windows) or select All Files in the List Files Of Type box (Macintosh).
A WLL can be loaded from any WordBasic macro, or from a function in another WLL, by calling AddAddIn. This statement and others used in WordBasic macros to work with Word add-in libraries are described in Part 2, "WordBasic Reference."
If a WordBasic auto macro, such as AutoExec, AutoNew, or AutoOpen, is available, Word runs it automatically. You can use the AddAddIn statement in any auto macro to automatically load a WLL. For example, an AutoExec macro in the Normal template can automatically load a WLL every time Word is started.
All WLLs located in Word's designated startup folder will automatically load when Word is started. To set the startup folder, choose Options from the Tools menu, select the File Locations tab, and then specify the folder for the Startup option.
In Windows, you can load a WLL when Word is started by adding an /l command line switch to the command line for a Microsoft Word program item in Program Manager (Windows 3.x and Windows NT) or a Microsoft Word shortcut in Windows Explorer (Windows 95). The following example command line loads CAPI.WLL when Word is started.
c:\winword\winword.exe /lc:\winword\templates\capi.wll
On the Macintosh, you can modify the Word Switches setting in Word Settings (6) to load a WLL when Word is started. For information about modifying this setting, see "Startup Switches" in WordBasic Help.
Note
It is also possible for a WordBasic macro to declare and then directly call a function in a WLL, but this doesn't guarantee that the WLL will be loaded as expected. Unless the WLL is loaded in one of the ways described above, the wdAutoOpen function does not have the chance to register other functions, and any intended modifications to menus or toolbars will not be made.