SWMM5 Delphi GUI Ulegend.pas Summary

 Extended and Expanded Summary of the Ulegend.pas Unit

The Ulegend.pas unit in EPA SWMM manages the creation, display, and editing of color legends for various variables shown on the study area map. It also includes functionality to draw a legend for elapsed or actual simulation time (the “time legend”). Below is a thorough overview of the unit’s functionality, data parameters, and key routines.

---

1. Purpose and Scope

The Ulegend.pas unit is responsible for:

1. Drawing the legend that shows how colors map to ranges (intervals) of subcatchment, node, or link variables (e.g., pollutant concentration, water depth, velocity, etc.).
2. Displaying and editing legend intervals and colors through a user interface (the Legend Editor dialog).
3. Drawing a separate time legend on the map that displays the current simulation time period being viewed.

---

2. Key Data Types and Fields

2.1 TMapLegend Record

A TMapLegend is defined globally in Uglobals.pas and referenced here. It holds:

• Intervals: an array of floating-point breakpoints for the color intervals.
• Nintervals: the number of these intervals actually used (1 to MAXINTERVALS).
• Ltype: the object type for this legend (e.g., SUBCATCHMENTS, NODES, or LINKS).
• ViewVar: the index of the particular variable (e.g., flow, depth, pollutant concentration) being displayed.

2.2 Supporting Variables

• MapColor[] or Colors[]: arrays of TColor used to assign colors to each legend interval.
• Digits: integer specifying how many decimal places to display for legend intervals.
• Framed: boolean that determines if the legend is drawn with a bounding rectangle.

---

3. Main Functions and Procedures

3.1 DrawLegend(...)

procedure DrawLegend(
  const R: TRect;
  const C: TCanvas;
  const BackColor: TColor;
  const Framed: Boolean;
  const Legend: TMapLegend;
  const VarIndex: Integer;
  const Digits: Integer;
  const MapColor: array of TColor);

• Purpose
  Draws a color-coded legend for a specified variable on a map canvas.

• Parameters

  1. R: The rectangle on which the legend is drawn.
  2. C: The TCanvas where the legend is rendered.
  3. BackColor: Background color for the legend area.
  4. Framed: Whether or not to draw a rectangle frame around the legend.
  5. Legend: The TMapLegend record containing intervals and the number of intervals.
  6. VarIndex: Identifies which variable’s legend is drawn (e.g., flow, depth).
  7. Digits: Number of decimal digits to display on interval labels.
  8. MapColor: Array of colors associated with each legend interval.

• Logic

  • Retrieves the name and units of the variable from GetObjVarNames (in Uglobals.pas).
  • Clears the rectangle R with the background color.
  • Draws optional framing if Framed is True.
  • Renders a title with object type (“Node”, “Link”, or “Subcatch”) and the variable name (e.g., “Depth”, “Concentration”).
  • For each interval in the legend, draws a small color box and a textual label with the numeric breakpoint (formatted with Digits decimals).
  • Optionally shows the variable’s measurement units (e.g., MGD, CFS, etc.).

3.2 DrawTimeLegend(...)

procedure DrawTimeLegend(
  R: TRect;
  C: TCanvas;
  const BackColor: TColor;
  const S: String);

• Purpose
  Draws the textual “time legend” (the current date/time or elapsed time of the simulation) in a specified rectangle.

• Parameters

  1. R: The rectangle bounding the legend.
  2. C: The map canvas on which to draw.
  3. BackColor: Background color.
  4. S: The time string to display (e.g., “4/25/2024 12:00:00 AM”).

• Logic

  • Fills the background with BackColor.
  • Chooses a font (Arial, Bold, size=8).
  • Writes the string S centered in the rectangle R.
  • The text and pen color is set to contrast with the background (e.g., if the background is black, the text is white).

3.3 EditLegend(...)

function EditLegend(
  var Legend: TMapLegend;
  const VarIndex: Integer;
  const Digits: Integer;
  const TimePeriod: Integer;
  var Colors: array of TColor;
  var Framed: Boolean): Boolean;

• Purpose
  Opens a Legend Editor dialog box (TLegendForm) to let the user modify legend intervals, colors, or whether the legend is framed.

• Parameters

  1. Legend: Reference to the current legend’s intervals, number of intervals, etc.
  2. VarIndex: The variable being depicted.
  3. Digits: Decimal places for numeric intervals.
  4. TimePeriod: The current simulation time period (for possibly adjusting scale).
  5. Colors: The color array for each legend break.
  6. Framed: Whether the user wants a framed bounding rectangle around the legend.

• Logic

  1. Retrieves the object class and variable name/units via GetObjVarNames.
  2. Instantiates TLegendForm (declared in Dlegend.pas), passing in legend data.
  3. If the user clicks OK, the updated intervals, colors, and Framed flag are retrieved.
  4. If user cancels, returns False (no changes applied).

---

4. Integration with Other Units

1. Dlegend.pas: The actual Legend Editor form used by EditLegend.
2. Uglobals.pas:
   • Contains the TMapLegend record, constants like SUBCATCHMENTS, NODES, etc.
   • Provides GetObjVarNames(...) which returns object category name, variable name, and units.
3. Uutils.pas:
   • Offers string formatting and numeric conversion utilities (FloatToStrF, etc.).
4. Fmain.pas or Fmap.pas**:
   • The location where these legends are drawn or updated on the map.
5. System.UITypes:
   • Provides definitions for color, coordinate rectangles, and possibly other UI-related types.

---

5. Typical Usage Flow

1. Drawing the Legend

   • The SWMM main map display calls DrawLegend(...) whenever it needs to refresh or redraw the color-coded legend.
   • The legend’s intervals and colors come from the SubcatchLegend[], NodeLegend[], or LinkLegend[] arrays in Uglobals.

2. User Editing

   • The user right-clicks or otherwise chooses to “Edit Legend.”
   • EditLegend(...) is invoked, which displays TLegendForm.
   • The user adjusts the color scale, intervals, number of intervals, etc.
   • On closing with OK, the updated properties store back into the Legend and Colors arrays.

3. Time Legend

   • In an animation loop or when stepping through simulation time periods, DrawTimeLegend(...) is called to update the displayed date/time in a small region of the map.

---

6. Conclusions

The Ulegend.pas unit provides the fundamental drawing routines and an editing hook for legends in SWMM’s map display. Key highlights include:

• It can display both variable legends (with multiple color intervals) and a time legend.
• Legend intervals are typically read from or saved to Uglobals data structures, ensuring consistency across SWMM.
• A separate form (Dlegend.pas) is used for interactive editing of the color intervals, numeric ranges, and legend styles.

This approach separates the concerns of:

1. Storing legend data (TMapLegend in Uglobals),
2. Drawing it on the map (Ulegend.pas), and
3. Letting the user edit intervals (Dlegend.pas).