init

docs/ai/Common/DTS.Common/Behaviors.md

@@ -0,0 +1,120 @@
+---
+source_files:
+  - Common/DTS.Common/Behaviors/StringMetaDataAttr.cs
+  - Common/DTS.Common/Behaviors/TrimTextBoxBehavior.cs
+  - Common/DTS.Common/Behaviors/InteractivityTemplate.cs
+  - Common/DTS.Common/Behaviors/TextBoxPasteBehavior.cs
+  - Common/DTS.Common/Behaviors/MultiSelectionBehavior.cs
+generated_at: "2026-04-17T15:36:03.026612+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "36e847a660d89b00"
+---
+
+# DTS.Common.Behaviors Namespace Documentation
+
+## 1. Purpose
+
+This module provides a collection of WPF behaviors and utilities for the DTS application. It includes: `StringMetaDataAttr` for attaching string metadata to enums and objects via reflection; `TrimTextBoxBehavior` for automatically trimming whitespace from TextBox input on focus loss; `InteractivityTemplate` and `InteractivityItems` for attaching behaviors and triggers via data templates (enabling MVVM-friendly dynamic interactivity); `TextBoxPasteBehavior` for intercepting paste operations and routing them through custom ICommand implementations; and `MultiSelectionBehavior` for two-way synchronization between a ListBox's selected items and a bound collection, with special optimizations for bulk operations on specific collection types.
+
+---
+
+## 2. Public Interface
+
+### StringMetaDataAttr
+
+```csharp
+public class StringMetaDataAttr : Attribute
+{
+    public string MetaData { get; }
+    internal StringMetaDataAttr(string attr);
+    public static string GetStringMetaData(object o);
+}
+```
+
+- **`MetaData`** property: Read-only string containing the metadata value.
+- **`StringMetaDataAttr(string attr)`**: Constructor marked `internal`; cannot be instantiated from outside the assembly.
+- **`GetStringMetaData(object o)`**: Static method that retrieves the `MetaData` value from a `StringMetaDataAttr` applied to the member represented by `o`. Returns `null` if the object is null, has no matching member, or lacks the attribute.
+
+---
+
+### TrimTextBoxBehavior
+
+```csharp
+public class TrimTextBoxBehavior : Behavior<TextBox>
+{
+    protected override void OnAttached();
+    protected override void OnDetaching();
+}
+```
+
+- **`OnAttached()`**: Subscribes to `AssociatedObject.LostFocus`.
+- **`OnDetaching()`**: Unsubscribes from `AssociatedObject.LostFocus`.
+- Behavior trims whitespace from `AssociatedObject.Text` on focus loss and calls `UpdateSource()` on the `TextBox.TextProperty` binding expression if the text changed.
+
+---
+
+### InteractivityTemplate
+
+```csharp
+public class InteractivityTemplate : DataTemplate
+{
+}
+```
+
+- Empty class inheriting from `DataTemplate`. Serves as a marker/template type for interactivity.
+
+### InteractivityItems
+
+```csharp
+public class InteractivityItems : FrameworkElement
+{
+    public List<TriggerBase> Triggers { get; }
+    public List<Behavior> Behaviors { get; }
+    
+    public static InteractivityTemplate GetTemplate(DependencyObject obj);
+    public static void SetTemplate(DependencyObject obj, InteractivityTemplate value);
+    public static readonly DependencyProperty TemplateProperty;
+}
+```
+
+- **`Triggers`**: Lazily-initialized list of `TriggerBase` objects.
+- **`Behaviors`**: Lazily-initialized list of `Behavior` objects.
+- **`GetTemplate(DependencyObject obj)`**: Gets the attached `InteractivityTemplate`.
+- **`SetTemplate(DependencyObject obj, InteractivityTemplate value)`**: Sets the attached `InteractivityTemplate`.
+- **`TemplateProperty`**: Attached property. When changed, loads the template content, casts to `InteractivityItems`, and copies all behaviors and triggers to the target element via `Interaction.GetBehaviors()` and `Interaction.GetTriggers()`.
+
+---
+
+### TextBoxPasteBehavior
+
+```csharp
+public class TextBoxPasteBehavior
+{
+    public static readonly DependencyProperty PasteCommandProperty;
+    
+    public static ICommand GetPasteCommand(DependencyObject target);
+    public static void SetPasteCommand(DependencyObject target, ICommand value);
+}
+```
+
+- **`PasteCommandProperty`**: Attached property of type `ICommand`.
+- **`GetPasteCommand(DependencyObject target)`**: Returns the attached `ICommand`.
+- **`SetPasteCommand(DependencyObject target, ICommand value)`**: Sets the attached `ICommand`. When set, registers or unregisters a handler for `CommandManager.ExecutedEvent` on the target.
+- Internal handler `CommandExecuted` checks if the command is `ApplicationCommands.Paste` or a `RoutedUICommand` with name "Paste". If so, retrieves clipboard text via `Clipboard.GetText()`, executes the attached command (passing the TextBox as parameter), and marks the event handled.
+
+---
+
+### MultiSelectionBehavior
+
+```csharp
+public class MultiSelectionBehavior : Behavior<ListBox>
+{
+    public IList SelectedItems { get; set; }
+    public static readonly DependencyProperty SelectedItemsProperty;
+    
+    protected override void OnAttached();
+}
+```
+
+- **`SelectedItems`**: Dependency property of type `IList`.