SWMM5 Delphi GUI Ugraph.pas Summary

 Extended Summary of the Ugraph.pas Unit

This unit, Ugraph.pas, provides general-purpose charting routines for use within EPA SWMM’s Delphi application. It supports creating, configuring, copying, and printing TChart objects and their data series, utilizing the TeeChart library components (TChart, TSeries, etc.). Below is a detailed overview of how each part of this unit fits together.

---

1. Overall Purpose

Ugraph.pas encapsulates:

1. Procedures that help configure and initialize various chart properties (axes, legend, colors, etc.) using the global GraphOptions from Uglobals.pas.
2. Functions that create new data series (e.g. area, line, bar, point) within a TChart.
3. Routines to copy chart images/data to the clipboard or a file (bitmap, metafile, textual data).
4. Procedures to print the chart to either a physical printer or a preview form.

---

2. Key Exposed Procedures and Functions

1. CopyTo(Chart: TChart)

   • Opens a dialog (TCopyToForm) allowing the user to copy a chart to either a file or the Clipboard in one of three formats:
     • Bitmap (raster)
     • Enhanced Metafile (vector)
     • Text (raw numeric data)
   • Internally calls helper routines (CopyToBitmap, CopyToMetafile, or CopyToString) depending on the user’s choice.

2. Data Series Creation
   A set of functions that create specific TeeChart series within a given TChart:

   • CreateBarSeries(Chart, Title): creates and configures a TBarSeries.
   • CreateAreaSeries(Chart, Title): creates a TAreaSeries (used for rainfall, typically in a “staired” mode).
   • CreateFastLineSeries(Chart, Title): creates a TFastLineSeries, which is faster for large data sets.
   • CreateLineSeries(Chart, Title): creates a standard TLineSeries.
   • CreatePointSeries(Chart, Title): creates a TPointSeries that draws discrete points.

   Each of these sets up the series with basic properties (e.g. color, visible in legend, pointer style, etc.) and references GraphOptions to stay consistent with the user’s global preferences.

3. InitGraphOptions(Chart: TChart)

   • Applies the global GraphOptions to the chart. This includes whether it’s 3D, background color, legend style, axis styles, fonts, and so on.
   • Also calls an internal helper InitAxisOptions for each axis (bottom, left, right) to set up grid style, font properties, etc.

4. Print(Chart, thePrinter, Destination)

   • Renders the chart to a TPrintControl object, which can go to the system printer or to a preview form.
   • Creates an internal Metafile of the chart, fits it to the page, and sends it through thePrinter.

5. SetGraphOptions(theChart, var startPage, theForm)

   • Opens a Chart Options dialog (from Dchart.pas) where the user can adjust line styles, point styles, axis settings, etc.
   • On success, merges the user’s changes back into GraphOptions and optionally saves them as new defaults if the user requests it.

---

3. Internal Helper Procedures

1. CopyToBitmap(Fname, Chart) and CopyToMetafile(Fname, Chart)
   • If Fname is non-empty, the chart is saved to a file. Otherwise, it’s copied to the Windows Clipboard in the respective format.
2. CopyToString(Fname, Chart)
   • Extracts X-Y data from the chart’s series into a tab- or space-delimited text.
   • If Fname is empty, it places the text on the Clipboard; otherwise, it writes to disk.
   • Handles single series vs. multiple time series, calibration data sets, etc.
3. InitLineSeriesOptions, InitAreaSeriesOptions, InitFastLineSeriesOptions
   • Apply color, pen styles, pointer visibility, etc., to each series, referencing arrays from GraphOptions.
4. SaveDefaultOptions(Chart, UseDefaultPanelColor)
   • Called if the user wants to make the updated chart settings the new “application defaults.”
   • Updates the global GraphOptions so future new charts adopt those styles automatically.

---

4. Data Structures

4.1 Data Series Classes

• TBarSeries: draws columns for data. Typically for histograms.
• TAreaSeries: area under a line, used in SWMM for e.g. rainfall bars.
• TFastLineSeries: optimized line series for large data.
• TLineSeries: standard line graph.
• TPointSeries: for discrete scatter plots or calibration data sets.

4.2 Global GraphOptions (from Uglobals)

• The InitGraphOptions, InitLineSeriesOptions, etc. all read from the global GraphOptions. The user can update GraphOptions via a chart options dialog, or revert to previously saved defaults.

---

5. Summary of Use

1. Creation: Another unit can call CreateLineSeries(...) or CreateBarSeries(...) to add a data series to a TChart.
2. Initialization: Once the series are created, InitGraphOptions(Chart) configures the chart’s background, legend, axes, etc.
3. User Adjustments: The user can open a Chart Options dialog by calling SetGraphOptions(...), and the new settings are loaded into GraphOptions.
4. Output: The chart can be:
   • Copied to a file or clipboard (CopyTo(Chart)).
   • Printed or previewed (Print(Chart, thePrinter, Destination)).

Hence, Ugraph.pas is a utility for standard charting operations, bridging user preferences (GraphOptions) and the various TeeChart components used throughout SWMM’s GUI.