SWMM5 Delphi GUI Dtimeplot.pas Summary

 Below is an overview of Dtimeplot.pas, a Delphi unit from SWMM 5.2 that provides the TTimePlotForm dialog for setting up time series plots of simulation results. Users can specify multiple data series, each representing a particular object-variable combination (e.g., flow in a link, water depth at a node, runoff from a subcatchment, etc.), along with additional options like date range and axis settings. When the user is done, SWMM will generate the requested time series plot using the specified configurations.

---

1. Purpose and Context

In SWMM, a time series plot displays how a certain parameter (flow, depth, pollutant concentration, rainfall, etc.) evolves over time. The TTimePlotForm allows users to select:

• Which objects (subcatchments, nodes, links, or the entire system).
• Which variables (e.g., water depth, flow, pollutant).
• **Whether to use elapsed or actual date/time on the X-axis.
• The time window (start and end date/time).
• Number of data series (up to six) in one combined plot, each assigned to either the left or right Y-axis.

When the user hits OK, the form sets up a TReportSelection structure that describes the items to plot, then calls MainForm.CreateReport(ReportSelection) to produce the time series plot.

---

2. Main Form: TTimePlotForm

2.1 Pages and Controls

1. PageControl1 with two TabSheet pages:

   • TabSheet1 ("Data Series Selection"): Lists the data series to be plotted. The user can add or delete series, or move them up or down (changing the order in the plot's legend).
   • TabSheet2 ("Edit Data Series"): A page to specify which object is being plotted, which variable, and other details like axis assignment and legend label.

2. Buttons:

   • Add (BtnAdd): Creates a new data series and switches to TabSheet2 to define it.
   • Edit (BtnEdit): Edits the currently selected series in TabSheet2.
   • Delete: Removes the currently selected series.
   • MoveUp / MoveDown: Reorders the data series in the list.
   • Accept: On TabSheet2, updates the series with the user’s input.
   • OK: Closes the form, finalizing the ReportSelection.
   • Cancel: Closes the form without changes.
   • Help: Brings up context help.

3. SeriesListBox:

   • Lists each data series in textual form, typically: "[object type] [object ID] [variable name]".

4. Object Type (ObjTypeCombo), Object Name (ObjNameEdit), Variable (VariableCombo):

   • The user chooses subcatchment/node/link/system and a variable.
   • If “System” is chosen, no object name is needed.
   • ObjNameEdit can be filled automatically from the currently selected object in SWMM’s data browser, via SetObject() or AddSelectedObject().

5. Time range:

   • StartDateCombo1 / EndDateCombo1: The user picks which date/time indices from the simulation to start and stop the plot.
   • ElapsedTimeBtn or DateTimeBtn: Chooses whether to label the X-axis in elapsed hours or actual date/time.

6. LeftAxisBtn / RightAxisBtn:

   • Decides if the series is assigned to the left or right Y-axis.

7. LegendLabelEdit:

   • The user’s custom label for the data series in the plot’s legend (optional).

---

3. Data Structures

3.1 TReportSelection

• A SWMM structure that describes how to build a plot or table. For time-series plots:
  1. ReportType := TIMESERIESPLOT.
  2. StartDateIndex, EndDateIndex: the user’s chosen date/time period.
  3. DateTimeDisplay: if True uses date/time on X-axis, otherwise uses elapsed time.
  4. Items: a list of data series descriptions (strings).
  5. ItemCount: how many data series.
  6. VariableCount: same as ItemCount for time series.
  7. Each data series is in ReportItems[], containing object type, object name, variable index, axis assignment, and an optional legend label.

3.2 The Relationship to SWMM’s Data

• ObjTypeCombo.ItemIndex corresponds to SUBCATCHMENTS=0, NODES=1, LINKS=2, SYS=3.
• For subcatchments, node or link variables, the Variable is adjusted by offset indices (SUBCATCHOUTVAR1, NODEOUTVAR1, LINKOUTVAR1, or SYSOUTVAR1) in the final step (OkBtnClick).
• The user picks the date/time combos from MainForm.DateListBox.

---

4. Workflow

1. Setup: Called to initialize the time range combos (StartDateCombo1, EndDateCombo1) and to set the check for elapsed vs. date/time axis.
2. Add: Switches from TabSheet1 to TabSheet2, clearing the details for a new data series, optionally pulling in the user’s currently selected SWMM object from the data browser (AddSelectedObject).
3. Edit: The user picks an existing series in SeriesListBox, the form loads its details into TabSheet2 for editing.
4. Accept: The user finalizes the new or edited series data (object type, name, variable, axis, legend text). This updates SeriesListBox with a textual description, and updates an internal ReportSelection.ReportItems[SeriesIndex].
5. OK: The user finalizes the entire plot. The form sets ReportType = TIMESERIESPLOT, date/time indices, DateTimeDisplay, ItemCount, and calls MainForm.CreateReport(ReportSelection).

---

5. Validation

• If the user picks a non-system object type but the specified object name doesn’t exist in the project, an error message is shown (“There is no such object in your project.”).
• The user can only have up to 6 data series.
• The date/time combos must have StartDateIndex <= EndDateIndex.

---

6. Summary

Dtimeplot.pas provides TTimePlotForm, a specialized interface for building multi-series time series plots in SWMM. It allows the user to specify multiple object-variable pairs, their date/time coverage, and how they appear in the final plot (axis assignment, legend label, etc.). This ensures a flexible, user-friendly approach to visualizing simulation results over time.