WHY?
The Plugin Tool is an instrument that can be used to run external executables (from complicated to simple) or batchfiles within iMOD.
WHAT?
The Plugin tool makes it possible to include advanced plugins that come close to fully software integration as well as plugins that simply run an executable file. This allows you to start a specific program within an iMOD-session without stop working in this session. A number of pre-settings and couplings are necessary before you can launch a plugin. iMOD needs information about the plugin and vice versa.
HOW?
Before starting the iMOD Plugin Tool, you need to walk through a couple of preprocessing steps before a plugin can be used within the iMOD gui.
1. Predefine PLUGIN1= and/or PLUGIN2= in the iMOD preference file (IMOD_INIT.PRF). With these two keywords you can set the specific file-directory where iMOD can find the plugin(s). You are able to use two different plugin-directories inside iMOD. The iMOD preference file might look like this (See section 9.1 for a more extended description of the preference file):
PLUGIN1 "C:\PLUGIN1"
PLUGIN2 "E:\PLUGIN2"
2. Create a subfolder with the plugin-name in which you can store all the needed "coupling"-files, including the executable file itself. Note: this subfolder should be located in de PLUGIN1 or PLUGIN2 folder.
3. An initialization file called PLUG-IN.INI, needs to be created that should be placed within the plugin-subfolder. This file can contain the following keywords:
|
Keyword |
Description | ||
|
TXT= |
This keyword is linked to the filename of the text file that contains a short description of the plugin. | ||
|
CMD= |
With this keyword the specific plugin-executable or batch-file is called. You have to make an additional choice whether you prefer to run the plugin in "WAIT" modus or in the background ("NOWAIT") of other iMOD-processes, e.g. CMD=DEMO.EXE NOWAIT | ||
|
MENU= |
This keyword is optional. MENU refers to a file that describes an optional menu to be displayed, before the actual plugin will start, e.g. MENU=D:\PLUGIN1\PLUG-IN.MENU. The file contains the visual-settings of the specific plugin window. See description in section section 7.7.1 for the PLUG-IN.MENU setup. | ||
|
HELP= |
This keyword is optional and refers to the helpfile related to the plugin itself (PDF or HTML). In case the helpfile is in PDF-format, the keyword ACROBATREADER is needed to be defined in the preference file to be able to read the PDF-file. | ||
|
BACK= |
With this keyword you specify a filename that iMOD will check repeatedly (minute time interval), e.g. BACK=PLUG-IN.OUT, see section section 7.7.1 for more detailed information about the content of this file. | ||
Example1
TXT= WATERBALANCE.TXT
CMD= WATERBALANCE.EXE WAIT
Example2
TXT= RASTERCONVERSION.TXT
MENU= RASTERCONVERSION.MENU
HELP= RASTERCONVERSION_MANUAL.PDF
CMD= RASTERCONVERSION.EXE NOWAIT
BACK= RASTERCONVERSION.OUT
The files related to the keywords are described in section section 7.7.1.
4. Now the Plugin Tool can be used. For the steps to be taken see section 7.7.2
Note: You are able to save the activated plugins for later use within the IMF-file. You can do this by saving the current iMOD project session via the Save-button or via File->Save as... in the main-menu. Also the chosen time interval (see TMO.PITools.execution how to set this interval) on which iMOD tests whether a plugin is running or not, is saved in the IMF-file.
In the PLUG-IN.INI different initialization files are listed behind the above explained keywords. Some of these files also contain a list of keywords. We will explain them here.
All keywords are optional.
|
Keyword |
Description | ||
|
TITLE= |
Optional keyword that sets the title of the menu window, e.g. TITLE="This plugin computes residuals". | ||
|
BUTTON1= |
Optional keyword that sets the text on the Close-button, e.g. BUTTON1=Afbreken. | ||
|
BUTTON2= |
Optional keyword that sets the text on the Help-button, e.g. BUTTON=Hilfe. | ||
|
BUTTON3= |
Optional keyword that sets the text on the Apply-button, e.g. BUTTON3=Go-for-it | ||
|
LIST= |
Optional keyword that loads all available files from a certain place or directory. If not defined, iMOD shows a diaolog in which you need to select files yourself. The following options are available: | ||
|
IMODMANAGER |
Whenever LIST=IMODMANAGER, iMOD will display the selected files from the iMOD Manager in a separate window. Be aware that iMOD places a ’+’-sign in front of the directory name in case the related file is selected in the iMOD Manager and a ’-’-sign in case the file is not selected! To be able to read the file properly the plugin needs to handle this. Example  Use the buttons left and right to move the selected items from left to right or the other way around . |
||
|
*.IDF / *.* |
Whenever LIST=*.IDF iMOD will display a dialog in which files can be selected, e.g. IDF-files. Any combination of wildcards can be uses, e.g. LIST=*.*, LIST=*.RUN, or whatsoever the plugin need as an input. Example  Use the "open"-button (  ) to add files to the dialog. |
||
|
TEXT= |
Refers to an addition text file with explanatory text with requirements for using the chosen plugin, e.g. TEXT=EXPLAINATION.TXT. | ||
The list of files defined with keyword LIST or by making use of the plugin menu-dialog, is stored in a file called "PLUG-IN.IN" (see section 7.7.1.2).
Example1
TITLE= Compute Waterbalance
BUTTON1= Quit
BUTTON2= Info
BUTTON3= Run
LIST= IMODMANAGER
TEXT= EXPLAIN.TXT
Example2
TITLE= Convert Raster settings
LIST= *.IDF
TEXT= EXPLAIN.TXT
The list of files that is used by the plugin is saved in this file "PLUG-IN.IN", and can serve as a checkup for the user of the plugin. In case LIST="IMODMANAGER" is given in the MENU-file, iMOD puts a ’+’- or a ’-’-sign in front of each individual file listed in PLUG-IN.IN. The ’+’-sign is written when a file is selected in the iMOD manager, else a ’-’-sign appears.
This file needs to be written by the plugin executable after or during its execution. It needs to be prepared within the code of the plugin. To allow iMOD to interact with the plugin, it is required to include at least one of the following keywords in the OUT file.
|
Keyword |
Description | ||
|
WINDOW= |
With this keyword the plotting window extent (decimal coordinates) in iMOD can be set. Once this is read, iMOD will adapt the current window extent to the extent mentioned by WINDOW. Use the format: XMIN,YMIN,XMAX,YMAX, e.g. WINDOW=10000.0,250000.0,150000.0,300000.0. | ||
|
NFILE= |
Number of files to be read into the iMOD Manager. | ||
|
FILE{i}= |
The i\(^{\rm th}\) file to be read into iMOD Manager, e.g. FILE1=FLUX.IDF. Given file needs to be available in the specific plugin-(sub)folder. Only name of the (subfolder+)file+extension are needed to be given. As mentioned the use of subfolders is allowed. | ||
|
MESSAGE_{...}= |
Contains some text lines to be given at a certain moment in de executable process. | ||
|
{INFO} |
Contains general information to be given in a popup window at a certain moment during de executable process. | ||
|
{ERROR} |
Contains error-information to be given in a popup window at a certain moment during de executable process. | ||
|
{PROGRESS} |
Contains progress-information to be given at a certain moment during de executable process. This will be visible in the information-bar at the bottom of the iMOD main-window. | ||
Note: It is the responsibility of the plugin owner to process the message(s) of the plugin in the right way and at the right moment. After reading the OUT-file, iMOD will delete the file from disc to avoid any double interpretation of the file.
Example1
WINDOW= 140000.0,445000.0,150000.0,452000.0
NFILE= 2
FILE1 = WBAL_2014_SUMMER.IDF
FILE2 = WBAL_2014_WINTER.IDF
MESSAGE_INFO= "The waterbalance is succesfully calculated."
Example2
MESSAGE_PROGRESS= "Plugin is still busy ..."
To start the Plugin Tool from the main menu, choose Plug-in. A sub-menu will appear. If you did define PLUGIN1 and/or PLUGIN2 in the iMOD preference file, you can choose Manage Plug-in 1 ... and/or Manage Plug-in 2 .... To start the Plugin Manager window, click on either of the two.
Example of Plugin Manager window
|
Plugins (folder name) |
The list displays all sub-folders in the {PLUGIN1}\folder. Click on the sub-folder. If a {PLUGIN}.txt is available in the sub-folder an explanatory text of the plugin will appear in the sub-window below. |
|
Active |
Select the check box to (de)activate a specific plugin. When you activate a plugin, the plugin appears in the main sub-menu Tools and Plugin. |
|
Apply |
Click this button to apply your plugin-settings and to close the window. |
|
Cancel |
Click this button to close the window and not applying your modified plugin-settings. |
|
Help… |
Click this button to start the Help functionality. |
After clicking on Apply button, the activated plugins are added to the Plugin menu. At maximum, 10 plugins can be activated at once into this menu list. The Plugin-menu might look like this:
It depends on the configuration of the Plugin what will happen whenever the plugin is selected from the menu. During the whole running process iMOD checks at predefined fixed moments (intervals of 60, 30, 15 or 1 seconds) if there are plugins running. The running check time interval can be changed by selecting the similar called option in the Plug-In menu (see figure below). On default this interval is set on 60 seconds. As long as a single plugin or multiply plugins are running, the plugin manager(s) cannot be reached (Menu options are grayed-out) for making changes. Though you are able to use already selected plugins from the plugin-menu.
As shown in the example above, only the plugins that are running are grayed-out. If there are still plugins running when trying to close iMOD, iMOD asks the following question for every plugin that is running:
Note: When using a batch file as a plugin to call an executable, this plugin cannot be terminated by iMOD. The plugin continues running after iMOD is closed.