Developer’s Guide

10-12 Developer’s Guide
The names of the external functions start at string ID 144 for
Windows and are defined as a STR# resource with ID 144 for the
Mac OS. The first exported function name is mapped to ID 0 and
increased incrementally by 1 for each following name. These ID
numbers are then used to switch to the correct processing routine.
The input and result parameters of the External Function message are
Mac OS style Handles that contain text using Macintosh character
set encoding. This means that all numbers are also represented as
text. The result Handle is always empty when the External Function
message is sent. You should only manipulate the Handles using the
memory manager callback routines that are defined in FMExtern.h.
In the Mac OS, the parameters will be real Mac OS Handles, but you
cannot depend on which heap they may be located in. In Windows,
these Handles exist in the FileMaker Pro memory manager pool and
have no relation to anything called a HANDLE in the Win32s APIs.
Depending on the value of the param2 variable, the Full Example
plug-in will run the following external functions:
For information on each external function, see “Description of the
Full Example plug-in’s external functions” on page 10-6.
The Preferences message
The Preferences message, kFMXT_DoAppPreferences, is sent in
response to a user clicking the Configure button for the selected plug-
in in the Application Preferences dialog box.
The plug-in should display a dialog box of some sort that will allow
the user to set any specific configuration data required by the plug-
in. If the plug-in requires user-definable preferences, you should
implement your UI here. The Configure button will only be enabled if
the sixth character of the feature string is set to “Y” (see “Required
feature string syntax” on page 10-8).
Any options that need to be saved should be placed in their own
registry entry or .INI file (Windows) or in their own preference file
(Mac OS).
The Full Example plug-in needs to implement a configuration dialog
box for the Xpl-Format function, so the flag has been set in the
feature string (
Xmpl1YYYnnn) and the function Do_AppPrefs is called
when the Preferences message is received.
Like the
Do_Init function, the code for displaying a dialog box and
setting the preferences is quite different on both platforms, so
preprocessor flags are used to select the appropriate code at compile
time. The Windows code passes the function
prefProc to the
DialogBox routine to control the dialog and set the registry entries.
The Mac OS code also calls an additional function called
writePrefs
to write the preference information to disk.
Debugging your plug-in
You can debug code resources or shared libraries easily if you use
the DisplayMessage function. The DisplayMessage function is
defined in the FMTemplate.c and FMExample.c files.
Your plug-in code could also include a preprocessor instruction to
cause your plug-in to behave differently during the debugging
process. For example, the Full Example plug-in will behave in the
following ways when the DEBUG_VERSION flag is set to “1”:
1 The DebugPlugin routine will be substituted for the PluginVersion
function.
This param2
value
Corresponds to this
external function name
And causes the plug-in
to run this function
0 Xpl-Version PlugInVersion
1 Xpl-BigPI funct_PI
2 Xpl-Format funct_Format
3 Xpl-NumWords funct_Num2Words