How to Create a Simple Project
Using Argus PIEs
Introduction
The following paper documents a PIE product that
was developed using Argus' published PDK, based on GenericExport.DLL which was
published on our Web site in March 1997. This product uses the strength of the
PIE technology to implement a "flat text file" mechanism (as suggested by Dr.
Cliff Voss of the USGS) which allows one to automate the creation of stationery
Argus ONE projects.
The PIE is compatible with Argus ONE version 4 or later.
Overview
The following solutions allow model developers, who
are not familiar with C programing, to create simple Graphical User Interfaces
(GUIs) for numerical models. These solutions, based on the existing Argus PIE
technology, allow one to interface with codes (models), from the simple creation
of a "stationery" document for a model code, and up to the creation of a full
featured code interface with dialogs and menus. This is achieved through the use
of a ready-made Generic PIE (provided from our web site) and "flat text file"
interface which may or may not interact with an external program written in any
language.
The simplest form of using this ready-made Generic PIE completely eliminates the
need for programing. The more advanced form allows an external application
(written in any language) to interact with the ready-made Generic PIE, through a
series of pre-defined ASCII (text) files.
The four different uses of the Generic PIE described below are:
The only noticeable limitation
presented by this approach, as compared with advanced PIEs developed using DLLs
or Shared Libraries, is that this approach does not allow adding and deleting
Argus ONE layers after a project has been defined (see MODFLOW GUI-PIE).
To develop function PIEs, import PIEs, interpolator PIEs, etc. one needs to
use the C interface PIE Development Kit.
Click here
to download all the necessary examples which also include source code for Visual Basic and
JAVA and executable examples for an external application which interacts with
the Generic PIE. Examples and source codes in other languages (e.g. Delphi
Pascal) will be made available in the future.
To Create a stationery PIE
A stationery PIE is a PIE
that creates a customized Argus ONE document without interacting with the user
through dialog boxes. Such a PIE performs two tasks: - Installs
menu items under the PIEs menu, which when invoked, will create a new project and
export information to the model.
- Creates a stationery document according to a certain layer structure. The
layer structure may include the layers, parameters, links, expressions, etc.
which are required for the project.
- After the user completes spatial data entry, the PIE exports the information
as input files in the required format and may run the model.
To create
a stationery PIE, the PIE developer needs to define a layer structure and an
export template. For that purpose follow the steps below: - Build a
sample ArgusONE document: Such a document needs to contain the layer
structure required by the project, as well as the export-template that will
export the information properly.
- Save the layer structure description:
- Open the Layers Dialog (View/Layers...)
- Hold the Shift key, and click on the "Copy" button.
That will copy a text description of the layout to the clipboard. - Open a
text editor (such as windows Notepad), choose Paste and save the text file
If your PIE name is, for example, "MyPIE", you should name the layout file
"MyPIE.LAY" (the term "MyPIE" is repeated throughout this document as the name of
the PIE, you should replace it by the name of your PIE).
- Save the export template: Open the export template editor
(File/Export/Edit Template...) and click the "Save" button. Name the template
file "MyPIE.MET".
To have your PIE up and running, copy the
GenericProject.DLL file into the "ArgusPIE" directory within the "Argus
Interware" directory (it is recommended to create a directory within it, such as
"MyPIE" which will contain all the required files). Rename the GenericProject.DLL
to "MyPIE.DLL". Also copy the "MyPIE.LAY" and "MyPIE.MET" files to this
directory.
When running ArgusONE, "MyPIE" is loaded. It is listed in the PIEs list , both
in the Greeting and in the About windows. A new menu item "New MyPIE Project..."
will appear in the PIEs menu. Selecting this command will create a new untitled
copy of the stationery document harboring the layer structure supplied in the LAY
file. When this file is the active one, and the active layer is a mesh or grid,
another item "Export MyPIE..." will be added to the PIEs menu. This command will
run the export template given in "MyPIE.MET" to create the input files and run
the Model.
You can find a sample stationery PIE in the attached directory:
Generic Project\stationery\
stationery.DLL
stationery.LAY
stationery.MET
To Create a stationery PIE with Variable Values
The
GenericProject.DLL supports adding variables to the template. This feature
enables the user to customize certain values in the export template through a
values file. To do so, create a file called "MyPIE.VAL" having lines like:
@<variable>@ = <value>
Where:
- <variable> is any string not containing
"@"
- <value> is any string not beginning with space, tab or
"="
- The "=" between the @<variable>@ and the
<value> is optional and can be omitted
Before the
PIE passes the export template to ArgusONE, it looks for a VAL file. If such a
file is found, the PIE will, for each variable, go through the export template,
locate all the expressions containing "@<variable>@" and replace them by the
string "<value>".
For example, if the export template contains the line:
If: @Number of time steps@ > 0
and the VAL file contains the line:
@Number of time steps@ = 5
then, the template passed to ArgusONE will look like:
If: 5 > 0
You can find a sample PIE in the attached directory:
Generic Project\stationery with val\
stationeryWithVal.DLL
stationeryWithVal.LAY
stationeryWithVal.MET
stationeryWithVal.VAL
Note that GenericProject.DLL will save the content of the VAL file within the
ArgusONE document when it is saved to disk. Hence you don't have to worry about
saving, loading, working with several projects concurrently, or moving a project
to another directory or computer.
To Create a Simple PIE withGUI
In contrary to fully developed PIEs which include the GUI within the
PIE (DLL, Shared Library), Generic Project PIEs use external programs
(executable) to provide a front-end to the PIE.
A PIE with a GUI (Graphical User Interface) requires an executable (EXE)
file that displays a dialog box and manages the interaction with the user.
This executable provides a graphical representation of the fields contained in
the VAL file. For each variable in the VAL file, the executable should display a
control (e.g. text box, button, list) through which the user edits the variable's
value. This VAL file will later be used by the Generic Project PIE as in the
previous example.
The EXE file can be created with any development system: Visual Basic,
Fortran, Visual C++, Java, Code Warrior, etc. When the EXE file is executed, it
receives, as an argument, the PIE's name, not including the extension ("MyPIE" in
our example). It should then read the VAL file, interpret the values given inside
and display a dialog box filled with the proper values. The user then will be
allowed to view the values and modify them according to his/her needs. When the
user dismisses the dialog box, the EXE should re-write the VAL file to reflect
the new values, and exits.
The EXE file should have the same name as the PIE, e.g. MyPIE.EXE. The Generic
Project PIE calls it on three instances:
- When a new
project is created (PIEs/New MyPIE Project...)
- When the user asks to edit the project values (PIEs/Edit Project
Info...)
- Before the export is executed (PIEs/Run MyPIE...)
Two
sample projects are provided to demonstrate how to create an EXE file in Visual Basic and in Java.
You can find a sample GUI PIE in the attached directorys:
-
Using Visual Basic GUI executable:
Generic Project\GUI (VB)\
GUI.DLL
GUI.LAY
GUI.MET
GUI.VAL
GUI.EXE
- Using Java
GUI executable:
Generic Project\GUI (Java)\
JGUI.DLL
JGUI.LAY
JGUI.MET
JGUI.VAL
JGUI.EXE
GWFlow2D.class
GWFlow2DFrame.class
IDD_GWFlow2D.class
DialogLayout.class
A Customized PIE with GUI
A PIE with a GUI might use different
dialog boxes for each of the above three instances. The PIE interacts with the
executable (or executables) through command line arguments (DOS like) when it
calls it. To achieve this, an INI file should be used. The INI file
specifies the arguments passed by the PIE to the executable in each of the three
instances. Additionally, the INI file defines the type of layers from which the
export template is allowed to be called.
The INI file looks like the VAL file, but specifies special variables:
Variable name |
Description |
@MENU@ |
The string that will appear in the "New project..." and "Run..." menu items.
That variable enables you to use a menu name that is different from the DLL file
name. For example: "@MENU@ = VS2DT" will create a menu item:
"New VS2DT Project..." regardless of the PIE's name |
@NEW COMMAND@ |
The command line to be executed when a new project is created. You can place
here a different EXE file name, or add command line arguments. For
example: "@NEW COMMAND@ = C:\MODELS\VS2DT.EXE NEW" will execute that
command line when the "New Project..." menu is selected |
@EDIT COMMAND@ |
The command line to be executed when the user requests the "Edit Project
Info..." command |
@PRE EXPORT COMMAND@ |
The command line to be executed prior to project export |
@EXPORT TRI MESH@ |
A value of "1" here will denote that "Run..." command will be executed from
Tri. Mesh layers. A value of "0" here, or omitting this line altogether will
remove the "Run..." command from the PIEs menu when the active layer is a Tri.
Mesh layer |
@EXPORT QUAD MESH@ |
Same for Quad Mesh layers |
@EXPORT GRID@ |
Same for Grid layers |
You can find a sample
Customized GUI PIE in the attached directory:
Generic Project\Customized GUI\
CustomizedGUI.DLL
CustomizedGUI.LAY
CustomizedGUI.MET
CustomizedGUI.VAL
GWFlow2D.EXE
CustomizedGUI.INI
Appendix A - How to Create Your Own GUI Using Visual Basic
To create your own EXE file, use the Visual Basic project given in
"SampleEXE-VB.zip". This code is very flexible since it loops through all the
Text Boxes it finds in the dialog box, and updates the VAL file accordingly. You
can create your own dialog box in few minutes by following the steps below:
- Open the Visual Basic project ("GWFlow2D.vbp") and open the Object
View (View/Object)
- Modify the Form to your needs - add and remove GUI objects
- Set the names of the Text Boxes to the names of the variables, as
they appear in the VAL file (View/Properties Window, then set the (Name)
field)
- Build an EXE file (File/Make GWFlow2D.EXE...)
Appendix B - How to Create Your Own GUI Using Java
To create your own EXE file, use the Visual J++ project given in
"SampleEXE-J.zip". This code is very flexible since it loops through all the Text
Boxes it finds in the dialog box, and updates the VAL file accordingly. You can
create your own dialog box in few hours by following the steps below:
- Open the Visual J++ project ("GWFlow2D JA.dsw")
- In the Workspace view, select the FileView pane and open the resource
file "GWFlow2D.rct"
- Open the "Dialog" folder
- Open the Dialog Box "IDD_GWFlow2D"
- Modify the Dialog Box to your needs - add and remove GUI objects
- Assign the Text Boxes meaningful IDs, they will serve you later:
- Double click a Text Field
- Within the Text Properties window, make sure you're in the "General"
pane
- Set the ID field to the variable name
- Save the Dialog Box (File/Save)
- Regenerate the IDD_GWFlow2D.java file:
- Run the Java Resource Wizard (Tools/Java Resource
Wizard...)
This Wizard will convert the description of the Dialog Box into a Java code
that creates the GUI elements and puts them in their proper locations -
Browse for the "GWFlow2D.rct" file
- Hit the Finish button
- You will be notified that two files were regenerated:
- IDD_GWFlow2D.java
- DialogLayout.java
- Set the default values of the Text Boxes to the names of the
variables, as they appear in the VAL file:
(The code uses the default value to match the variable names in the VAL file)
- Open the file "IDD_GWFlow2D.java"
- Look for lines of the form:
<Variable Name> = new TextField ("");
<Variable Name> being the variable name you have set as
the Text Box ID - Type the variable name as the default string, the
line now should look like:
<Variable Name> = new TextField ("<Variable
Name>"); - Repeat the above steps for each variable Text
Box
- Build the Java CLASS files (Build/Build GWFlow2D JA)
That command will build four CLASS files: - GWFlow2D.class
- GWFlow2DFrame.class
- IDD_GWFlow2D.class
- DialogLayout.class
- Make an EXE file out of GWFlow2D.class using JEXEGEN. You can use the
BAT file "ExeGen.bat" for that purpose. If you don't have JEXEGEN.EXE, you can
download it from Microsoft. It is a part of the JAVA-SDK package.
- Copy the EXE file as well as the four CLASS files to the PIE
directory.
Important Note: In
order to run Java Applets, one must have Java VM (Virtual Machine)
installed. If you intend to distribute GUI elements that uses Java Applet, Java
VM must by installed on the target machine!
To find out more about Argus and it's products email marketing@argusint.com or call (516)
931-4725
Tech. support: support@argusint.com
snail mail: 11 Merit Lane, Jericho, NY
11753
Copyright © Argus Holdings, Ltd.
1995