SWMM5 Delphi GUI Dtseries.pas Summary

 Below is an overview of Dtseries.pas, a Delphi unit from SWMM 5.2 that implements a form (TTimeseriesForm) for defining and editing time series objects within SWMM. A time series in SWMM is a series of (date/time, value) pairs, often used for external inflows, rainfall data, or other model input signals that vary over time.

---

1. Purpose and Context

In SWMM, a time series can be referenced by nodes, subcatchments, or other elements to provide varying input data (e.g. inflow over time, tidal data, control rules, etc.). The TTimeseriesForm dialog allows the user to:

1. Specify a unique name for the time series.
2. Include an optional comment describing its purpose.
3. Supply the data in two ways:
   • Directly through a table of date/time/value entries,
   • Externally via a file path to a file containing these data.
4. Optionally preview the time series data on a quick plot to ensure correct ordering and formatting.

Once the user finalizes changes, the time series data are stored in a TTimeseries object in SWMM’s project data structure, enabling it to be used wherever time-varying data are needed in the model.

---

2. Main Form: TTimeseriesForm

2.1 Key Controls

1. SeriesName (TEdit):

   • Holds the time series’ name (unique ID in SWMM).

2. Comment (TEdit):

   • A short, optional description of the series.

3. GridEdit (TGridEditFrame):

   • Allows direct entry of rows of date, time, value in the StringGrid.
   • Up to 1000 rows (though the Grid is sized for a maximum of 1000).
   • Each row has three columns: date, time, numeric value.

4. UseFileCheckBox / UseTableCheckBox:

   • Indicate if the user is specifying the time series from:
     • An external file (UseFileCheckBox = True),
     • The table in the grid (UseTableCheckBox = True).

5. FileNameEdit / FindFileBtn:

   • The file path to an external data file containing the time series, and a browse button to open a file dialog.

6. BtnView:

   • Launches a quick preview plot of the table-based data in a TPreviewPlotForm.

7. Buttons:

   • OK: Validates and finalizes data.
   • Cancel: Discards changes.
   • Help: Opens context help about time series.
   • Edit: Opens a comment editor for the time series description.

---

3. Data Flow

3.1 SetData(Index, S, aSeries)

• Called to load existing data for a time series:
  1. SeriesIndex := Index (the position in SWMM’s TIMESERIES list).
  2. SeriesName.Text := S (the time series’ name).
  3. Comment.Text := aSeries.Comment.
  4. If aSeries.Filename is non-empty, the user is using an external file.
     • FileNameEdit.Text := aSeries.Filename.
     • UseFileCheckBox.Checked := True.
     • Disables the grid entry (GridEdit.Enabled := False).
  5. Otherwise, it populates GridEdit.Grid from the Dates, Times, and Values lists in aSeries.

3.2 GetData(S, aSeries)

• Called when the user presses OK to finalize changes:
  1. S := SeriesName.Text to hold the final time series name.
  2. aSeries.Comment := Comment.Text.
  3. If using an external file, store aSeries.Filename. Clear its table-based data lists.
  4. If using a table:
     • Clear aSeries.Filename.
     • Copy each row from GridEdit.Grid into aSeries.Dates, Times, and Values.

3.3 BtnOKClick / ValidateData

• Checks that:
  1. Time series name is not empty and not a duplicate among Project.Lists[TIMESERIES].
  2. If using a file, that file actually exists.
  3. The user’s date/time entries in the grid are in ascending chronological order (the TimeOrdered check).
  4. The numeric values are valid numbers.

If any check fails, the form does not close and displays an error.

3.4 BtnViewClick (Preview Plot)

• If the user is using the table-based approach (not an external file), it creates a TPreviewPlotForm, calls PlotTimeSeries(GridEdit.Grid, “Time Series <Name>”, D0), where D0 is the project’s start date.
• The plot uses the table's date/time to create an X-axis, and the numeric values as Y-axis points.

3.5 UseFileCheckBoxClick / UseTableCheckBoxClick

• Toggles between external file usage and direct table usage.
• Disables or enables the relevant controls accordingly.

---

4. Additional Features

• Edit button calls a generic comment editor to allow multi-line editing of the time series’ Comment.
• Name field disallows special characters like ' ', '"', ';', '[' (for the first character).
• The GridEdit control supports row insertion and numeric input style.

---

5. Summary

Dtseries.pas provides a user-friendly UI for managing SWMM’s time series objects. Whether referencing a plain text file or manually entering date/time/value rows in a grid, the form ensures:

1. A valid, unique time series name.
2. Optionally a comment.
3. Validated date/time entries in ascending order.
4. Quick plot preview to confirm correct data ordering.

This data is stored in a TTimeseries object, used throughout SWMM (e.g., for inflows, rainfall, controls, etc.).