DP44/enriched-qwen3-coder-next/DTS Viewer/DTS.Viewer.Modules/DTS.Viewer.GraphList/Classes.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DTS Viewer/DTS.Viewer.Modules/DTS.Viewer.GraphList/Classes/VirtualToggleButton.cs	2026-04-16T13:48:16.790928+00:00	zai-org/GLM-5-FP8	1	001b39a3411ec3ba

Documentation: VirtualToggleButton

1. Purpose

VirtualToggleButton is a static helper class that provides attached dependency properties to imbue any WPF element with toggle button behavior. Rather than requiring inheritance from ToggleButton, this module allows arbitrary DependencyObject instances (specifically those implementing IInputElement) to respond to mouse clicks and keyboard input (Space/Enter) by toggling between checked, unchecked, and optionally indeterminate states. This is used within the DTS.Viewer.GraphList module to create toggle-style interactions on elements that cannot directly inherit from ToggleButton.

---

2. Public Interface

Attached Properties

IsLockedProperty

• Type: DependencyProperty (attached)
• Value Type: Nullable<bool>
• Default Value: false
• Metadata Flags: BindsTwoWayByDefault | Journal
• Get Accessor: Nullable<bool> GetIsLocked(DependencyObject d)
• Set Accessor: void SetIsLocked(DependencyObject d, Nullable<bool> value)
• Behavior: Represents the toggle state. When changed, raises ToggleButton.CheckedEvent (if true), ToggleButton.UncheckedEvent (if false), or ToggleButton.IndeterminateEvent (if null).

IsThreeStateProperty

• Type: DependencyProperty (attached)
• Value Type: bool
• Default Value: false
• Get Accessor: bool GetIsThreeState(DependencyObject d)
• Set Accessor: void SetIsThreeState(DependencyObject d, bool value)
• Behavior: When true, allows IsLocked to cycle through null (indeterminate) state during toggle operations.

IsVirtualToggleButtonProperty

• Type: DependencyProperty (attached)
• Value Type: bool
• Default Value: false
• Get Accessor: bool GetIsVirtualToggleButton(DependencyObject d)
• Set Accessor: void SetIsVirtualToggleButton(DependencyObject d, bool value)
• Behavior: When set to true on an IInputElement, subscribes OnMouseLeftButtonDown and OnKeyDown handlers. When set to false, unsubscribes them.

Internal Methods

RaiseCheckedEvent(UIElement target)

• Returns: RoutedEventArgs or null if target is null
• Behavior: Raises ToggleButton.CheckedEvent on the target element.

RaiseUncheckedEvent(UIElement target)

• Returns: RoutedEventArgs or null if target is null
• Behavior: Raises ToggleButton.UncheckedEvent on the target element.

RaiseIndeterminateEvent(UIElement target)

• Returns: RoutedEventArgs or null if target is null
• Behavior: Raises ToggleButton.IndeterminateEvent on the target element.

---

3. Invariants

1. Input Handler Attachment: Setting IsVirtualToggleButton to true on a non-IInputElement has no effect (handlers are not attached, no exception is thrown).

2. Toggle State Cycling Logic (in UpdateIsLocked):

   • If IsLocked == true: Sets to false, or null if IsThreeState is true.
   • If IsLocked == false or null: Sets to true.

3. Keyboard Handling:

   • Space key toggles the state, unless Alt modifier is present (system menu invocation is preserved).
   • Enter key toggles the state only if KeyboardNavigation.AcceptsReturnProperty is true on the sender.

4. Event Routing: Raised events use ToggleButton.CheckedEvent, ToggleButton.UncheckedEvent, and ToggleButton.IndeterminateEvent as routed event identifiers.

---

4. Dependencies

This Module Depends On:

• System
• System.Windows (DependencyObject, DependencyProperty, FrameworkPropertyMetadata, UIElement, ContentElement, RoutedEventArgs, IInputElement)
• System.Windows.Controls.Primitives (ToggleButton)
• System.Windows.Input (Key, KeyEventArgs, Keyboard, KeyboardNavigation, ModifierKeys, MouseButtonEventArgs)

Consumers:

• Unclear from source alone. The class is in DTS.Viewer.GraphList namespace, suggesting consumption by GraphList-related components.

---

5. Gotchas

1. Misleading XML Documentation: The XML comments for IsLocked state "indicates whether the toggle button is checked" — this appears to be copy-pasted from a standard IsChecked property. The property name IsLocked suggests a different semantic meaning (possibly "locked/selected" in the context of graph items).

2. Type Inconsistency in Event Raising: The private RaiseEvent method supports both UIElement and ContentElement, but the internal RaiseCheckedEvent, RaiseUncheckedEvent, and RaiseIndeterminateEvent methods only accept UIElement. If a ContentElement needs these events raised, the internal methods cannot be used directly.

3. Namespace Suppression: The file contains // ReSharper disable CheckNamespace, indicating the namespace DTS.Viewer.GraphList may not match the project's default namespace structure. This could indicate a refactoring artifact or intentional namespace override.

4. No Null Guard in UpdateIsLocked: The method casts sender as DependencyObject without null-checking before calling GetIsLocked(d). If called with a non-DependencyObject sender, this would pass null to GetIsLocked, which would throw a NullReferenceException inside d.GetValue().

5. Event Handled Flag: Both OnMouseLeftButtonDown and OnKeyDown mark events as e.Handled = true, which may prevent bubbling to parent handlers unexpectedly.