SWMM5 Delphi GUI TPropEdit.pas Summary

Below is an extended and expanded summary of the PropEdit.pas code. It gives a high-level description of how the TPropEdit component operates, the sub-components it creates, and how it manages the display and editing of property values.

---

1. Purpose and Overview

• PropEdit.pas defines a Delphi component named TPropEdit, which visually displays a set of properties in a two-column layout—property names on the left, and corresponding values on the right.
• The component manages reading, displaying, and editing property values via specialized in-place editors (an TEdit for text or numeric input and a TComboBox for list-based selections).
• Each individual “property” is described by a TPropRecord structure, which specifies how the property is labeled and how it can be edited.

2. Relationship to Delphi UI

• TPropEdit derives from TCustomPanel and includes:
  • A header panel with two sub-panels for column headings,
  • A splitter that allows resizing of the two column headers,
  • A string grid (named FGrid) that contains rows for each property and two columns (property name / property value),
  • Two ephemeral editor controls: a normal edit control (FEdit) and a combo box (FCombo)—both appear temporarily, placed over a cell to allow user input.

3. The TPropRecord Structure

Each property is defined by a record named TPropRecord:

• Name: The user-facing name of the property (appears in the left column).
• Style: One of the following edit styles:
  1. esHeading: Not editable; used as a descriptive heading.
  2. esReadOnly: The property displays a value that cannot be edited.
  3. esEdit: User can type text or numbers in an TEdit control.
  4. esComboList: A drop-down list (fixed choices, no user text input).
  5. esComboEdit: A drop-down list (but users can also edit or type new text).
  6. esButton: Special style that displays a “button” (drawn within the cell) which triggers an external event.
• Mask: An edit mask that further restricts esEdit entry (e.g., numeric only, positive numeric, no spaces, or none).
• Length: Maximum text length allowed in the esEdit style.
• List: For combo box styles, a string containing the possible choices (separated by #13).

4. TPropEdit Sub-Components

When TPropEdit is first created:

1. FGrid (a TStringGrid)
   • Two columns: property name (col 0) and property value (col 1).
   • Allows for custom drawing of cells (OnDrawCell) so that headings, read-only cells, and button cells can be visually distinct.
   • Manages row selection, key navigation, etc.
2. Header Panel / Sub-panels
   • A top panel FPanel1 that holds:
     • FHeader1 (the left header label, i.e., property name heading),
     • FSplitter (the movable splitter),
     • FHeader2 (the right header label, i.e., property value heading).
   • The user can drag FSplitter to adjust how much width is given to each column.
3. FEdit (TEdit)
   • Invisible by default.
   • Placed over a grid cell for in-place editing of textual/numeric properties.
   • Restricts user input according to the property’s Mask (e.g., numeric only).
4. FCombo (TComboBox)
   • Invisible by default.
   • Used instead of FEdit when the property’s style requires a drop-down list of choices (esComboList/esComboEdit).
   • The user can pick from a set of items or, in esComboEdit, can also type a custom value.

5. Property Editor Lifecycle

1. Loading Properties
   • The SetProps method is called with two parameters:
     • An array of TPropRecord (defining each property’s name, edit style, etc.),
     • A matching stringlist of initial values for these properties.
   • TPropEdit sets up the FGrid row count to match the number of properties, placing each property’s name in col 0 and each initial value in col 1.
2. Display and Interaction
   • The user sees each property name in the left column and the current value in the right column.
   • If the property style is:
     • esHeading: Shows only a label, merges with the left column cells, not editable.
     • esReadOnly: The user cannot edit the value.
     • esEdit: The user can click or press a key to invoke the FEdit control.
     • esComboList/esComboEdit: The user sees or can invoke a FCombo drop-down for selecting or typing a value.
     • esButton: The property row shows a small “button” on the right. When clicked, it fires the OnButtonClick event.
3. Editing
   • On a keystroke or double-click in a cell, TPropEdit:
     • Positions and displays either FEdit or FCombo exactly over that cell.
     • The user modifies the text or picks from the list.
     • On pressing Enter, or leaving the cell, TPropEdit hides the edit control.
   • The OnValidate event (if assigned) is called to check the new value. If valid, TPropEdit updates FGrid and its internal stringlist. Otherwise, it can revert or show an error message.
4. Finishing Edits
   • The “modified” flag is set if the user changes a property.
   • The user or code calls EndEditing or sets focus away from the editor to finalize changes.

6. Event Handling

• Row selection is tracked, and OnRowSelect can be triggered whenever a new row is chosen.
• OnValidate is where code can confirm or reject new values.
• OnButtonClick is triggered for an esButton style property row if a user clicks that property’s “button.”

7. Key Implementation Details

1. GoValidate
   • Utility method that checks if a user’s new value is valid via an OnValidate callback. If it is valid, it updates the grid and the underlying stringlist.
   • If not valid, raises an exception or discards changes.
2. StringGrid Drawing
   • The component customizes the grid appearance for headings, read-only cells, etc.
   • For an esButton property, the right column draws a small button-like rectangle.
3. FHeaderSplit
   • A user-defined percentage controlling the relative widths of property vs. value columns. The user can drag a splitter at runtime to change these columns’ widths.
   • SplitterMoved updates the grid column widths accordingly.
4. FReadOnlyColor, FValueColor, FHeadBackColor, FHeadForeColor
   • Control the background/foreground colors of read-only property cells, value cells, and heading cells.

8. Typical Usage

1. Create a TPropEdit component on a form.
2. Call SetProps(PropertyArray, Values) to populate the editor with property definitions and initial values.
3. Display the form, letting the user interact with the property table.
4. Validation of changed values occurs through the OnValidate event.
5. Button property rows use the OnButtonClick event for specialized actions.
6. At the end, retrieve updates (if any) from the property editor via the underlying stringlist or by calling GetProp for each property.

9. Summary

• TPropEdit is a self-contained property editing panel. It organizes properties (described by TPropRecord) in a grid.
• It seamlessly offers different editing styles: read-only, heading, direct text input, combo box selection, or custom “button event.”
• By hooking up OnValidate and OnButtonClick handlers, one can create a robust, small-scale “property inspector” tailored to Delphi applications.
• It features column headings, color customizations, automatic resizing with a splitter, and row-based event callbacks.

In short, TPropEdit gives a developer the means to present a property table to end-users with minimal overhead, while also allowing easy customization for validation and specialized event handling.