DP44/enriched-qwen3-coder-next/Common/DTS.Common/Controls.md

---
source_files:
  - Common/DTS.Common/Controls/RoundedBox.xaml.cs
  - Common/DTS.Common/Controls/TestIDView.xaml.cs
  - Common/DTS.Common/Controls/checkbox.xaml.cs
  - Common/DTS.Common/Controls/GridLengthAnimation.cs
  - Common/DTS.Common/Controls/ISOPopup.xaml.cs
  - Common/DTS.Common/Controls/LookupPopup.xaml.cs
  - Common/DTS.Common/Controls/TestIdPreFixSuffixHelper.cs
  - Common/DTS.Common/Controls/AutoSizedGridView.cs
  - Common/DTS.Common/Controls/TestIDTestBox.xaml.cs
  - Common/DTS.Common/Controls/DynamicGrid.cs
  - Common/DTS.Common/Controls/TestIDViewModel.cs
  - Common/DTS.Common/Controls/TestIDControl.xaml.cs
  - Common/DTS.Common/Controls/GridViewColumnHeaderSelectable.xaml.cs
  - Common/DTS.Common/Controls/IPTextBox.xaml.cs
  - Common/DTS.Common/Controls/GridViewColumnHeaderSearchable.xaml.cs
generated_at: "2026-04-16T02:54:39.689905+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "65aa3f7b7e06fc1f"
---

# DTS.Common.Controls Module Documentation

## 1. Purpose

This module provides a collection of WPF UI controls and supporting utilities for the DTS (Device Test System) application. It includes specialized input controls (e.g., `IPTextBox`, `TestIDTextBox`), layout helpers (`DynamicGrid`, `GridLengthAnimation`), and test ID management components (`TestIdPreFixSuffixHelper`, `TestIDViewModel`, `TestIdControl`). These controls extend standard WPF functionality to support domain-specific requirements such as structured test ID generation, IP address entry validation, dynamic grid layout, and column header interactions (selectable/searchable headers with popups). The module serves as a foundational UI component library for test setup and execution interfaces.

## 2. Public Interface

### Classes

#### `RoundedBox`
- **`public void Connect(int connectionId, object target)`**  
  Placeholder method intended for connection logic; currently throws `NotImplementedException`.

#### `TestIDView`
- No public methods or properties exposed beyond default `UserControl` behavior.

#### `checkbox`
- **`public void ToolTipEventHandler(object sender, ToolTipEventArgs e)`**  
  Handles tooltip requests by publishing a `HelpTextEvent` via Prism's `IEventAggregator`, including the sender and event args in the `HelpTextEventArg`.

#### `GridLengthAnimation`
- **`public GridLength From { get; set; }`**  
  Starting `GridLength` value for the animation.
- **`public GridLength To { get; set; }`**  
  Ending `GridLength` value for the animation.
- **`public override object GetCurrentValue(object defaultOriginValue, object defaultDestinationValue, AnimationClock animationClock)`**  
  Computes interpolated `GridLength` value based on animation progress, preserving `GridUnitType` (Star/Pixel) from the `To` value.

#### `ISOPopup`
- **`private void ISOPart_OnPreviewKeyUp(object sender, KeyEventArgs e)`**  
  Filters keyboard input in child controls to allow only alphanumeric keys, numeric pad digits, control keys (Enter, Tab, Backspace, etc.), and the `OemQuestion` key.
- **`private void ISOPart_OnGotMouseCapture(object sender, MouseEventArgs e)`**  
  Selects all text in a `TextBox` when it receives mouse capture.
- **`private void ISOPart_OnGotKeyboardFocus(object sender, KeyboardFocusChangedEventArgs e)`**  
  Selects all text in a `TextBox` when it receives keyboard focus.

#### `LookupPopup`
- **`public event ChannelCodeSelectedEventHandler ChannelCodeSelected`**  
  Event raised when a channel code is selected (via double-click on a `DataGrid` item).
- **`public IList PossibleChannels { get; set; }`**  
  Dependency property backing the list of available channel codes.
- **`public delegate void ChannelCodeSelectedEventHandler(object sender, string code, string name)`**  
  Delegate for the `ChannelCodeSelected` event.
- **`private void PossibleChannels_OnMouseDoubleClick(object sender, MouseButtonEventArgs e)`**  
  Extracts `Code` and `Name` properties from the selected item and raises `ChannelCodeSelected`.

#### `TestIdPreFixSuffixHelper`
- **`public TestIdPreFixSuffix TestIdPreFixSuffix { get; }`**  
  Encapsulated prefix/suffix configuration.
- **`public override string ToString()`**  
  Returns localized string via `Strings.Strings.ResourceManager`, or the raw value if not found.

#### `AutoSizedGridView`
- **`protected override void PrepareItem(ListViewItem item)`**  
  Ensures columns with `Width="Auto"` (unbound) are correctly measured and re-measured when items are prepared. Handles re-binding of width-bound columns if binding is lost.

#### `TestIDTextBox`
- **`public string Text { get; set; }`**  
  Dependency property for the full test ID text value.
- **`public void Clear()`**  
  Clears the internal `tbTestId` text box.
- **`private static bool IsValidText(string text)`**  
  Validates text against invalid filename/path characters and the period (`.`) character.

#### `DynamicGrid`
- **`public byte GridColumns { get; set; }`**  
  Number of columns in the grid; changing this triggers a layout refresh.
- **`public void Refresh()`**  
  Recalculates column and row definitions and assigns children to grid cells in row-major order. Adds a final star-width column and row for expansion.

#### `TestIDViewModel`
- **`public string TestSetupLabel { get; set; }`**  
  Label for test setup; affects `TestSetupLabelVisibility`.
- **`public Visibility TestSetupLabelVisibility { get; }`**  
  `Visibility.Visible` if `TestSetupLabel` is non-empty, else `Collapsed`.
- **`public string TestIdEditableText { get; set; }`**  
  User-editable portion of the test ID.
- **`public void PopulateAllTestIdPrefixSuffixValues(string[] serializedValues)`**  
  Initializes list of available prefix/suffix options from DB values.
- **`public TestIdPreFixSuffixHelper[] AllTestIdPrefixSuffixValues { get; }`**  
  Read-only array of available prefix/suffix helpers.
- **`public TestIdPreFixSuffixHelper SelectedTestIdPrefixValueItem { get; set; }`**  
  Currently selected prefix helper (default: `None`).
- **`public TestIdPreFixSuffixHelper SelectedTestIdSuffixValueItem { get; set; }`**  
  Currently selected suffix helper (default: `TimeStamp`).
- **`public string TestName { get; set; }`**  
  Test name used when prefix/suffix is `TestSetupName`.
- **`public string GetTestId()`**  
  Constructs test ID by concatenating prefix, test setup label, editable text, and suffix with underscores.
- **`private string GetRunTimeTestIdPrefixOrSuffix(TestIdPreFixSuffixHelper prefixOrSuffix)`**  
  Resolves runtime value for a prefix/suffix helper (e.g., timestamp or test name).
- **`public string GetTestIdTimestamp()`**  
  Returns current timestamp as `yyyy_MM_dd HH_mm`.

#### `TestIdControl`
- **`public string TestSetupLabel { get; set; }`**  
  Same as in `TestIDViewModel`.
- **`public Visibility TestSetupLabelVisibility { get; }`**  
  Same as in `TestIDViewModel`.
- **`public string TestIdEditableText { get; set; }`**  
  Same as in `TestIDViewModel`.
- **`public void PopulateAllTestIdPrefixSuffixValues(string[] serializedValues)`**  
  Same as in `TestIDViewModel`.
- **`public TestIdPreFixSuffixHelper[] AllTestIdPrefixSuffixValues { get; }`**  
  Same as in `TestIDViewModel`.
- **`public TestIdPreFixSuffixHelper SelectedTestIdPrefixValueItem { get; set; }`**  
  Same as in `TestIDViewModel`.
- **`public TestIdPreFixSuffixHelper SelectedTestIdSuffixValueItem { get; set; }`**  
  Same as in `TestIDViewModel`.
- **`public string TestName { get; set; }`**  
  Same as in `TestIDViewModel`.
- **`public string GetTestId()`**  
  Same as in `TestIDViewModel`.
- **`private string GetRunTimeTestIdPrefixOrSuffix(TestIdPreFixSuffixHelper prefixOrSuffix)`**  
  Same as in `TestIDViewModel`.
- **`public string GetTestIdTimestamp()`**  
  Same as in `TestIDViewModel`.

#### `GridViewColumnHeaderSelectable`
- **`public string ListviewId { get; set; }`**  
  Identifier for the associated `ListView`.
- **`public string HeaderTitle { get; set; }`**  
  Display title for the header.
- **`public bool ToggleButtonIsChecked { get; set; }`**  
  Controls popup state; raises `OpenChanged` event on change.
- **`public event RoutedEventHandler OpenChanged`**  
  Raised when popup state changes.
- **`public event RoutedEventHandler ClickHandler`**  
  Raised on header click.
- **`public event RoutedEventHandler SelectAll`**  
  Raised when "Select All" or "Clear All" buttons are clicked.

#### `IPTextBox`
- **`public string Address { get; set; }`**  
  Dependency property for full IP address string (e.g., `"192.168.1.1"`).
- **`public void Clear()`**  
  Clears all four internal `TextBox` segments.

#### `GridViewColumnHeaderSearchable`
- **`public string ListviewId { get; set; }`**  
  Identifier for the associated `ListView`.
- **`public string HeaderTitle { get; set; }`**  
  Display title for the header.
- **`public bool ToggleButtonIsChecked { get; set; }`**  
  Controls popup state; raises `OpenChanged` event on change.
- **`public string HeaderSearchTerm { get; set; }`**  
  Current search term; raises `Search` event on change.
- **`public Geometry ToggleIconGeometry { get; }`**  
  Returns arrow or filter icon geometry based on search term presence.
- **`public event RoutedEventHandler OpenChanged`**  
  Raised when popup state changes.
- **`public event RoutedEventHandler Search`**  
  Raised when search term changes.

### Enums

#### `TestIdFixedPrefixSuffixValues`
- `NotFixed = -1`
- `None = 0`
- `TimeStamp = 1`
- `TestSetupName = 2`

## 3. Invariants

- **`GridLengthAnimation.GetCurrentValue`**:  
  The `GridUnitType` of the result is determined solely by the `To.IsStar` property; `From`'s unit type is ignored.
  
- **`IPTextBox` input validation**:  
  Only digits (0–9, including Numpad), period (`.`/`OemPeriod`/`Decimal`), navigation keys (Left/Right), Backspace, Tab, and Delete are allowed. Clipboard operations (Ctrl+C/V/A/X) are permitted.

- **`TestIDTextBox` text validation**:  
  Text must not contain any characters from `Path.GetInvalidFileNameChars()`, `Path.GetInvalidPathChars()`, or `.` (period).

- **`DynamicGrid.Refresh()`**:  
  - Columns are created with `Auto` width for all but the last column, which is `Star`.
  - Rows are created with `Auto` height for all but the last row, which is `Star`.
  - Children are assigned to grid cells in row-major order.

- **`ISOPopup` key filtering**:  
  Only alphanumeric keys (A–Z, 0–9), Numpad digits (NumPad0–NumPad9), control keys (Enter, Tab, Backspace, Delete, Home, End), and `OemQuestion` are allowed.

- **`TestIdPreFixSuffixHelper.ToString()`**:  
  Returns a localized string if available (via `Strings.Strings.ResourceManager`), otherwise returns the raw internal string.

## 4. Dependencies

### Dependencies *on* this module:
- **`DTS.Common.Events`**: Used by `checkbox` (for `HelpTextEvent`), `GridViewColumnHeaderSelectable`, and `GridViewColumnHeaderSearchable` (for `ListViewStatusEvent`).
- **`Prism.Ioc` / `Prism.Events`**: Used by `checkbox`, `GridViewColumnHeaderSelectable`, and `GridViewColumnHeaderSearchable` (for `IEventAggregator` and `ContainerLocator`).
- **`DTS.Common.Interface.Channels.ChannelCodes`**: Used by `LookupPopup` (for `IChannelCode`).
- **`DTS.Common.Base`**: Used by `GridViewColumnHeaderSelectable` and `GridViewColumnHeaderSearchable` (for `IBasePropertyChanged`).
- **`DTS.Common.Utilities.Logging`**: Used by `GridViewColumnHeaderSelectable` and `GridViewColumnHeaderSearchable` (for logging utilities).
- **`DTS.Common`**: Used by `TestIdPreFixSuffixHelper` (for `Base.BasePropertyChanged`).

### Dependencies *of* this module:
- **WPF Framework**: `System.Windows`, `System.Windows.Controls`, `System.Windows.Media`, `System.Windows.Media.Animation`, `System.Windows.Input`, `System.Windows.Shapes`, `System.Windows.Navigation`, `System.Windows.Data`, `System.Windows.Controls.Primitives`.
- **Prism Library**: `Prism.Ioc`, `Prism.Events`.
- **.NET Base Libraries**: `System`, `System.Collections.Generic`, `System.ComponentModel`, `System.IO`, `System.Linq`, `System.Threading.Tasks`.

## 5. Gotchas

- **`RoundedBox.Connect` is unimplemented**: The method throws `NotImplementedException`; callers must not invoke it.
- **`BoolToInvertedBoolConverter.ConvertBack` is not implemented**: Throwing `NotImplementedException` if used in two-way bindings.
- **`TestIdControl` is deprecated**: The class summary explicitly states: *"Remove this control after deleting the TTS module and migrating to new test setup wizard"*.
- **`TestIDTextBox` and `IPTextBox` share similar validation logic**: Both validate against invalid path/filename characters, but `TestIDTextBox` additionally forbids `.` while `IPTextBox` requires it.
- **`DynamicGrid.Refresh()` behavior**:  
  - The last column is always `Star` width, and the last row is always `Star` height, regardless of content.
  - If `GridColumns` is set to 0, `Refresh()` will create no columns, potentially breaking layout.
- **`GridViewColumnHeaderSelectable`/`Searchable` event subscription**:  
  Both subscribe to `ListViewStatusEvent` in their constructor. If `ListviewId` is not set correctly, the event handler may not clear search terms on `ListView` unload.
- **`TestIdPreFixSuffixHelper` equality semantics**:  
  `Equals()` returns `base.Equals()` if `FixedValue != NotFixed`, but compares string representations only if `FixedValue == NotFixed`. This may lead to unexpected equality results for non-`NotFixed` values.
- **`TestIDViewModel`/`TestIdControl` timestamp format**:  
  `GetTestIdTimestamp()` uses space (` `) as separator between date and time (`yyyy_MM_dd HH_mm`), which may cause issues in file system contexts.
- **`LookupPopup` reflection usage**:  
  `PossibleChannels_OnMouseDoubleClick` uses reflection (`GetProperty("Code")?.GetValue(...)`) to extract `Code`/`Name` from items; this assumes all items have these properties and may fail silently if they do not.