--- 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 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).