init
This commit is contained in:
245
docs/ai/Common/DTS.CommonCore/Controls.md
Normal file
245
docs/ai/Common/DTS.CommonCore/Controls.md
Normal file
@@ -0,0 +1,245 @@
|
||||
---
|
||||
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-17T15:28:35.741418+00:00"
|
||||
model: "zai-org/GLM-5-FP8"
|
||||
schema_version: 1
|
||||
sha256: "7d23a26eb40cb4f6"
|
||||
---
|
||||
|
||||
# DTS.Common.Controls Documentation
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This module provides a collection of custom WPF controls and helper classes for the DTS application framework. It includes specialized controls for test ID generation and display, animated grid layouts, data grid enhancements with searchable/selectable column headers, popup dialogs for ISO input and channel code lookup, and utility classes for managing test ID prefixes and suffixes. The controls integrate with the Prism event aggregation system and support MVVM patterns through `INotifyPropertyChanged` implementations.
|
||||
|
||||
---
|
||||
|
||||
## 2. Public Interface
|
||||
|
||||
### Classes
|
||||
|
||||
#### `RoundedBox`
|
||||
A simple `UserControl` wrapper.
|
||||
- `RoundedBox()` — Default constructor, calls `InitializeComponent()`.
|
||||
- `void Connect(int connectionId, object target)` — Empty implementation (comment indicates `NotImplementedException` was considered but disabled).
|
||||
|
||||
---
|
||||
|
||||
#### `TestIDView`
|
||||
A minimal `UserControl` for test ID display.
|
||||
- `TestIDView()` — Default constructor, calls `InitializeComponent()`.
|
||||
|
||||
---
|
||||
|
||||
#### `checkbox`
|
||||
A partial class handling tooltip events via event aggregation.
|
||||
- `void ToolTipEventHandler(object sender, ToolTipEventArgs e)` — Marks event as handled, retrieves `IEventAggregator` via `ServiceLocator.Current`, and publishes a `HelpTextEvent` with a `HelpTextEventArg` containing the sender and event args.
|
||||
|
||||
---
|
||||
|
||||
#### `GridLengthAnimation`
|
||||
An `AnimationTimeline` subclass for animating `GridLength` values.
|
||||
- `GridLengthAnimation()` — Default constructor (no-op).
|
||||
- `GridLength From` / `GridLength To` — Dependency properties defining animation range.
|
||||
- `Type TargetPropertyType` — Returns `typeof(GridLength)`.
|
||||
- `object GetCurrentValue(object defaultOriginValue, object defaultDestinationValue, AnimationClock animationClock)` — Interpolates between `From` and `To` values based on `animationClock.CurrentProgress`. Preserves `GridUnitType.Star` or `GridUnitType.Pixel` from the `To` value.
|
||||
- `Freezable CreateInstanceCore()` — Returns a new `GridLengthAnimation` instance.
|
||||
|
||||
---
|
||||
|
||||
#### `ISOPopup`
|
||||
A `Popup` subclass for ISO-related text input with input validation.
|
||||
- `ISOPopup()` — Default constructor, calls `InitializeComponent()`.
|
||||
- `void ISOPart_OnPreviewKeyUp(object sender, KeyEventArgs e)` — Filters keyboard input to allow only: letters (A-Z), numbers (0-9, NumPad0-9), control keys (Enter, Return, Tab, OemBackTab, Delete, Back, Home, End), and OemQuestion. Sets `e.Handled` to block disallowed keys.
|
||||
- `void ISOPart_OnGotMouseCapture(object sender, MouseEventArgs e)` — Selects all text in the `TextBox` sender.
|
||||
- `void ISOPart_OnGotKeyboardFocus(object sender, KeyboardFocusChangedEventArgs e)` — Selects all text in the `TextBox` sender.
|
||||
|
||||
---
|
||||
|
||||
#### `LookupPopup`
|
||||
A `Popup` for selecting channel codes from a list.
|
||||
- `IEnumerable<IChannelCode> AllChannelCodes` — Public property (getter only, private setter).
|
||||
- `LookupPopup()` — Default constructor, calls `InitializeComponent()`.
|
||||
- `delegate void ChannelCodeSelectedEventHandler(object sender, string code, string name)` — Event signature.
|
||||
- `event ChannelCodeSelectedEventHandler ChannelCodeSelected` — Raised when a channel code is double-clicked.
|
||||
- `IList PossibleChannels` — Dependency property for the list of selectable channels; defaults to an empty list of anonymous objects with `Code` and `Name` properties.
|
||||
- `void PossibleChannels_OnMouseDoubleClick(object sender, MouseButtonEventArgs e)` — Raises `ChannelCodeSelected` with `Code` and `Name` extracted via reflection from the selected item.
|
||||
|
||||
---
|
||||
|
||||
#### `TestIdPreFixSuffixHelper` and Related Types
|
||||
|
||||
**Enum `TestIdFixedPrefixSuffixValues`**
|
||||
- `NotFixed = -1`
|
||||
- `None = 0`
|
||||
- `TimeStamp = 1`
|
||||
- `TestSetupName = 2`
|
||||
|
||||
**Class `TestIdPreFixSuffix`**
|
||||
- `TestIdFixedPrefixSuffixValues FixedValue` — Read-only property, defaults to `NotFixed`.
|
||||
- `TestIdPreFixSuffix(TestIdFixedPrefixSuffixValues fixedPrefixSuffix)` — Constructor that sets `FixedValue` and creates internal string `"TESTID_PREFIX_SUFFIX_" + fixedPrefixSuffix`.
|
||||
- `TestIdPreFixSuffix(string dbPrefixSuffix)` — Constructor that stores the string directly.
|
||||
- `string ToString()` — Returns the internal string.
|
||||
|
||||
**Class `TestIdPreFixSuffixHelper` (extends `Base.BasePropertyChanged`)**
|
||||
- `TestIdPreFixSuffix TestIdPreFixSuffix` — Read-only property.
|
||||
- `TestIdPreFixSuffixHelper(string testIdPreFixSuffix)` — Constructs with a string value.
|
||||
- `TestIdPreFixSuffixHelper(TestIdFixedPrefixSuffixValues testIdPreFixSuffix)` — Constructs with an enum value.
|
||||
- `string ToString()` — Returns localized string from `Strings.Strings.ResourceManager` if available, otherwise the raw string.
|
||||
- `bool Equals(object obj)` — Compares `FixedValue` and, if `NotFixed`, compares string values.
|
||||
|
||||
---
|
||||
|
||||
#### `AutoSizedGridView`
|
||||
A `GridView` subclass that auto-sizes columns on item preparation.
|
||||
- `void PrepareItem(ListViewItem item)` — Override that tracks columns by hash code, identifies auto-width columns (`double.IsNaN(Width)` with no binding), and forces re-measurement. Also re-binds width bindings if lost.
|
||||
|
||||
---
|
||||
|
||||
#### `DynamicGrid`
|
||||
A `Grid` subclass implementing `INotifyPropertyChanged` that auto-arranges children.
|
||||
- `event PropertyChangedEventHandler PropertyChanged`
|
||||
- `DynamicGrid()` — Constructor, calls `Refresh()`.
|
||||
- `byte GridColumns` — Property (default 2); setter calls `Refresh()`.
|
||||
- `void Refresh()` — Clears and rebuilds `ColumnDefinitions` and `RowDefinitions`, arranges children left-to-right, top-to-bottom. Last column is `Star`-sized; others are `Auto`. Adds a final `Star`-height row.
|
||||
- `void OnVisualChildrenChanged(DependencyObject visualAdded, DependencyObject visualRemoved)` — Override that calls `Refresh()`.
|
||||
|
||||
---
|
||||
|
||||
#### `TestIDViewModel`
|
||||
A view model for test ID generation.
|
||||
- `event PropertyChangedEventHandler PropertyChanged`
|
||||
- `string TestSetupLabel` — Property; setter raises `PropertyChanged` for itself and `TestSetupLabelVisibility`.
|
||||
- `Visibility TestSetupLabelVisibility` — Returns `Collapsed` if label is empty, otherwise `Visible`.
|
||||
- `string TestIdEditableText` — Property, default `string.Empty`.
|
||||
- `string TestName` — Property.
|
||||
- `TestIdPreFixSuffixHelper SelectedTestIdPrefixValueItem` — Default `TEST_ID_SUFFIX_VALUE_NONE_ITEM`.
|
||||
- `TestIdPreFixSuffixHelper SelectedTestIdSuffixValueItem` — Default `TEST_ID_SUFFIX_VALUE_TIME_STAMP_ITEM`.
|
||||
- `void PopulateAllTestIdPrefixSuffixValues(string[] serializedValues)` — Populates `AllTestIdPrefixSuffixValues` with built-in items (None, TimeStamp, TestSetupName) plus database values.
|
||||
- `TestIdPreFixSuffixHelper[] AllTestIdPrefixSuffixValues` — Returns array of available prefix/suffix options.
|
||||
- `string GetTestId()` — Builds test ID by joining prefix, `TestSetupLabel`, `TestIdEditableText`, and suffix with underscores.
|
||||
- `string GetTestIdTimestamp()` — Returns formatted timestamp: `"YYYY_MM_DD HH_MM"`.
|
||||
|
||||
---
|
||||
|
||||
#### `TestIdControl`
|
||||
A `UserControl` implementing test ID generation (marked for removal).
|
||||
- Same public interface as `TestIDViewModel` (properties, methods).
|
||||
- `TestIdControl()` — Constructor, calls `InitializeComponent()`.
|
||||
- **Note:** Comment indicates this control should be removed after TTS module deletion and migration to new test setup wizard.
|
||||
|
||||
---
|
||||
|
||||
#### `GridViewColumnHeaderSelectable`
|
||||
A `UserControl` for column headers with selection popup.
|
||||
- `event PropertyChangedEventHandler PropertyChanged`
|
||||
- `GridViewColumnHeaderSelectable()` — Constructor, subscribes to `ListViewStatusEvent` via `IEventAggregator`.
|
||||
- `string ListviewId` — Dependency property.
|
||||
- `string HeaderTitle` — Dependency property, default `"Awesome"`.
|
||||
- `bool ToggleButtonIsChecked` — Controls popup state; raises `OpenChanged` event.
|
||||
- `Geometry ToggleIconGeometry` — Not fully implemented in code-behind (getter references `dtsGridViewColumnHeader` resource lookup, but no field declaration visible).
|
||||
- `event RoutedEventHandler OpenChanged` — Bubbling routed event.
|
||||
- `event RoutedEventHandler ClickHandler` — Bubbling routed event.
|
||||
- `event RoutedEventHandler SelectAll` — Bubbling routed event; raised by Select All/Clear All buttons.
|
||||
- `string ToString()` — Returns `HeaderTitle`.
|
||||
|
||||
---
|
||||
|
||||
#### `GridViewColumnHeaderSearchable`
|
||||
A `UserControl` for column headers with search functionality.
|
||||
- `event PropertyChangedEventHandler PropertyChanged`
|
||||
- `GridViewColumnHeaderSearchable()` — Constructor, subscribes to `ListViewStatusEvent`.
|
||||
- `string ListviewId` — Dependency property.
|
||||
- `string HeaderTitle` — Dependency property, default `"Awesome"`.
|
||||
- `string HeaderSearchTerm` — Dependency property; changes raise `Search` event.
|
||||
- `bool ToggleButtonIsChecked` — Controls popup state.
|
||||
- `Geometry ToggleIconGeometry` — Returns `DownArrowIconGeometry` or `FilterIconGeometry` based on whether `HeaderSearchTerm` is empty.
|
||||
- `event RoutedEventHandler OpenChanged` — Bubbling routed event.
|
||||
- `event RoutedEventHandler ClickHandler` — Bubbling routed event.
|
||||
- `event RoutedEventHandler Search` — Bubbling routed event.
|
||||
|
||||
**Class `BoolToInvertedBoolConverter`**
|
||||
- `object Convert(object value, ...)` — Returns inverted boolean.
|
||||
- `object ConvertBack(...)` — Throws `NotImplementedException`.
|
||||
|
||||
---
|
||||
|
||||
#### `GridViewColumnHeaderSearchableCheckBox`
|
||||
A `UserControl` for column headers with search and boolean filter options.
|
||||
- `event PropertyChangedEventHandler PropertyChanged`
|
||||
- `GridViewColumnHeaderSearchableCheckBox()` — Constructor, subscribes to `ListViewStatusEvent`.
|
||||
- `string ListviewId` — Dependency property.
|
||||
- `string HeaderTitle` — Dependency property, default `"Awesome"`.
|
||||
- `string HeaderSearchTerm` — Dependency property.
|
||||
- `bool ToggleButtonIsChecked` — Controls popup state.
|
||||
- `Geometry ToggleIconGeometry` — Returns icon based on search term state.
|
||||
- `event RoutedEventHandler OpenChanged` — Bubbling routed event.
|
||||
- `event RoutedEventHandler ClickHandler` — Bubbling routed event.
|
||||
- `event RoutedEventHandler Search` — Bubbling routed event (registered as `"SearchCheckBox"`).
|
||||
- `event RoutedEventHandler Filter` — Bubbling routed event; raised with `"All"`, `"True"`, or `"False"`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
- **GridLengthAnimation**: `animationClock.CurrentProgress` must have a value (no null check); calling `GetCurrentValue` when `CurrentProgress` is null will throw.
|
||||
- **ISOPopup**: The `ISOPart_OnPreviewKeyUp` handler only filters key input; paste operations are not explicitly handled.
|
||||
- **LookupPopup**: `PossibleChannels_OnMouseDoubleClick` uses reflection to access `Code` and `Name` properties; items in `PossibleChannels` must have these properties or `NullReferenceException` may occur.
|
||||
- **DynamicGrid**: `GridColumns` must be at least 1 for meaningful layout (0 would clear all columns).
|
||||
- **AutoSizedGridView**: Column tracking uses `GetHashCode()`; if column objects are replaced with equal-hash instances, the tracking may not update correctly.
|
||||
- **GridViewColumnHeaderSelectable/Searchable/SearchableCheckBox**: All require `ServiceLocator.Current` to return a valid `IEventAggregator` instance at construction time.
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
### External Dependencies (Imports)
|
||||
- `System.Windows.*` — WPF core assemblies (`Controls`, `Input`, `Data`, `Media`, `Media.Animation`, `Navigation`, `Shapes`, `Controls.Primitives`).
|
||||
- `Microsoft.Practices.ServiceLocation` — `ServiceLocator` for service location.
|
||||
- `Microsoft.Practices.Prism.Events` — `IEventAggregator`, `ThreadOption` for event aggregation.
|
||||
|
||||
### Internal Dependencies
|
||||
- `DTS.Common.Events` — `HelpTextEvent`, `HelpTextEventArg`, `ListViewStatusEvent`, `ListViewStatusArg`.
|
||||
- `DTS.Common.Interface.Channels.ChannelCodes` — `IChannelCode` interface.
|
||||
- `DTS.Common.Base` — `BasePropertyChanged`, `IBasePropertyChanged`.
|
||||
- `DTS.Common.Utilities.Logging` — Referenced but not directly used in visible code.
|
||||
- `Strings.Strings` — Resource manager for localization in `TestIdPreFixSuffixHelper`.
|
||||
|
||||
### Consumers
|
||||
- Unknown from source alone; these are reusable controls likely consumed by various modules in the DTS application.
|
||||
|
||||
---
|
||||
|
||||
## 5. Gotchas
|
||||
|
||||
1. **TestIdControl is deprecated**: The class has a comment indicating it should be removed after TTS module deletion. New code should use `TestIDViewModel` instead.
|
||||
|
||||
2. **Reflection-based property access in LookupPopup**: `PossibleChannels_OnMouseDoubleClick` uses `GetProperty("Code")` and `GetProperty("Name")` via reflection. This is fragile and will fail silently (returning null) or throw if properties don't exist.
|
||||
|
||||
3. **GridLengthAnimation null progress risk**: `GetCurrentValue` accesses `animationClock.CurrentProgress.Value` without null checking. If the animation clock hasn't started or progress is unavailable, this will throw `InvalidOperationException`.
|
||||
|
||||
4. **checkbox class naming**: The class `checkbox` violates C# naming conventions (should be PascalCase `Checkbox`). This may cause confusion or issues with XAML namespace mapping.
|
||||
|
||||
5. **RoundedBox.Connect is a stub**: The `Connect` method has a commented-out `NotImplementedException`. Its purpose is unclear—it may be an interface implementation requirement or leftover code.
|
||||
|
||||
6. **GridViewColumnHeaderSelectable.OnListviewStatusEvent has empty body**: When `arg.Id == ListviewId` and status is `Unloaded`, the if-block is empty. This appears to be incomplete implementation.
|
||||
|
||||
7. **Duplicate code between TestIDViewModel and TestIdControl**: These classes have nearly identical logic. This is technical debt from the migration mentioned in the deprecation comment.
|
||||
|
||||
8. **DynamicGrid adds extra row**: `Refresh()` always adds a final `Star`-height row definition even if no children exist, which may affect layout in unexpected ways.
|
||||
|
||||
9. **GridViewColumnHeaderSearchableCheckBox.Search event name mismatch**: The routed event is registered with name `"SearchCheckBox"` but the CLR event is named `Search`, which could cause confusion in XAML binding.
|
||||
Reference in New Issue
Block a user