SWMM5 Delphi GUI Utools.pas Summary

 Below is a high-level summary of the Utools.pas unit, which manages user-registered external tools from SWMM’s Tools menu.

---

1. Purpose & Overview

Utools.pas provides the functionality to register, store, and launch external executables (tools) integrated into SWMM’s Tools menu. By “tools,” we mean any external program or script that might interact with the current SWMM project or its temporary input and output files. The user can specify command-line arguments (macros) that reference various SWMM file locations, allowing seamless handoff of project or results data to an external program.

Core Responsibilities:

• Maintain a list (ToolList) of external tools.
• Load/save each tool’s settings (exe path, working directory, parameters, etc.) from/to a dedicated INI file (swmm5tools.ini).
• Populate the Tools menu in the SWMM GUI with each registered tool as a menu item.
• Run a selected tool, possibly updating SWMM’s input/output if so configured.

---

2. Key Data Structures

1. TTool Class

   • Records all settings for a single external tool:
     • ExeName: The path/name of the tool’s executable.
     • DirName: The working directory (often a macro).
     • Params: Command-line parameters (can also contain macros).
     • DisableSWMM: If true, the main SWMM UI is hidden while the tool runs.
     • UpdateSWMM: If true, SWMM’s project or results are refreshed afterward.
     • MnuItem: A pointer to the Delphi TMenuItem that appears under Tools.

2. ToolList (TStrings)

   • Holds all TTool objects and their corresponding display names.
   • Provides indexing and naming references.

3. Macros

   • A set of string tokens (like $PROJDIR, $INPFILE, etc.) replaced at runtime with actual file or directory paths.
   • The recognized macros are:

     $PROJDIR    (project directory)
     $SWMMDIR    (SWMM’s program directory)
     $INPFILE    (current project’s temporary input file)
     $RPTFILE    (temporary text-based status report file)
     $OUTFILE    (temporary output file)
     $RIFFILE    (runoff interface file)
     

   • Tools can use these macros in their command-line Params.

---

3. Primary Procedures and Functions

Below is the typical lifecycle of the Tools collection:

1. Initialization / Finalization

   • OpenToolList: Called during SWMM startup to create ToolList and populate it from swmm5tools.ini.
   • CloseToolList: Called at shutdown to save the final tool list back to swmm5tools.ini and free resources.

2. INI File Reading & Writing

   • ReadToolsIniFile: Opens swmm5tools.ini, reads each “section” as one tool.
   • WriteToolsIniFile: Writes each tool’s properties back to the INI file.

3. Tool CRUD Operations

   • UpdateTool(I, S1, S2, S3, S4, Flag1, Flag2)
     • If I is -1, a new TTool is created and appended. Otherwise, the existing tool at index I is updated.
     • S1 is the Tool’s menu text, S2 the exe path, S3 the directory, S4 the command-line parameters, and Flag1, Flag2 are the two Booleans.
   • DeleteTool(I): Removes the tool at index I from both the ToolList and the Tools menu.
   • ExchangeTools(I1, I2): Swaps the order of two tools in ToolList, ensuring the Tools menu re-orders accordingly.

4. Utility Functions

   • GetTmpInpFileName: Creates and exports the current SWMM project to a new temporary .inp file if $INPFILE is used.
   • RunTool(S: String):
     1. Locates the named tool in ToolList.
     2. Prepares the working directory (DirName) by substituting macros.
     3. Prepares command-line parameters by substituting macros in Params.
     4. Optionally hides SWMM, then executes the external program.
     5. If UpdateSWMM is true, checks whether the external tool changed the .inp or .out files, and updates SWMM’s data or results accordingly.

---

4. Macro Substitution Mechanism

When RunTool is invoked, it constructs the final command-line and directory via:

• GetDir
  • Replaces $PROJDIR with Uglobals.ProjectDir, $SWMMDIR with the SWMM program’s directory.
• GetParams
  • Replaces $INPFILE with a newly generated temporary SWMM input file.
  • Replaces $RPTFILE, $OUTFILE, $RIFFILE similarly.

This ensures an external tool can seamlessly reference the current project’s data.

---

5. Integration Flow

1. Startup: OpenToolList loads all tools from swmm5tools.ini, creating a Tools menu item for each.
2. Edit Tools: The user can open a UI to add, remove, or reorder tools.
3. Invoke Tool: The user clicks a Tools menu item:
   1. RunTool(...) is called.
   2. Temporary input/outputs are created if macros are used.
   3. The external exe is launched with the constructed command-line.
   4. If DisableSWMM is set, the main form is hidden.
   5. If UpdateSWMM is set, the .inp or .out files are re-read so that changes show up in SWMM’s UI.
4. Shutdown: CloseToolList saves current tools to swmm5tools.ini.

---

6. Example Usage Scenario

1. The user wants a post-processor like “PlotterX” accessible from SWMM:
   • They add a new Tool named “PlotterX,” specify ExeName as C:\Tools\PlotterX.exe, DirName as $PROJDIR, and Params as -i $INPFILE -o results.png.
   • They set DisableSWMM = false and UpdateSWMM = false.
2. At run-time, SWMM writes the current project to a temp .inp file. Then PlotterX is called with the appropriate path arguments.
3. The user’s external program can produce a figure from that .inp data.
4. Because UpdateSWMM = false, SWMM does not automatically re-import results.

---

7. Conclusion

Utools.pas is a convenience unit enabling SWMM to store and launch external applications from the Tools menu. By supporting macros and optional SWMM synchronization, it offers a robust mechanism for custom post-processing, run automation, or model transformations. This integration extends SWMM’s functionality without requiring changes to its internal code.