Developer’s Guide

Developing third-party FileMaker plug-ins 67
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.
The plug-in should display a dialog box 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
user interface here. The
Configure button will only be enabled if the
sixth character of the option string is set to “Y.” For more
information, see
“Option string syntax” on page 65.
Any options that need to be saved should be placed in their own
registry entry (Windows) or in their own preference file
(Mac
OS X).
The FMExample plug-in needs to implement a configuration dialog
box for the
XMpl_UserFormatNumber function, so the flag has been set
in the option string (Xmpl1Ynnnnn) and the function Do_PluginPrefs is
called when the Preferences message is received.
External Function message
The External Function message, kFMXT_External, is a legacy
message for old style plug-ins. It is no longer required for plug-ins
that are registered in the new style.
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.