init

docs/ai/DataPRO/DataPRO/Controls/Downloads.md

@@ -0,0 +1,67 @@
+---
+source_files:
+  - DataPRO/DataPRO/Controls/Downloads/SimpleDownloadOptions.xaml.cs
+generated_at: "2026-04-17T15:59:49.852280+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "0e1d27b067d2cea1"
+---
+
+# Documentation: SimpleDownloadOptions
+
+## 1. Purpose
+
+`SimpleDownloadOptions` is a WPF `UserControl` that provides a UI for configuring download options for recorded data. It manages Regions of Interest (ROI), download events, and validates download parameters against recording mode constraints. The control serves as the configuration interface for users to define what data to download, which time regions to include, and which channels to capture, while enforcing business rules specific to different recording modes (CircularBuffer, Recorder, Active, etc.).
+
+---
+
+## 2. Public Interface
+
+### Methods
+
+| Signature | Description |
+|-----------|-------------|
+| `void SetEnabled(bool bEnable)` | Enables or disables the control. Uses `Dispatcher.BeginInvoke` for thread-safe access if called from a non-UI thread. Returns early if `((App)Application.Current).CurrentUser` is null. |
+| `void SetParent(object o)` | Delegates to `_roiChannelsVm.SetParent(o)` if the ROI channels ViewModel is initialized. |
+| `void StartSearch(string term)` | Triggers filtering on the ROI channels ViewModel via `_roiChannelsVm.Filter(term)`. |
+| `bool ValidatePage(double PreTriggerSeconds, double PostTriggerSeconds, RecordingModes recordingMode, ref List<string> errors)` | Validates ROI configuration and channel assignments. Returns `true` if valid; appends error messages to the `errors` list. |
+| `void ClearView()` | Resets all UI state: clears `RegionsOfInterest`, `EventsToDownload`, resets timing values to 0, sets `RecordingMode` to `CircularBuffer`, and collapses visibility flags. |
+| `void Initialize(double dataStart, double dataEnd, double preTrigger, double postTrigger, RecordingModes recordingMode, BindingList<IRegionOfInterest> regionsOfInterest, BindingList<IDownloadEvent> eventsToDownload, Dictionary<string, IDASHardware> hardwareLookup, TestTemplate testTemplate, IReadOnlyDictionary<int, double> eventLengthByIndex)` | Populates the control with download configuration data. Calculates aggregate sample rate, populates event lengths, and initializes the ROI channels ViewModel. |
+
+### Properties
+
+| Type | Name | Access | Description |
+|------|------|--------|-------------|
+| `Visibility` | `RoiVisibility` | get/set | Controls visibility of ROI section. Backed by `_roiVisibility`, default is `Collapsed`. |
+| `Visibility` | `EventDetailsVisibility` | get/set | Controls visibility of event details section. Default is `Collapsed`. |
+| `Visibility` | `DataDetailsVisibility` | get | Visibility for data details section. Default is `Collapsed`. |
+| `Visibility` | `ChannelDetailsVisibility` | get | Visibility for channel details section. Becomes `Visible` when `RegionsOfInterest.Count > 1`. |
+| `string` | `DownloadPath` | get | Full path to download folder, derived from `Properties.Settings.Default.DownloadFolder`. |
+| `double` | `DataStart` | get | Start time of data range. |
+| `double` | `DataEnd` | get | End time of data range. |
+| `double` | `PreTriggerSeconds` | get | Pre-trigger duration in seconds. |
+| `double` | `PostTriggerSeconds` | get | Post-trigger duration in seconds. |
+| `double` | `SampleRateAggregate` | get | Aggregate sample rate across DAS units. Set to `double.NaN` if rates differ. |
+| `string` | `SPSText` | get | Formatted sample rate string; returns localized "Multiple Sample Rates" text if `SampleRateAggregate` is `NaN`. |
+| `RecordingModes` | `RecordingMode` | get | Current recording mode. |
+| `BindingList<IRegionOfInterest>` | `RegionsOfInterest` | get | Collection of ROI definitions. |
+| `BindingList<IDownloadEvent>` | `EventsToDownload` | get | Collection of events selected for download. |
+| `RoutedCommand` | `AddROICommand` | get/set | Command to add a new ROI period. |
+| `RoutedCommand` | `RemoveROICommand` | get/set | Command to remove an ROI period. |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `PropertyChangedEventHandler PropertyChanged` | Standard `INotifyPropertyChanged` implementation for data binding. |
+
+---
+
+## 3. Invariants
+
+### ROI Validation Rules (enforced in `ValidateROIControl`)
+
+1. **Unique Suffixes**: All ROI items must have unique `Suffix` values. Grouping by suffix and counting must equal total count.
+2. **At Least One Enabled ROI**: `RegionsOfInterest` must contain at least one item where `IsEnabled == true`.
+3. **Valid Region Bounds**: For each enabled ROI, `Start` must not equal `End`, and `Start` must not be greater than `End`.
+4. **Channel Assignment for Multiple ROIs**: When `RegionsOfInterest.Count > 1`, each enabled