functions

fhInitialise

Description

This is a special function. It isn't necessary to call it, but if it is called, it should be the first function called in the plugin, and it should only be called once. It allows any plugin to specify minimum Family Historian version requirements. And it also allows a plugin (unless it is a read-only plugin) to require or recommend that any unsaved changes made to the current file or project be saved, prior to running the plugin.

It is an error to call this function after calling any function that changes data in any way.

Syntax

bResult = fhInitialise(iMinVer1 [, iMinVer2 [, iMinVer3, [, strSaveRequirements]])

Parameters

iMinVer1

The first digit of the minimum version of Family Historian that is required to run this plugin.

iMinVer2 (optional)

The second digit of the minimum version of Family Historian that is required to run this plugin (defaults to zero if not supplied).

iMinVer3 (optional)

The third digit of the minimum version of Family Historian that is required to run this plugin (defaults to zero if not supplied).

strSaveRequirements (optional)

String: Must be blank for read-only plugins (e.g. report type plugins). For other plugins, if supplied, it must be one of the following:

save_recommended	If there are any unsaved changes, a dialog box will tell the user that saving changes is recommended, and ask if he/she wishes to save now. The dialog box will have 3 buttons: Yes, No and Cancel. If the user clicks Yes, changes will be saved, and the function will return true. If the user clicks No, changes will not be saved and the function will return false. If the clicks Cancel, the function will not return, and the plugin will terminate immediately.
save_required	If there are any unsaved changes, a dialog box will tell the user that saving changes is required, and ask if he/she wishes to save now. The dialog box will have 2 buttons: OK and Cancel. If the user clicks OK, changes will be saved, and the function will return true. If the clicks Cancel, the function will not return, and the plugin will terminate immediately.

save_recommended

If there are any unsaved changes, a dialog box will tell the user that saving changes is recommended, and ask if he/she wishes to save now. The dialog box will have 3 buttons: Yes, No and Cancel. If the user clicks Yes, changes will be saved, and the function will return true. If the user clicks No, changes will not be saved and the function will return false. If the clicks Cancel, the function will not return, and the plugin will terminate immediately.

save_required

If there are any unsaved changes, a dialog box will tell the user that saving changes is required, and ask if he/she wishes to save now. The dialog box will have 2 buttons: OK and Cancel. If the user clicks OK, changes will be saved, and the function will return true. If the clicks Cancel, the function will not return, and the plugin will terminate immediately.

Return Value

bResult: The value returned will always be true (if the function returns at all), unless the "save_recommended" option is used, and the user (when prompted to save unsaved changes), clicks 'No', in which case it will return false.

ExampleS

fhInitialise(7)
fhInitialise(7,0)
fhInitialise(7,0,0)
fhInitialise(7,0,0, "save_required")
fhInitialise(7,0,0, "save_recommended")