init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Classes/ChannelCodes.md

@@ -0,0 +1,166 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Classes/ChannelCodes/TextPastedArgs.cs
+  - Common/DTS.CommonCore/Classes/ChannelCodes/ChannelCode.cs
+generated_at: "2026-04-16T02:39:51.595748+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "9a72b7f2cc9cf8aa"
+---
+
+# ChannelCodes
+
+## Documentation: ChannelCode Module
+
+---
+
+### 1. Purpose
+
+This module provides core data and command infrastructure for handling *channel codes*—named identifiers (e.g., ISO or user-defined codes) used to categorize or label channels in the system. It defines the `ChannelCode` class as the canonical implementation of `IChannelCode`, including persistence support via `IDataReader`, equality semantics, and property change notification. It also defines `PasteCommandClass`, a `ICommand` implementation that intercepts text paste operations in UI text boxes, processes clipboard content (including multi-line or delimited data), and publishes structured `TextPastedArgs` events for downstream handling—while suppressing default paste behavior to enable custom logic.
+
+---
+
+### 2. Public Interface
+
+#### `class ChannelCode : BasePropertyChanged, IChannelCode`
+
+- **`int Id { get; set; }`**  
+  Unique numeric identifier for the channel code. Initialized to `-1` by default.
+
+- **`UIItemStatus ItemStatus { get; set; }`**  
+  Status of the item (e.g., `None`, `New`, `Modified`, `Deleted`). Uses `SetProperty` for change notification.
+
+- **`string Code { get; protected set; }`**  
+  The code string (e.g., `"A1"`, `"ISO-8601"`). Protected setter allows subclassing.
+
+- **`string Name { get; protected set; }`**  
+  Human-readable name for the channel code (e.g., `"Temperature Sensor"`).
+
+- **`ChannelEnumsAndConstants.ChannelCodeType CodeType { get; set; }`**  
+  Enumerated type of the code: `User` or `ISO`. Default is `ISO` in parameterless constructor.
+
+- **`const string PASTE_ID = "ChannelCode"`**  
+  Static identifier used to correlate paste operations with this channel code type.
+
+- **`ICommand PasteCommand { get; set; } = null`**  
+  Command bound to text boxes to handle paste operations. Defaults to `null` to avoid exceptions during UI construction.
+
+- **`ChannelCode(IDataReader reader, IReadOnlyDictionary<short, string> channelTypeLookup)`**  
+  Constructor that initializes the instance from a database record. Reads `Id`, `Code`, `Name`, and `CodeTypeInt` columns. Uses `channelTypeLookup` to map `CodeTypeInt` to `ChannelCodeType` (`User` or `ISO`) via string keys (`"User"` / `"ISO"`).
+
+- **`ChannelCode()`**  
+  Parameterless constructor. Sets `CodeType` to `ISO`.
+
+- **`ChannelCode(IChannelCode channelCode)`**  
+  Copy constructor. Copies `Id`, `Code`, `Name`, and `CodeType` from another `IChannelCode`.
+
+- **`override bool Equals(object obj)`**  
+  Equality comparison based on `Code`, `Name`, and `CodeType`. Returns `false` if `obj` is not a `ChannelCode`.
+
+- **`~ChannelCode()`**  
+  Finalizer that nulls `_code` and `_name` to reduce memory footprint if the object is held longer than expected.
+
+#### `class PasteCommandClass : ICommand`
+
+- **`string Id { get; }`**  
+  Identifier passed at construction; used to tag paste events.
+
+- **`bool CanExecute(object parameter)`**  
+  Always returns `true`.
+
+- **`void Execute(object parameter)`**  
+  Handles paste logic:
+  - Requires `parameter` to be a `TextBox`.
+  - Attempts to resolve `IChannelCode` from `TextBox.DataContext`, with fallbacks to `ChannelCodeBuilder` or `ChannelNameBuilder` view models.
+  - Reads clipboard text.
+  - If clipboard contains **exactly one line** and **no delimiters** (`,`, `;`, `\t`), publishes a `PageModifiedEvent` and exits early (single-field paste is handled by `TextChanged`).
+  - Otherwise:
+    - Resets `Code` and `Name` properties (no-op assignment to trigger change notifications).
+    - Publishes a `TextPastedEvent` with a `TextPastedArgs` instance containing:
+      - `Text`: full clipboard content
+      - `Sender`: resolved `IChannelCode`
+      - `Id`: `PasteCommandClass.Id`
+      - `Tag`: `TextBox.Tag`
+  - Catches and reports exceptions via `PageErrorEvent`.
+
+- **`PasteCommandClass(string id)`**  
+  Constructor storing `id` in `Id` property.
+
+#### `delegate string CoerceISOCodeDelegate(...)`
+
+- **`string CoerceISOCodeDelegate(string val, bool uniqueISOCodesRequired, bool useISOCodeFilterMapping)`**  
+  Signature for a delegate used to transform or validate incoming ISO codes. Not implemented in this file—only declared.
+
+---
+
+### 3. Invariants
+
+- **`ChannelCode.Code` and `ChannelCode.Name` must be non-null**  
+  Initialized to `string.Empty` and never set to `null` (via `SetProperty` and constructor defaults).
+
+- **`ChannelCode.Id` defaults to `-1`**  
+  A value of `-1` indicates the code has not been persisted or assigned.
+
+- **`ChannelCode.CodeType` defaults to `ISO`**  
+  Unless explicitly set otherwise (e.g., via constructor with `IDataReader` or copy constructor).
+
+- **Equality is based on `Code`, `Name`, and `CodeType`**  
+  `Id` is *not* part of equality semantics.
+
+- **Paste command only processes `TextBox` parameters**  
+  Non-`TextBox` inputs are silently ignored.
+
+- **Clipboard text is split by `Environment.NewLine`**  
+  Only single-line, non-delimited text bypasses `TextPastedEvent`; all other cases trigger it.
+
+---
+
+### 4. Dependencies
+
+#### *This module depends on:*
+- **`DTS.Common.Base`**  
+  Provides `BasePropertyChanged` (base class for `ChannelCode`).
+- **`DTS.Common.Interface.Channels.ChannelCodes`**  
+  Defines `IChannelCode` interface.
+- **`DTS.Common.Enums`**  
+  Provides `UIItemStatus`, `ChannelEnumsAndConstants` (enum `ChannelCodeType`, string constants `"User"`, `"ISO"`).
+- **`DTS.Common.Events`**  
+  Defines `PageModifiedEvent`, `TextPastedEvent`, `PageErrorEvent`, and argument types (`PageModifiedArg`, `TextPastedArgs`, `PageErrorArg`).
+- **`System.Data`**  
+  For `IDataReader`.
+- **`System.Windows` / `System.Windows.Controls` / `System.Windows.Input`**  
+  For `UIElement`, `TextBox`, `ICommand`.
+- **`Microsoft.Practices.Prism.Events`**  
+  For `IEventAggregator`.
+- **`Microsoft.Practices.ServiceLocation`**  
+  For `ServiceLocator`.
+
+#### *This module is depended on by:*
+- Any UI layer components that bind `ChannelCode` instances to views (e.g., `ChannelCodeBuilder`, `ChannelNameBuilder`).
+- Event handlers subscribed to `TextPastedEvent`.
+- Code that constructs `ChannelCode` instances from database readers or clones them.
+
+---
+
+### 5. Gotchas
+
+- **`PasteCommand` defaults to `null`**  
+  To avoid exceptions during UI construction (per inline comment: *"putting a null here avoids wasteful exception"*). Consumers must explicitly assign a `PasteCommandClass` instance.
+
+- **`ChannelCode.Equals` ignores `Id`**  
+  Two codes with different IDs but identical `Code`, `Name`, and `CodeType` are considered equal. This may cause issues if IDs are expected to be unique in comparisons.
+
+- **`~ChannelCode()` finalizer nulls fields but does not prevent GC of the object**  
+  This is a cleanup heuristic, not a disposal pattern. No `IDisposable` implementation is present.
+
+- **Single-line paste with delimiters still triggers `TextPastedEvent`**  
+  Only *single-line, no-delimiter* text skips the event; multi-line or single-line with `,`, `;`, or `\t` always publish `TextPastedArgs`.
+
+- **`PasteCommand.Execute` silently ignores invalid contexts**  
+  If `parameter` is not a `TextBox`, or `DataContext` is not an `IChannelCode`/builder, the method returns without error or logging (except via `PageErrorEvent` on exception).
+
+- **`CoerceISOCodeDelegate` is declared but not implemented here**  
+  Its purpose is documented, but no concrete implementation is provided in this module.
+
+- **`ChannelCode` constructor with `IDataReader` relies on column names and lookup dictionary**  
+  If `channelTypeLookup` lacks the key from `CodeTypeInt`, or columns are missing, behavior is undefined (no explicit validation is present).