Home

Site Map

About

News

Purchase

Products

Download

Support

Search

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:

• Stationery PIE
• Stationery PIE with Variables
• Simple PIE with GUI
• Customized PIE with GUI

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:

1. Installs menu items under the PIEs menu, which when invoked, will create a new project and export information to the model.
2. 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.
3. 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:

1. 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.
2. Save the layer structure description:
   1. Open the Layers Dialog (View/Layers...)
   2. Hold the Shift key, and click on the "Copy" button.
      That will copy a text description of the layout to the clipboard.
   3. 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).
3. 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:

1. When a new project is created (PIEs/New MyPIE Project...)
2. When the user asks to edit the project values (PIEs/Edit Project Info...)
3. 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:

1. Open the Visual Basic project ("GWFlow2D.vbp") and open the Object View (View/Object)
2. Modify the Form to your needs - add and remove GUI objects
3. 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)
4. 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:

1. Open the Visual J++ project ("GWFlow2D JA.dsw")
2. In the Workspace view, select the FileView pane and open the resource file "GWFlow2D.rct"
3. Open the "Dialog" folder
4. Open the Dialog Box "IDD_GWFlow2D"
5. Modify the Dialog Box to your needs - add and remove GUI objects
6. Assign the Text Boxes meaningful IDs, they will serve you later:
   1. Double click a Text Field
   2. Within the Text Properties window, make sure you're in the "General" pane
   3. Set the ID field to the variable name
7. Save the Dialog Box (File/Save)
8. Regenerate the IDD_GWFlow2D.java file:
   1. 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
   2. Browse for the "GWFlow2D.rct" file
   3. Hit the Finish button
   4. You will be notified that two files were regenerated:
      • IDD_GWFlow2D.java
      • DialogLayout.java
9. 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)
   1. Open the file "IDD_GWFlow2D.java"
   2. Look for lines of the form:
      <Variable Name> = new TextField ("");
      <Variable Name> being the variable name you have set as the Text Box ID
   3. Type the variable name as the default string, the line now should look like:
      <Variable Name> = new TextField ("<Variable Name>");
   4. Repeat the above steps for each variable Text Box
10. 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
11. 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.
12. 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!