SWMM5 Delphi GUI Dprevplot.pas Summary

 Below is an overview of Dprevplot.pas, a Delphi unit from SWMM 5.2 that provides a dialog form (TPreviewPlotForm) for displaying a quick preview plot of data contained in other editors—namely the Curve editor, Time Series editor, or Transect editor. The form also supports showing cross-sectional geometry for storage units or custom shapes.

---

1. Purpose and Context

When the user clicks the View button in various SWMM dialogs (e.g., the Transect, Curve, or Time Series editors), SWMM needs a quick way to visualize the data (stations and elevations for transects, X-Y pairs for curves, time-value pairs for time series, etc.). TPreviewPlotForm serves this purpose:

1. It holds a TChart (named Chart1) with 4 data series:
   • Series1: A line series (top line of an entire transect).
   • Series2: A line series (top line of just the main channel portion).
   • Series3: A line series (plots generic X-Y data for curves/time series).
   • Series4: An area series (used to “fill in” the bottom of a transect cross-section).
2. The form can display these Series differently depending on whether it’s showing a transect cross-section, a standard X-Y curve, a time series, or a special cross-section shape.

---

2. Main Form: TPreviewPlotForm

2.1 Components

• Chart1: A TChart that hosts line/area series.
• Series1, Series2, Series3, Series4:
  • Series1 / Series2: line series used for transect top lines.
  • Series3: line series for curves, time series, or single-series X-Y plots.
  • Series4: area series for filled-in portion of a transect.
• Buttons:
  • CopyBtn: Copy the chart image to clipboard.
  • PrintBtn: Print the chart.
  • CloseBtn: Closes the preview form.
• Panel arrangement: Panel1 holds the chart, BtnPanel holds the buttons.

2.2 Key Routines

1. PlotCurveData(DataGrid, Title, UseStairs, SwitchXY)

   • Reads X-Y pairs from DataGrid and places them into Series3.
   • If UseStairs = True, uses a step-plot style.
   • If SwitchXY = True, the grid’s X & Y columns are swapped.
   • Adds a chart title and axis labels from the grid’s header row.

2. PlotTimeSeries(DataGrid, Title, D0)

   • Interprets columns (0: date, 1: time, 2: value) from DataGrid.
   • Converts date+time to “elapsed hours” from a reference date/time D0.
   • Adds those points to Series3 and sets Chart1.BottomAxis.Title.Caption to “Elapsed Time (hours).”

3. PlotTransectData(DataGrid, Xleft, Xright, Xfactor, Yfactor, Title, Units)

   • Used for cross-section data.
   • DataGrid rows contain station (column 1) and elevation (column 2).
   • Series4 draws an area of the entire transect (filling from lowest station to highest).
   • Series1 draws the top line across the entire width.
   • If Xleft / Xright exist, Series2 highlights the portion of the transect that is the “main channel.”
   • Xfactor, Yfactor can rescale the station or elevation values.

4. PlotStorageXsect(DataGrid, Title)

   • Interprets column 1 as depth, column 2 as cross-sectional area.
   • Draws a symmetrical shape about the center line, as if it’s a storage tank cross-section (radius derived from $\sqrt{A/\pi}$).
   • Creates left half (negative X) and right half (positive X) about the Y-axis.

5. PlotShapeXsect(DataGrid, Title)

   • Interprets column 1 as depth, column 2 as width ratio.
   • Plots a custom cross-section shape symmetrically about the Y-axis (like half the shape to the left, half to the right).
   • Potentially ensures a 1:1 aspect ratio by adjusting the axis scale.

6. CopyBtnClick: calls Ugraph.CopyTo(Chart1), copying the chart image to the clipboard.

7. PrintBtnClick: calls Ugraph.Print(Chart1, MainForm.thePrinter, Xprinter.dPrinter) to open a print dialog.

2.3 Additional Utility Methods

• SetBottomAxisScale: If the maximum X in a plot is less than 10, tries to auto-scale the axis with finer increments.
• StripReturns(S): Removes carriage returns (#13) from a string (used for axis titles that might contain line breaks).

---

3. Typical Usage

• When the user opens a “Transect Editor” or “Curve Editor,” they might see a View button. Clicking it collects data from a TStringGrid and calls one of the Plot...() methods in TPreviewPlotForm (e.g. PlotTransectData or PlotCurveData).
• The form then appears with the chart automatically scaled, a relevant caption, X/Y axis labels, and possibly a filled area or multiple lines.
• The user can Copy the chart image, Print it, or Close the form.

---

4. Summary

Dprevplot.pas enables SWMM’s “preview plot” functionality for various editors, giving a simple, uniform way to visualize table-based data (transect cross-sections, curves, time series, etc.). With minimal user input, it sets up and displays a TChart with up to four different series (line or area) for a clear, on-demand preview:

1. Series1 / Series2: lines for transect outlines (full cross-section vs. main channel).
2. Series3: a generic line series for curves or time series.
3. Series4: an area fill for the bottom or banks of a transect.

The user can then copy or print the displayed chart before closing the preview.