Development Guide

Table Of Contents
40 FileMaker Pro Advanced Development Guide
For the FMPluginExample plug-in, the Do_PluginInit function is called
when the Initialization message is received. The
Do_PluginInit function
first checks the version of the API that the plug-in was compiled with to
verify that it’s compatible with the version of FileMaker
Pro, FileMaker
Pro Advanced, or FileMaker Server that has loaded it. Then the function
checks for preferences and sets them if they exist. If no preferences
currently exist, it will create them with default values.
In Windows, these preferences are stored as registry entries. In
Mac
OS X, they are stored in a file within the Preferences folder of the
System Folder. Due to the differences between the way this information
is stored on the two platforms, the
Do_PluginInit function uses
preprocessor instructions to choose the correct code at compile time.
If the preferences are set properly and the API version is correct, the
Do_PluginInit function in the FMPluginExample plug-in will return
kCurrentExtnVersion.
After you set the preferences, register each external function by
providing its name, description, and the function to be used. Use
fmx::ExprEnv::RegisterExternalFunction to register your functions.
Shutdown message
The Shutdown message, kFMXT_Shutdown, is sent to the plug-in
whenever it is disabled in FileMaker
Pro, FileMaker Pro Advanced, or
FileMaker Server. This may or may not correspond with the quitting
of the application, depending on whether the plug-in is disabled in the
Preferences dialog box.
The FMPluginExample plug-in does not allocate any persistent
memory on the heap, and therefore does not do anything when it
receives the Shutdown message. You should implement a clean-up
function in your plug-in, however, to deallocate anything you have on
the heap and exit from any operating system services you may be using.
It’s possible for a plug-in to be enabled and disabled multiple times
during a session, so it’s important for your plug-in to clean up memory.
Unregister each external function registered during the Initialization
message using
fmx::ExprEnv::UnRegisterExternalFunction.
Idle message
The Idle message, kFMXT_Idle, is only sent to the plug-in during idle
time if the idle feature flag was set to “
Y” in the option string and the
plug-in is currently enabled.
There are five times when this message is called by the FileMaker
application.
If the idleLevel parameter is not zero, then the routine has been called
while the application is running a script or is being controlled by the
user. One of the following four messages has been sent:
Do not perform any lengthy, user interface, or event processing when
the
idleLevel parameter is not zero.
The Idle message will also be sent is when the application detects free
time and does its own internal idle handling.
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
Preferences dialog box.
Message Meaning
kFMXT_UserNotIdle = 1 The user has done something within the last 30
seconds.
kFMXT_ScriptPaused = 2 The user is running a script that has been paused.
kFMXT_ScriptRunning = 3 The user is running a script.
kFMXT_Unsafe = 4 Same as if the unsafeCalls parameter is set to true.
Message Meaning
kFMXT_UserIdle = 0 The user hasn’t done anything within the last 30
seconds or more.