Report Plugins

This entry-point is rarely needed or used.  If possible, you should avoid using it.  If you wish to allow the user to choose options, you will normally specify these using the 'options' value in FH_Requirements.  In that case, these options will then be accessible to the user in the Main (first) tab of the ordinary Report Options dialog.  You can specify numerous options of all kinds using this technique.  All such options are saved to the 'Plugin' section of the Report Options file.  You get the path to this file by calling fhGetContextInfo("CI_REPORT_OPTIONS_FILE"), and you can access the values using the fhGetIniFileValue function.

If you have requirements that for whatever reason cannot be handled in that way, the alternative is to implement your own user-defined report options dialog.  This is what FH_PromptUserOptions allows you to do.  If you choose to do this, you should still be sure to save all of the options the user chooses in the usual Report Options file.  You can also use fhGetIniFileValue and fhSetIniFileValue to get and set option values. Your options dialog will be called if the user clicks the More Options link on the default startup dialog (if there is one), or if the user clicks on the Options button in the Report Window.  Your plugin should then prompt the user to choose the options they require, perhaps using an IUP dialog.  Your dialog should also provide some way for the user to access the default report options dialog (via a button or link or menu command, say).  This is because the default report options dialog provides numerous options relating to page layout and possibly other things, which your options dialog will not handle, but which the user will still need to be able to access. If the user clicks the relevant button or link, you should call fnShowDefaultRptOptionsDlg to display the default report options dialog.  fnShowDefaultRptOptionsDlg is FH_Startup's only parameter.  It is an unusual kind of parameter.  Most parameters are text, booleans, numbers, or some kind of object.  fnShowDefaultRptOptionsDlg is a function (or if you prefer, you can think of it as a link to a function).  More specifically, it is a function which takes one parameter and does not return anything.  The parameter it takes is a window handle.  This must be supplied.  It should be either the window handle of your own options dialog (if still visible at this point), or failing that, the 'parent window' handle returned by fhGetContextInfo("CI_PARENT_HWND").  Iup dialogs have a read-only attribute HWND which is the window handle (as a light userdata object).

If special care is not taken, your options dialog could easily disappear behind the main Family Historian application window. To ensure that this does not happen, when you display your report options dialog, you must ensure that your dialog is made a child of an appropriate parent window in the main application.  To do this call fhGetContextInfo("CI_PARENT_HWND") to retrieve the parent window handle, and use iup.SetAttribute to allocate it to your dialog.  The code snippet below shows how this is done.  It might appear that there are other ways of doing this which are equivalent and should work equally well.  However, this is the only way of doing it with main application handles that we have found which works, so we recommend that you stick closely to it.

require("iuplua")
....
dlg = iup.dialog{btn; title="Test dialog"};

iup.SetAttribute(dlg, "NATIVEPARENT", fhGetContextInfo("CI_PARENT_HWND"));  -- Set the parent window handle

dlg:show()
iup.MainLoop()
dlg:destroy()

bOK = FH_PromptUserOptions(fnShowDefaultRptOptsDlg)

fnShowDefaultRptOptsDlg

A function object.  The function takes one parameter (a window handle, passed as a light userdata object), and returns nothing.  Call this function to display the default Report Options dialog.  If hwnd is the required window handle, call it like this:

fnShowRptOptsDlg(hwnd)

Returns

Example

local OptionsFile = fhGetContextInfo("CI_REPORT_OPTIONS_FILE");


....

-- Add this entry-point function to your report plugin to display your own options dialog
function FH_PromptUserOptions(fnShowDefaultRptOptsDlg)

	-- options should be retrieved from, and stored to, the report options file (see above)
	local opt = {};
	opt.title = fhGetIniFileValue(OptionsFile, "Plugin", "title", "text", "");
	opt.alt_title = fhGetIniFileValue(OptionsFile, "Plugin", "alt_title", "text", "");


	-- add your own options dialog here.  

....

-- hwnd is the handle of your options dialog if still visible (or allocate it to fhGetContextInfo("CI_PARENT_HWND") if your options dialog is not visible)

fnShowDefaultRptOptsDlg(hwnd); -- normally you would only call this function if the user clicked to view standard report options

return true
end