SWMM5 Delphi GUI Uutils.pas Summary

 Below is a high-level summary of the Uutils.pas unit, which provides general-purpose helper routines used throughout EPA SWMM. These functions cover a broad range of features, from string and file manipulation to graphics routines and mathematical helpers.

---

1. Purpose & Overview

The Uutils.pas unit acts as a utility library, giving other SWMM modules access to reusable functions for:

• String parsing and tokenizing
• Numerical conversions (e.g., string to float)
• File operations (e.g., retrieving file sizes, temporary filenames)
• Graphics and drawing (e.g., adjusting bitmaps, text rotation)
• Measurement system queries (e.g., checking Windows locale, decimal separator)
• Basic geometry (e.g., checking if a point is on a line)
• Miscellaneous housekeeping operations

---

2. Key Procedures and Functions

Below is a sampling of the major routines, grouped by purpose:

2.1. String & Number Utilities

1. GetSingle / GetExtended

   • Converts a string into a floating-point (Single/Extended) with built-in error checks.

2. IsValidNumber

   • Verifies if a user-supplied string is a valid numerical value; displays an error message if not.

3. ConvertDate

   • Converts date strings with different separators into a standard mm/dd/yyyy format (or tries to).

4. CompareStrVals

   • Compares two string values that might represent numbers. If both parse as numbers, it compares numerically; otherwise, it does a lexicographical comparison.

5. Tokenize

   • Splits a string into tokens, respecting quoted sections and ignoring text after semicolons (';'). Often used for parsing SWMM input lines.

---

2.2. File & Folder Operations

1. GetFileSize

   • Returns the size of a given file without needing to open it.

2. WinExecAndWait

   • Launches an external program (via a command line) and optionally waits for it to finish.

3. GetTempFile, GetTempFolder

   • Creates or returns temporary filenames / temporary directory paths.

4. GetAppDataDir

   • Provides a default application-specific directory in the user’s “AppData” folder, creating it if needed.

5. HasAttr, IsReadOnly

   • Checks file/directory attributes (e.g., read-only).

---

2.3. Graphics & Drawing

1. AdjustBitmap

   • Modifies each pixel of a bitmap to achieve a “watermark” (brightened) or grayscale effect.

2. Cls

   • Clears (fills) a rectangle on a canvas with a given color.

3. DrawTextCentered

   • Draws text centered within a specified rectangle on a canvas.

4. TextOutRotate

   • Draws rotated text at a specified angle on a canvas.

---

2.4. Math & Geometry

1. AutoScale

   • Auto-scales a numerical range [Zmin, Zmax] into “nice” intervals.

2. CompareSingles

   • Compare function for sorting single-precision floats.

3. LatLongToMeters

   • Converts lat/long coordinates into approximate meters (assuming a spherical Earth).

4. PtOnLine

   • Checks whether a point is on a line segment (within a given tolerance).

5. RoundToScale

   • Rounds a value to a “nice” scale factor.

---

2.5. Miscellaneous

1. GetTimeString

   • Converts a time in seconds into an “Hrs:Mins:Secs” string.

2. SortStringGrid

   • Sorts the rows of a Delphi TStringGrid control by a specific column, either numerically or lexicographically, in ascending or descending order.

3. GetDecimalChar

   • Retrieves the current system decimal separator from the OS locale settings.

4. MsgDlg

   • Overloaded functions that produce a message dialog (akin to MessageDlg) centered on the active form.

---

3. Typical Use Cases

• Parsing Input Lines:
  Tokenize is frequently used in SWMM’s input reading logic to separate tokens from a line (including quoted strings).

• Formatting & Checking Values:
  GetSingle and IsValidNumber ensure that user-entered or file-read strings are indeed valid floats.

• Displaying Overlays / Watermarks:
  AdjustBitmap can lighten or grayscale map layers behind the main map display.

• Sorting Grids:
  SortStringGrid is used when displaying tabular data in the UI, letting users reorder rows by column.

• Launching External Tools:
  WinExecAndWait is used to call external executables from within SWMM (e.g., user-registered “Tools”).

---

4. Integration and Dependencies

• Uutils.pas is mostly independent of other SWMM units but uses standard Delphi units like SysUtils, Windows, and Graphics.
• The code is used throughout the SWMM source where standard operations are needed (file checks, number conversions, geometry checks, etc.).
• Some of these routines (e.g., AutoScale, LatLongToMeters) reflect EPA SWMM’s inherent focus on hydraulic/hydrologic computations.

---

5. Conclusion

Uutils.pas is a generic utility library that keeps SWMM code lean by centralizing many common tasks:

• Reading & writing strings/numbers
• Performing geometry or math operations
• Manipulating UI elements (bitmaps, string grids)
• Managing file properties and external processes

This design helps maintain clear and reusable code across the entire SWMM application.