244 lines
14 KiB
Markdown
244 lines
14 KiB
Markdown
---
|
|
source_files:
|
|
- Common/DTS.CommonCore/Controls/RoundedBox.xaml.cs
|
|
- Common/DTS.CommonCore/Controls/TestIDView.xaml.cs
|
|
- Common/DTS.CommonCore/Controls/checkbox.xaml.cs
|
|
- Common/DTS.CommonCore/Controls/GridLengthAnimation.cs
|
|
- Common/DTS.CommonCore/Controls/ISOPopup.xaml.cs
|
|
- Common/DTS.CommonCore/Controls/LookupPopup.xaml.cs
|
|
- Common/DTS.CommonCore/Controls/TestIdPreFixSuffixHelper.cs
|
|
- Common/DTS.CommonCore/Controls/AutoSizedGridView.cs
|
|
- Common/DTS.CommonCore/Controls/DynamicGrid.cs
|
|
- Common/DTS.CommonCore/Controls/TestIDViewModel.cs
|
|
- Common/DTS.CommonCore/Controls/TestIDControl.xaml.cs
|
|
- Common/DTS.CommonCore/Controls/GridViewColumnHeaderSelectable.xaml.cs
|
|
- Common/DTS.CommonCore/Controls/GridViewColumnHeaderSearchable.xaml.cs
|
|
- Common/DTS.CommonCore/Controls/GridViewColumnHeaderSearchableCheckBox.xaml.cs
|
|
generated_at: "2026-04-16T02:14:42.933303+00:00"
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|
schema_version: 1
|
|
sha256: "1aa96c65b3ed084a"
|
|
---
|
|
|
|
# Documentation: `DTS.Common.Controls` Module
|
|
|
|
## 1. Purpose
|
|
|
|
This module provides a collection of reusable WPF UI controls and supporting types for the DTS (presumably "Data Test System") application. Its primary role is to encapsulate common UI patterns—such as test ID generation, lookup selection, dynamic grid layout, and enhanced `GridView` column headers with filtering/searching capabilities—into self-contained, declarative components. These controls reduce duplication across UI layers and enforce consistent behavior for test configuration, data display, and user interaction. The module does not contain business logic but serves as a bridge between XAML UI definitions and underlying data/event infrastructure (e.g., Prism EventAggregator, ServiceLocator).
|
|
|
|
---
|
|
|
|
## 2. Public Interface
|
|
|
|
### Classes
|
|
|
|
#### `RoundedBox : UserControl`
|
|
- **`public void Connect(int connectionId, object target)`**
|
|
Stub method intended for connection management; currently throws `NotImplementedException`. Not functional.
|
|
|
|
#### `TestIDView : UserControl`
|
|
- **`public TestIDView()`**
|
|
Constructor; initializes component via `InitializeComponent()`. No additional public members exposed.
|
|
|
|
#### `checkbox : UserControl`
|
|
- **`public void ToolTipEventHandler(object sender, ToolTipEventArgs e)`**
|
|
Handles `ToolTip` events by publishing a `HelpTextEvent` via `IEventAggregator`, including the `sender` and `e` in a `HelpTextEventArg`.
|
|
|
|
#### `GridLengthAnimation : AnimationTimeline`
|
|
- **`public GridLength From { get; set; }`**
|
|
Starting `GridLength` for the animation.
|
|
- **`public GridLength To { get; set; }`**
|
|
Ending `GridLength` for the animation.
|
|
- **`public override object GetCurrentValue(object defaultOriginValue, object defaultDestinationValue, AnimationClock animationClock)`**
|
|
Computes interpolated `GridLength` based on `animationClock.CurrentProgress`. Handles both `Pixel` and `Star` unit types. Assumes `From` and `To` are non-null and valid.
|
|
|
|
#### `ISOPopup : Popup`
|
|
- **`public ISOPopup()`**
|
|
Constructor; initializes component via `InitializeComponent()`.
|
|
- **`private void ISOPart_OnPreviewKeyUp(object sender, KeyEventArgs e)`**
|
|
Filters keyboard input: only allows alphanumeric keys, numeric keypad digits, control keys (Enter, Tab, Backspace, etc.), and `OemQuestion` (`?`). Sets `e.Handled = true` for disallowed keys.
|
|
- **`private void ISOPart_OnGotMouseCapture(object sender, MouseEventArgs e)`**
|
|
If `sender` is a `TextBox`, selects all text (`tb.SelectAll()`).
|
|
- **`private void ISOPart_OnGotKeyboardFocus(object sender, KeyboardFocusChangedEventArgs e)`**
|
|
Same behavior as `ISOPart_OnGotMouseCapture`.
|
|
|
|
#### `LookupPopup : Popup`
|
|
- **`public IEnumerable<IChannelCode> AllChannelCodes { get; private set; }`**
|
|
Property for channel codes (not used in current implementation).
|
|
- **`public event ChannelCodeSelectedEventHandler ChannelCodeSelected`**
|
|
Event raised when a channel code is selected via double-click in the `DataGrid`.
|
|
- **`public IList PossibleChannels { get; set; }`**
|
|
DP-backed property; default value is an empty list of anonymous objects with `Code` and `Name` properties.
|
|
- **`private void PossibleChannels_OnMouseDoubleClick(object sender, MouseButtonEventArgs e)`**
|
|
Raises `ChannelCodeSelected` with `Code` and `Name` extracted via reflection from the selected `DataGrid` item.
|
|
|
|
#### `TestIdPreFixSuffixHelper : Base.BasePropertyChanged`
|
|
- **`public TestIdPreFixSuffix TestIdPreFixSuffix { get; }`**
|
|
Holds the underlying prefix/suffix configuration.
|
|
- **`public override string ToString()`**
|
|
Returns localized string via `Strings.Strings.ResourceManager.GetString(...)`, or fallback to internal string if not found.
|
|
- **`public override bool Equals(object obj)`**
|
|
Compares `TestIdPreFixSuffix.FixedValue`; for `NotFixed`, also compares string representation.
|
|
|
|
#### `TestIdPreFixSuffix`
|
|
- **`public TestIdFixedPrefixSuffixValues FixedValue { get; }`**
|
|
Enum value indicating fixed prefix/suffix type.
|
|
- **`public TestIdPreFixSuffix(TestIdFixedPrefixSuffixValues fixedPrefixSuffix)`**
|
|
Constructor for enum-based initialization.
|
|
- **`public TestIdPreFixSuffix(string dbPrefixSuffix)`**
|
|
Constructor for arbitrary string-based initialization.
|
|
- **`public override string ToString()`**
|
|
Returns internal `_tempString` (e.g., `"TESTID_PREFIX_SUFFIX_1"` for `TimeStamp`).
|
|
|
|
#### `enum TestIdFixedPrefixSuffixValues`
|
|
- `NotFixed = -1`, `None = 0`, `TimeStamp = 1`, `TestSetupName = 2`
|
|
|
|
#### `TestIDViewModel : INotifyPropertyChanged`
|
|
- **`public string TestSetupLabel { get; set; }`**
|
|
DP-backed property; raising `TestSetupLabelVisibility` change on update.
|
|
- **`public Visibility TestSetupLabelVisibility { get; }`**
|
|
Computed property: `Collapsed` if `TestSetupLabel` is null/empty, else `Visible`.
|
|
- **`public string TestIdEditableText { get; set; }`**
|
|
Editable test ID component.
|
|
- **`public void PopulateAllTestIdPrefixSuffixValues(string[] serializedValues)`**
|
|
Populates `_allTestIdPrefixSuffixValues` with built-in items (`None`, `TimeStamp`, `TestSetupName`) and DB-provided values.
|
|
- **`public TestIdPreFixSuffixHelper[] AllTestIdPrefixSuffixValues { get; }`**
|
|
Read-only array of available prefix/suffix helpers.
|
|
- **`public TestIdPreFixSuffixHelper SelectedTestIdPrefixValueItem { get; set; }`**
|
|
Selected prefix helper (default: `None`).
|
|
- **`public TestIdPreFixSuffixHelper SelectedTestIdSuffixValueItem { get; set; }`**
|
|
Selected suffix helper (default: `TimeStamp`).
|
|
- **`public string TestName { get; set; }`**
|
|
Used for `TestSetupName` prefix/suffix.
|
|
- **`public string GetTestId()`**
|
|
Constructs test ID by concatenating prefix, `TestSetupLabel`, `TestIdEditableText`, and suffix with `_` separator.
|
|
- **`private string GetRunTimeTestIdPrefixOrSuffix(TestIdPreFixSuffixHelper prefixOrSuffix)`**
|
|
Returns runtime value: `TestName` for `TestSetupName`, timestamp for `TimeStamp`, or string representation for `NotFixed`.
|
|
- **`public string GetTestIdTimestamp()`**
|
|
Returns formatted timestamp: `"yyyy_MM_dd HH_mm"`.
|
|
|
|
#### `TestIdControl : UserControl, INotifyPropertyChanged`
|
|
- **Identical public interface to `TestIDViewModel`** (same properties, methods, and behavior).
|
|
*Note: Code comments indicate this control is deprecated and should be removed after TTS migration.*
|
|
|
|
#### `GridViewColumnHeaderSelectable : UserControl, IBasePropertyChanged`
|
|
- **`public string ListviewId { get; set; }`**
|
|
DP-backed; used to correlate with `ListViewStatusEvent`.
|
|
- **`public string HeaderTitle { get; set; }`**
|
|
DP-backed; default `"Awesome"`.
|
|
- **`public bool ToggleButtonIsChecked { get; set; }`**
|
|
Controls popup state; raises `OpenChanged` event and `ToggleIconGeometry` change.
|
|
- **`public Geometry ToggleIconGeometry { get; }`**
|
|
Computed based on `HeaderSearchTerm` (not implemented—uses `dtsGridViewColumnHeader.FindResource(...)`).
|
|
- **`public event RoutedEventHandler OpenChanged`**
|
|
Raised when popup state changes.
|
|
- **`public event RoutedEventHandler ClickHandler`**
|
|
Raised on header click (via `PreviewLeftButtonUp`).
|
|
- **`public event RoutedEventHandler SelectAll`**
|
|
Raised on "Select All"/"Clear All" button clicks.
|
|
|
|
#### `GridViewColumnHeaderSearchable : UserControl, IBasePropertyChanged`
|
|
- **`public string ListviewId { get; set; }`**
|
|
DP-backed; used to correlate with `ListViewStatusEvent`.
|
|
- **`public string HeaderTitle { get; set; }`**
|
|
DP-backed; default `"Awesome"`.
|
|
- **`public bool ToggleButtonIsChecked { get; set; }`**
|
|
Controls popup state; raises `OpenChanged` event and `ToggleIconGeometry` change.
|
|
- **`public string HeaderSearchTerm { get; set; }`**
|
|
DP-backed; default `""`. Raises `Search` event on change.
|
|
- **`public Geometry ToggleIconGeometry { get; }`**
|
|
Computed based on `HeaderSearchTerm` (uses `dtsGridViewColumnHeader.FindResource(...)`).
|
|
- **`public event RoutedEventHandler OpenChanged`**
|
|
Raised when popup state changes.
|
|
- **`public event RoutedEventHandler ClickHandler`**
|
|
Raised on header click (suppresses click if inside `Popup`).
|
|
- **`public event RoutedEventHandler Search`**
|
|
Raised when `HeaderSearchTerm` changes or Enter key pressed.
|
|
|
|
#### `BoolToInvertedBoolConverter : IValueConverter`
|
|
- **`public object Convert(object value, ...)`**
|
|
Converts `bool` to inverted `bool`.
|
|
- **`public object ConvertBack(...)`**
|
|
Throws `NotImplementedException`.
|
|
|
|
#### `GridViewColumnHeaderSearchableCheckBox : UserControl, IBasePropertyChanged`
|
|
- **`public string ListviewId { get; set; }`**
|
|
DP-backed; used to correlate with `ListViewStatusEvent`.
|
|
- **`public string HeaderTitle { get; set; }`**
|
|
DP-backed; default `"Awesome"`.
|
|
- **`public bool ToggleButtonIsChecked { get; set; }`**
|
|
Controls popup state; raises `OpenChanged` event and `ToggleIconGeometry` change.
|
|
- **`public string HeaderSearchTerm { get; set; }`**
|
|
DP-backed; default `""`. Raises `Search` event on change.
|
|
- **`public Geometry ToggleIconGeometry { get; }`**
|
|
Computed based on `HeaderSearchTerm` (uses `dtsGridViewColumnHeader.FindResource(...)`).
|
|
- **`public event RoutedEventHandler OpenChanged`**
|
|
Raised when popup state changes.
|
|
- **`public event RoutedEventHandler ClickHandler`**
|
|
Raised on header click.
|
|
- **`public event RoutedEventHandler Search`**
|
|
Raised when `HeaderSearchTerm` changes (named `SearchCheckBox` in event registration).
|
|
- **`public event RoutedEventHandler Filter`**
|
|
Raised on "All"/"True"/"False" button clicks.
|
|
|
|
#### `AutoSizedGridView : GridView`
|
|
- **`protected override void PrepareItem(ListViewItem item)`**
|
|
Ensures columns with `"Auto"` width are measured correctly by forcing remeasurement. Preserves bound column bindings.
|
|
|
|
#### `DynamicGrid : Grid, INotifyPropertyChanged`
|
|
- **`public byte GridColumns { get; set; }`**
|
|
Number of columns; triggers `Refresh()` on change.
|
|
- **`public void Refresh()`**
|
|
Dynamically rebuilds `ColumnDefinitions` and `RowDefinitions` to fit children in a left-to-right, top-to-bottom flow. Last column is `*` (star), others are `Auto`. Adds a final `*` row.
|
|
- **`protected override void OnVisualChildrenChanged(...)`**
|
|
Calls `Refresh()` on child addition/removal.
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
- **`GridLengthAnimation.GetCurrentValue`** assumes `From` and `To` are non-null and their `Value` properties are finite. No validation is performed.
|
|
- **`TestIdPreFixSuffixHelper.ToString()`** relies on `Strings.Strings.ResourceManager` existing and containing keys matching `TestIdPreFixSuffix.ToString()` output. Falls back to internal string if not found.
|
|
- **`LookupPopup.PossibleChannels`** must contain objects with `Code` and `Name` properties (via reflection); no compile-time or runtime validation.
|
|
- **`ISOPopup` key filtering** is strict: only allows specific keys (alphanumeric, numeric keypad, control keys, `?`). Other keys are rejected (`e.Handled = true`).
|
|
- **`DynamicGrid.Refresh()`** assumes `Children` contains only `UIElement`s; no type checking.
|
|
- **`TestIdControl` and `TestIDViewModel`** share identical logic but are separate implementations (tech debt).
|
|
- **`GridViewColumnHeader*` controls** depend on `dtsGridViewColumnHeader` resource dictionary containing `"DownArrowIconGeometry"` and `"FilterIconGeometry"` resources.
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
### External Dependencies
|
|
- **WPF Framework**: `System.Windows`, `System.Windows.Controls`, `System.Windows.Media.Animation`, etc.
|
|
- **Prism Library**: `Microsoft.Practices.Prism.Events` (`IEventAggregator`, `EventBase`).
|
|
- **Enterprise Library**: `Microsoft.Practices.ServiceLocation` (`ServiceLocator`).
|
|
- **DTS Common Core**:
|
|
- `DTS.Common.Base.IBasePropertyChanged`
|
|
- `DTS.Common.Events.*` (`HelpTextEvent`, `ListViewStatusEvent`)
|
|
- `DTS.Common.Interface.Channels.ChannelCodes.IChannelCode`
|
|
- `DTS.Common.Utilities.Logging.*`
|
|
- `DTS.Common.Strings` (for `Strings.Strings.ResourceManager`)
|
|
|
|
### Internal Dependencies
|
|
- **Controls**:
|
|
- `TestIDViewModel` and `TestIdControl` share logic but are not interdependent.
|
|
- `GridViewColumnHeader*` controls depend on shared XAML resources (`dtsGridViewColumnHeader`).
|
|
- **Data Models**:
|
|
- `TestIdPreFixSuffix` and `TestIdPreFixSuffixHelper` are tightly coupled.
|
|
- `AutoSizedGridView` depends on `GridViewColumn` metadata (`Width`, bindings).
|
|
|
|
---
|
|
|
|
## 5. Gotchas
|
|
|
|
- **`RoundedBox.Connect` is unimplemented** and will throw `NotImplementedException` if called.
|
|
- **`LookupPopup.PossibleChannels` uses reflection** (`item.GetType().GetProperty(...)`) to extract `Code`/`Name`. Fails silently if properties are missing or inaccessible (returns `null`).
|
|
- **`TestIdControl` is deprecated** (comment: *"Remove this control after deleting the TTS module..."*). Prefer `TestIDViewModel`.
|
|
- **`GridViewColumnHeader*` controls** assume `dtsGridViewColumnHeader` resource dictionary exists and contains required geometries. Missing resources cause runtime exceptions.
|
|
- **`BoolToInvertedBoolConverter.ConvertBack` is unimplemented**—throws `NotImplementedException`.
|
|
- **`DynamicGrid.Refresh()` adds a final `*` row** regardless of content, which may cause unexpected spacing.
|
|
- **`GridLengthAnimation` does not handle `NaN` or negative `GridLength.Value`**—may produce invalid interpolated values.
|
|
- **`ISOPopup` key filtering** is overly restrictive (e.g., no spaces, punctuation beyond `?`), potentially limiting user input.
|
|
- **`TestIDViewModel` and `TestIdControl` duplicate logic**—changes must be applied in both places.
|
|
- **`AutoSizedGridView` uses `GetHashCode()` for column tracking**—not robust if columns are reused or recreated (hash collisions possible). |