SWMM5 Delphi GUI Dlegend.pas Summary

 Below is an overview of Dlegend.pas, a Delphi unit from SWMM 5.2 that provides a form (TLegendForm) for editing a map legend. The legend is used to display intervals (ranges) of a particular hydraulic/hydrologic variable in color-coded form on the SWMM map.

---

1. Purpose and Context

This unit creates a Legend Editor dialog that allows the user to:

1. Define up to 5 intervals for a selected map variable (e.g., subcatchment runoff, node depth, or link flow).
2. Assign a color to each interval.
3. Optionally auto-generate intervals from the current min/max of the selected variable.
4. Pick a color ramp from predefined gradient schemes or manually choose individual colors.
5. Decide whether the legend appears with or without a frame on the map.

Because only 5 intervals are supported, the code references a constant MAXINTERVALS = 5 (though it’s effectively 5 minus 1 for distinct interval boundaries, plus one color for the top range).

---

2. Main Form Elements: TLegendForm

2.1 Color Boxes (Shapes)

• Box0 … Box4: five TShape components that represent the color assigned to each interval boundary and the final interval.
• A Hiliter shape that can highlight whichever color box the user clicks.

2.2 Interval Edit Controls

• Edit1 … Edit5: five TEdit fields in which the user can type numeric values that define the boundaries between intervals (e.g., 0, 2, 5, 10 …).

2.3 Other Controls and Buttons

• BtnAutoScale: automatically set interval boundaries based on the current min/max values of the selected map variable.
• BtnColorRamp: open a “Color Ramp” dialog (from Dcolramp.pas) to pick from a predefined set of color gradients.
• BtnReverse: reverse the order of the colors currently shown.
• CheckFramed: toggles whether the legend is displayed in a framed box.
• Standard OK, Cancel, and Help buttons.

---

3. Workflow and Data Flow

3.1 Input Data

SetData(...) is called externally to initialize the form:

1. VarName and VarUnits: text labels for the map variable being legended (e.g., “Depth,” “inches”).
2. Digits: number of decimal digits to display.
3. TimePeriod: which time period (e.g., simulation timestep) this legend applies to (for min/max retrieval).
4. Legend: a TMapLegend record that holds:
   • Intervals[]: up to 5 interval boundary values.
   • Nintervals: how many intervals are actually in use.
   • Ltype: which object category (subcatchments, nodes, or links) the legend is for.
5. An array of TColor for each color box.
6. A boolean that indicates whether the legend is framed (CheckFramed.Checked).

Inside SetData, the code:

• Sets up the color boxes (Box0 … Box4) to use the provided colors.
• Fills each Edit# with the corresponding numeric boundary from Legend.Intervals[] (or blank if MISSING).
• Records the relevant legend variable info in local fields (LegendType, LegendVarIndex, etc.).

3.2 Editing the Legend

The user can:

1. Manually edit the numeric boundary in each Edit# to define intervals.
2. Click a color box (BoxMouseDown) to change its color via the standard ColorDialog1.
3. Use BtnAutoScale to compute intervals from the project’s min/max of the selected variable at the chosen time step.
4. Use BtnColorRamp to pick a standard color gradient, which updates the shape colors.
5. Use BtnReverse to invert the current color sequence.

3.3 Validation and OK/Cancel

• BtnOKClick calls ValidateInput:
  1. Ensures each non-blank Edit# is a valid float.
  2. Checks that the user doesn’t leave all intervals blank.
  3. Sets Modified := True if something changed.
• If validation fails, the form remains open. Otherwise, it closes with mrOK.

3.4 Saving the Legend

GetData is called after the user presses OK to retrieve:

1. Interval Values: The form merges any blank entries, thus “compressing” the intervals so that only non-blank ones remain.
2. Colors: The color for each non-blank interval boundary is taken from the color box above it, and the final color from the last box.
3. Framed: whether CheckFramed was checked.

Those updates are stored in the Legend record and the color array, which the calling code can use to redraw the map legend.

---

4. Notable Procedures

4.1 BtnAutoScaleClick

• Retrieves the min and max of the selected variable (depending on LegendType—subcatchment, node, or link) from the Uoutput routines.
• Divides the range into equal increments if feasible, placing the resulting values into Edit1..Edit5.
• If the range is invalid (Xmax = MISSING), a warning is displayed.

4.2 BtnColorRampClick

• Displays TColorRampForm (from Dcolramp.pas), allowing a user to pick from a set of built-in color schemes (e.g., rainbow, heatmap, etc.).
• Copies the chosen ramp colors into Box0..Box4.

4.3 BtnReverseClick

• Reverses the order of the colors in the boxes (box0 ↔ box4, box1 ↔ box3, etc.).

4.4 BoxMouseDown

• When the user clicks on a shape (e.g., Box3), the code visually highlights it (Hiliter) and opens a ColorDialog.
• On choosing a new color, that color is assigned to the shape’s Brush.Color.

---

5. Summary

• Dlegend.pas provides a compact “Legend Editor” form that handles up to 5 intervals and color boxes for a SWMM map variable.
• Users can manually define or auto-generate intervals, choose a color ramp, or pick each color individually.
• The final result is stored in a TMapLegend record and a color array, allowing the map to be rendered with a custom legend that suits the user’s data range and color preferences.

This feature helps visualize results effectively, making it simpler to interpret and diagnose modeling outcomes within SWMM.