SWMM5 Delphi GUI Dgwater .pas Summary

 Detailed Expanded Summary of the Dgwater Unit (SWMM5)

The Dgwater unit (Object Pascal) provides a specialized dialog form (named TGroundWaterForm) that allows the user to view and edit the groundwater flow properties of a subcatchment in the EPA SWMM5 software. These properties describe how water flows between a subcatchment’s aquifer, soil zones, and the node that receives the outflow. Below is a comprehensive analysis of the unit’s functionality, structure, and role within the broader application.

---

1. Purpose & Scope

In SWMM5, each subcatchment can optionally have a groundwater component describing aquifer properties beneath it, plus equations describing lateral and deep percolation flows. The TGroundWaterForm dialog centralizes editing of these parameters, which include:

1. Aquifer name (links to a named Aquifer object)
2. Receiving node for groundwater flow
3. Surface elevation plus several flow coefficients, exponents, and threshold parameters
4. Optional custom equations for lateral and/or deep groundwater flow, allowing advanced control beyond the standard GW flow formula

Hence, Dgwater.pas is the code behind a SWMM5 window that displays and updates these fields.

---

2. Key Components

2.1. Form Class: TGroundWaterForm

• Inheritance: Descends from TForm, a Delphi/Lazarus standard for visual windows.
• Fields:
  • SubCatchIndex: The subcatchment index in SWMM’s data structure (pointing to the current subcatchment whose groundwater data is displayed).
  • GwaterProps: An array of property descriptors (TPropRecord) for each editable field, such as “Aquifer Name,” “Surface Elevation,” “Receiving Node,” etc.
  • PropEdit1: A TPropEdit control that implements a property-value style grid for editing. Each row corresponds to a property, while columns represent the property’s name and its value.
  • PropList: A string list containing the actual data values displayed in PropEdit1.
  • LatFlowEqn & DeepFlowEqn: Strings representing optional custom equations for lateral flow and deep flow, respectively, used in addition to or in place of the built-in SWMM groundwater formula.

2.2. Constants & Data Structures

1. MAX_GW_PROPS = 14: Number of groundwater properties including two for custom equations (LAT_EQN_INDEX = 13, DEEP_EQN_INDEX = 14).
2. Default_GW_Props: An array that provides default text for each property if no data exist (such as no aquifer name, or zero for flow coefficients).
3. PropNames & GroundWaterHint: Arrays of user-facing strings that define the names of each property and hints/tips displayed at the bottom of the form (the HintLabel) as the user navigates each row in PropEdit1.

2.3. Form Lifecycle Methods

1. FormCreate(Sender: TObject)

   • Instantiates and configures the PropEdit1 property grid (TPropEdit).
   • Sets up GwaterProps (one TPropRecord for each field).
   • Creates PropList, the string list that stores property values to display.
   • Initializes LatFlowEqn and DeepFlowEqn as empty strings.

2. FormShow(Sender: TObject)

   • Loads the property records (GwaterProps) plus values from PropList into PropEdit1.
   • Tells PropEdit1 to place the user in edit mode (Edit;).

3. FormDestroy(Sender: TObject)

   • Cleans up the PropList and PropEdit1 objects.

4. FormKeyDown(Sender: TObject; ...)

   • Detects F1 key press to trigger help.

---

3. User Interaction

3.1. Property Grid (PropEdit1)

Each row of the grid corresponds to a specific groundwater property. The user can:

• Enter text (for numeric or string fields).
• Click a button for the custom equations for lateral or deep flow, leading to a specialized child form (TGWEqnForm from Dgweqn.pas).

3.2. Buttons

• OK / Cancel: Finalize or dismiss changes.
• Help: Show specialized help.

3.3. Event Handlers

1. ButtonClick(Sender: TObject; Index: Integer; var S: String; var Modified: Boolean)
   Triggered when the user clicks the “...” button on a row in PropEdit1. Specifically for LAT_EQN_INDEX or DEEP_EQN_INDEX, it calls up TGWEqnForm to let the user input a custom equation. The resulting string is stored in LatFlowEqn or DeepFlowEqn, and S is set to “Yes” or “No” to reflect whether an equation is present.
2. ShowPropertyHint(Sender: TObject; aRow: LongInt)
   Updates the lower HintLabel with a short piece of help text from GroundWaterHint.
3. ValidateEntry(Sender: TObject; Index: Integer; var S: String; var Errmsg: String; var IsValid: Boolean)
   Currently only checks if the field can remain blank or not.
4. OKBtnClick(Sender: TObject)
   Ensures PropEdit1 fields pass validation. If not, remain in the form. Otherwise close with mrOK.

---

4. Data Transfer Methods

4.1. SetData(const Index: Integer)

Given a subcatchment index:

• Loads defaults (Default_GW_Props) into PropList.
• If the subcatchment is valid, it fetches the subcatchment’s Groundwater string list, copying each line into the first 13 items.
• The custom equations (GwLatFlowEqn & GwDeepFlowEqn) are loaded into local strings (LatFlowEqn & DeepFlowEqn). If these are non-empty, the corresponding property’s string in PropList is “Yes” else “No”.

4.2. GetData(const Index: Integer)

Copies the final set of property values back to the subcatchment:

1. Clears the subcatchment’s Groundwater list.
2. If the aquifer name property (index 0) is not blank, it copies the first 13 lines from the local PropList into Groundwater.
3. The LatFlowEqn & DeepFlowEqn are assigned to S.GwLatFlowEqn & S.GwDeepFlowEqn.
4. The global HasChanged is set if PropEdit1.Modified is true.

4.3. Group Data Methods

1. SetGroupData
   Switches the form caption to “Group Groundwater Editor” and changes the last property style to read-only. Also sets the local PropList to '*' for each property, meaning “Not editing or default.”
2. GetGroupData(var GWData: array of String)
   Copies the form’s property data (except for custom equations) into the passed array. Used to apply these as group edits to multiple subcatchments in a different code flow.

---

5. Coupling with Other Units

• Dgweqn: The specialized child form for custom flow equations. The ButtonClick method calls into Dgweqn.pas’s TGWEqnForm to handle user editing of advanced math expressions for LatFlowEqn or DeepFlowEqn.
• Uproject, Uglobals, Uutils: Provide references to the subcatchment data, global settings, and utility routines for error messages, numeric parsing, and string handling.

---

6. Workflow Example

1. User Opens Subcatchment’s Groundwater Editor: The main SWMM UI calls GroundWaterForm.SetData(i), passing subcatchment index i.
2. Properties Shown: The form populates the grid with the subcatchment’s existing data (like aquifer name, flow coefficients, etc.).
3. User Edits: If the user clicks on the lateral or deep equation row’s “...” button, a separate TGWEqnForm opens. The user can add or remove custom code there. The form’s property will become “Yes” or “No.”
4. Confirm: On OK, GetData(i) copies the user’s changes to the subcatchment data structure (S.GwLatFlowEqn etc.), sets HasChanged, and closes.

---

7. Maintenance & Extensibility

• Validation: Currently minimal. Additional checks on numeric ranges or synergy with aquifer references could be added.
• Custom Equation: The usage of “Yes/No” in PropEdit1 for the custom equation might be expanded to display a short preview if desired.
• Group Editing: SetGroupData/GetGroupData supports applying an edit to multiple subcatchments at once, used by a “Group Edit” function from other SWMM UI code.

---

Conclusion

Dgwater.pas is a compact, well-structured module enabling an advanced groundwater property UI. It leverages the standard approach in SWMM5’s UI: a property grid for data fields, dynamic memo-based help, and child forms for specialized tasks (like writing custom equations). It keeps all SWMM data in alignment with user changes for a single or multiple subcatchment(s).