SWMM5 Delphi GUI Ubrowser.pas Summary

 Extended and Expanded Summary of Ubrowser.pas

The unit Ubrowser.pas is part of the EPA SWMM (Storm Water Management Model) Delphi-based GUI. It contains functions and procedures that drive the Browser panel within the MainForm of the SWMM application. The Browser panel has two parts:

1. A Data Page that lists categories (nodes) of SWMM data (e.g., raingages, subcatchments, nodes, links, etc.) in a TreeView, and displays specific items from a selected category in a ListBox.
2. A Map Page that hosts combo boxes for selecting map display variables and controls for time/date selection.

This unit organizes, updates, and manipulates the data items that appear in the Browser, including the addition, deletion, sorting, and editing of objects, plus controlling output display on the map for different variables and time periods.

Below is a detailed outline:

---

1. Main Purpose

• It manages the content and behavior of the Browser panel on the MainForm.
• It supports object addition, deletion, sorting, renaming, editing, and selection in the Data Page.
• It also controls time and variable selection for map display in the Map Page (subcatchment, node, link data, date/time, etc.).

---

2. Key Global Variables and Utilities

Global Variables:

• CurrentDateIndex, CurrentTimeIndex: track the user-selected date/time indexes from the Date and Time listboxes.
• OldSubcatchVar, OldNodeVar, OldLinkVar: store the previously selected map display variables for subcatchments, nodes, and links so that we can restore or update them after a new analysis.

Stringlist Sorting:

• CompareIDStrings: a specialized comparison function that tries to compare numeric IDs numerically, and falls back to normal string comparison otherwise. Helpful for sorting object IDs like 1, 2, 10, 20.
• SortStringlist: a QuickSort-based routine to sort TStringList items using a user-supplied comparison function (here, CompareIDStrings).

---

3. Initial Setup Routines

1. InitBrowser

   • Called at application start or upon creating a new project.
   • Clears the map display variables, resets them to NOVIEW, and calls InitMapViewBoxes.

2. InitDataPage

   • Called when a new project begins.
   • Clears the “data” side of the Browser (the TreeView's selection, the ItemListBox, and associated states).

3. InitMapPage

   • Called before running an analysis.
   • Resets stored OldSubcatchVar, OldNodeVar, OldLinkVar.
   • Clears the map theme combo boxes and date/time controls, then calls InitMapViewBoxes to populate them.
   • Disables date/time controls (will enable once a simulation is completed).
   • Assigns units to potential output variables (e.g., flow units, pollution units).

4. InitMapViewBoxes

   • Fills the Subcatch, Node, and Link combo boxes with input variables only. After the simulation, it calls UpdateMapViewBoxes to add output variables.

---

4. Browser Data Page Manipulation

The Data Page has a TreeView listing categories (like “Subcatchments,” “Nodes,” “Hydrographs,” etc.), and an ItemListBox showing items within a selected category. The procedures relevant here:

• BrowserAddItem(ObjType, Index)
  Adds a new object of a given type to the browser’s list box (and optionally refreshes the display if it matches the current list). Updates HasItems for that object type.

• BrowserDeleteObject
  Prompts the user for confirmation (if Uglobals.ConfirmDelete is true) and then deletes the currently selected object in the list box and database. Calls DeleteItem internally.

• BrowserEditObject
  Invokes the universal object editing system (e.g., Uedit.EditObject). This can bring up specialized dialogs or the property editor for a selected object.

• BrowserNewObject
  Creates a new non-visual object by calling Uedit.AddNonvisualObject(Uglobals.CurrentList). For visual objects, the user typically uses the map-based “Add” toolbar buttons.

• BrowserSortObjects
  Sorts the current object’s items by ID using SortStringList(..., CompareIDStrings). The user sees these sorted in the ItemListBox.

• DeleteItem
  Called by BrowserDeleteObject or other routines to remove an item from the project’s database. If the object is visual, it calls MapForm.EraseObject(...).

• BrowserUpdate(ObjType, Index)
  The core routine that sets the current object type, selects the item in the list box, updates the property editor if necessary, highlights the item on the map, and sets the browser’s speed button states.

---

5. Browser Map Page: Time and Variable Control

• UpdateMapPage
  Called after a new successful simulation run. It populates the date list box and time list box, sets up the scroll bars, and re-enables those controls. Also sets the current map display to time period 0.

• EnableDateTimeControls(Boolean)
  Disables/enables the date/time controls in the interface.

• RefreshTimeListBox(Backwards)
  Rebuilds the items in the TimeOfDay list box for the selected date, either enumerating the day’s steps forward or backward.

• ChangeDate(I)
  Moves to date index I, calls RefreshTimeListBox with a direction, and thus changes the map’s date portion of the time.

• ChangeTimePeriod(I)
  Moves to time index I, sets Uglobals.CurrentPeriod, calls RefreshTimeLegend, and triggers RefreshMap plus UpdateProfilePlots.

• GetCurrentPeriod
  Returns the absolute reporting period from the sum of CurrentDateIndex + CurrentTimeIndex or just direct if DeltaDateTime >= 1.

• RefreshTimeLegend
  Adjusts the text in the map’s Time Legend panel (i.e., shows the date/time of current period). Also updates ElapsedTimePanel in the main status bar.

• IncreaseElapsedTime / DecreaseElapsedTime
  Let the user step forward/backward one time step (or day).

• RefreshMap
  Recomputes color themes if results exist, gets flow directions, updates subcatch/node/link color indexes, and redraws the map.

• RefreshMapColors
  If the user changes from old variable to new, reapply color sets for subcatchments, nodes, or links.

• UpdateMapViewBoxes
  After a run, it appends output variables (e.g., rainfall, infiltration, flow, or user pollutant names) to the Subcatch/Node/Link combo boxes.

---

6. Converting Object Types

Two specialized routines:

• ConvertNode(oldType, oldIndex, newType)

  • Creates a new node object of newType, copies property data from the old node, updates references in subcatchments and links, etc.
  • Returns the new node’s index.

• ConvertLink(oldType, oldIndex, newType)

  • Similarly, creates a new link object of newType, copies old link data, updates references, and returns the new link’s index.

These are used, for example, if the user changes a Node from “Junction” to “Storage” or a Link from “Conduit” to “Weir.”

---

7. Utility Functions

1. GetIndexOfVar(ObjType, S)
   Finds map variable index by name S in the theme combo box for ObjType.

2. GetIndexFromObject(ObjType) and GetObjectFromIndex(Index)
   Map from the object types to TreeView node indexes (and vice versa).

3. AssignOutputUnits
   Assigns measurement units to analysis output variables (flow units, volume, etc.) for subcatchments, nodes, and links.

4. SetBrowserButtons(ObjType, Index)
   Controls the enabling/disabling of the “New,” “Delete,” “Edit,” “Sort,” “Up,” “Down” buttons on the Data Page, depending on whether objects exist and what type they are.

5. RefreshObjectImage(ObjType, ImageIndex)
   Potentially updates the image next to an object in the TreeView (not currently used).

6. UpdateHasItems(ObjType)
   Tracks if the project database has at least one item of a given type or not.

---

8. Typical Flow of Calls

• Initialization: InitBrowser, InitDataPage, InitMapPage set up the empty project or new run.
• Adding/Deleting Objects: BrowserAddItem, BrowserDeleteObject, DeleteItem.
• Editing: BrowserEditObject calls Uedit.<method>.
• Sorting: BrowserSortObjects uses SortStringList.
• Switching: BrowserUpdate moves to a new object type or item, updating displays in list boxes, property editor, and map.
• Map: UpdateMapPage, EnableDateTimeControls, RefreshTimeListBox, ChangeTimePeriod, RefreshMap handle date/time changes and re-draw of color-coded objects.
• Convert: ConvertNode and ConvertLink handle advanced usage.

---

9. Conclusion

Ubrowser.pas plays a vital role in orchestrating the Browser panel’s data structure and interface interactions in the SWMM GUI. It ensures consistency between the project database (Project.Lists[ObjType]), the main form’s TreeView/ListBox, the property editor, and the study area map. Through a well-defined set of routines, it supports editing, sorting, timing, and theming operations that allow users to effectively manage SWMM model data within the application.