DP44/enriched-qwen3-coder-next/DataPRO/DataPRO.Core/Settings.md

---
source_files:
  - DataPRO/DataPRO.Core/Settings/SettingsChangedEventArgs.cs
  - DataPRO/DataPRO.Core/Settings/SettingsCollection.cs
generated_at: "2026-04-16T04:27:33.942396+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "d5502ead5db3d623"
---

# `SettingsCollection<TKey, TItem>` Module Documentation

---

## 1. Purpose

The `SettingsCollection<TKey, TItem>` class provides a dictionary-based collection that notifies subscribers of changes (add, remove, modify, clear) via the `CollectionItemPropertyChanged` event. It extends `IDictionary<TKey, TItem>` to offer standard dictionary operations while adding reactive behavior for UI binding or state synchronization scenarios. This module exists to decouple state mutation from side-effect logic (e.g., persistence, UI updates) by enabling consumers to subscribe to change events rather than manually tracking mutations.

---

## 2. Public Interface

### `SettingsCollection<TKey, TItem> : IDictionary<TKey, TItem>`

#### Event

- **`CollectionItemPropertyChanged`**  
  `event EventHandler<SettingsChangedEventArgs<TKey, TItem>>`  
  Fired whenever an item is added, removed, modified, or the collection is cleared.

#### Properties (from `IDictionary<TKey, TItem>`)

- **`this[TKey key]`**  
  `TItem this[TKey key] { get; set; }`  
  Gets or sets the value for the specified `key`. Setting a value fires a `Modified` event (note: *incorrectly* fires `Add` per implementation—see *Gotchas*).

- **`Keys`**  
  `ICollection<TKey> Keys { get; }`  
  Returns the collection of keys.

- **`Values`**  
  `ICollection<TItem> Values { get; }`  
  Returns the collection of values.

- **`Count`**  
  `int Count { get; }`  
  Returns the number of key-value pairs.

- **`IsReadOnly`**  
  `bool IsReadOnly { get; }`  
  Always `false`.

#### Methods (from `IDictionary<TKey, TItem>`)

- **`Add(TKey key, TItem value)`**  
  Adds a key-value pair. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.Add`.

- **`Add(KeyValuePair<TKey, TItem> item)`**  
  Adds a key-value pair. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.Add`.

- **`Remove(TKey key)`**  
  Removes the entry with the specified `key`. Returns `true` if removed. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.Remove`.

- **`Remove(KeyValuePair<TKey, TItem> item)`**  
  Removes the entry matching the key of `item`. Returns `true` if removed. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.Remove`.

- **`Clear()`**  
  Removes all entries. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.ClearAll`.

- **`ContainsKey(TKey key)`**  
  `bool ContainsKey(TKey key)`  
  Returns `true` if `key` exists.

- **`Contains(KeyValuePair<TKey, TItem> item)`**  
  `bool Contains(KeyValuePair<TKey, TItem> item)`  
  Returns `true` if both key and value exist in the collection.

- **`TryGetValue(TKey key, out TItem value)`**  
  `bool TryGetValue(TKey key, out TItem value)`  
  Returns `true` and sets `value` if `key` exists.

- **`CopyTo(KeyValuePair<TKey, TItem>[] array, int arrayIndex)`**  
  Throws `NotImplementedException`.

- **`GetEnumerator()`**  
  `IEnumerator<KeyValuePair<TKey, TItem>> GetEnumerator()`  
  Returns an enumerator over the collection.

- **`IEnumerable.GetEnumerator()`**  
  Explicit implementation of `IEnumerable.GetEnumerator()`.

---

### `SettingsChangedEventArgs<TKey, TItem> : EventArgs`

#### Constructors

- **`SettingsChangedEventArgs(ChangeSettingType changeType)`**  
  Initializes with only the `ChangeType`.

- **`SettingsChangedEventArgs(ChangeSettingType changeType, TKey key)`**  
  Initializes with `ChangeType` and `Key`.

- **`SettingsChangedEventArgs(ChangeSettingType changeType, TKey key, TItem item)`**  
  Initializes with `ChangeType`, `Key`, and `Item`.

#### Properties

- **`ChangeType`**  
  `ChangeSettingType ChangeType { get; }`  
  Type of change (`Add`, `Remove`, `Modified`, or `ClearAll`).

- **`Key`**  
  `TKey Key { get; }`  
  Key associated with the change (may be default if `ClearAll`).

- **`Item`**  
  `TItem Item { get; }`  
  Value associated with the change (may be default if `Remove` or `ClearAll`).

---

### `ChangeSettingType` Enum

- **`Add = 0`**  
  A new item was added.

- **`Remove = 1`**  
  An item was removed.

- **`Modified = 3`**  
  An existing item’s value was updated.

- **`ClearAll = 4`**  
  The entire collection was cleared.

---

## 3. Invariants

- **Event Firing**:  
  - `Add`, `Remove`, and `ClearAll` always fire an event.  
  - `this[key] = value` *always* fires an event (with `ChangeType.Add`, per implementation—see *Gotchas*).  
  - Events are fired *after* the underlying dictionary is mutated (i.e., state is consistent at event time).

- **Event Arguments**:  
  - For `Add`/`Modified`: `Key` and `Item` are non-null/non-default (assuming `TKey`/`TItem` allow it); `ChangeType` is `Add`.  
  - For `Remove`: `Item` is default (`default(TItem)`); `ChangeType` is `Remove`.  
  - For `ClearAll`: `Key` and `Item` are default; `ChangeType` is `ClearAll`.

- **No Partial Updates**:  
  Only full additions, removals, or clears trigger events—no partial or batched updates.

---

## 4. Dependencies

### Dependencies *of* this module:
- **`System.Collections.Generic`**  
  Provides `Dictionary<TKey, TItem>`, `ICollection<TKey>`, `ICollection<TItem>`, `IEnumerator<T>`, `IDictionary<TKey, TItem>`.
- **`System`**  
  Provides `EventArgs`, `EventHandler<T>`, `NotImplementedException`, `enum`.

### Dependencies *on* this module:
- **`DataPRO.Core.Settings` namespace**  
  Used internally by consumers (e.g., `SettingsChangedEventArgs` and `ChangeSettingType` are public and likely used elsewhere in the codebase to handle settings changes).

### Inferred Usage:
- Likely consumed by UI layers or configuration managers that need to react to settings changes (e.g., saving to disk, updating UI controls).

---

## 5. Gotchas

- **Incorrect `Modified` Event Type**:  
  The indexer setter (`this[TKey key] { set { ... } }`) fires `ChangeSettingType.Add` instead of `ChangeSettingType.Modified`. This is inconsistent with the semantic meaning of "modify" and may mislead consumers expecting `Modified` for updates.  
  **Example**:  
  ```csharp
  collection["foo"] = "bar"; // Fires Add, not Modified
  ```

- **`CopyTo` Not Implemented**:  
  `CopyTo(KeyValuePair<TKey, TItem>[], int)` throws `NotImplementedException`. This violates the `ICollection<KeyValuePair<TKey, TItem>>` contract and may cause runtime failures if used (e.g., via LINQ’s `ToArray()` or `ToList()`).

- **`Contains(KeyValuePair<TKey, TItem>)` Semantics**:  
  Checks both key *and* value equality. This is stricter than typical dictionary `Contains` behavior (which usually checks only key), and may cause confusion.

- **No Validation on Keys/Values**:  
  No checks for `null` keys (if `TKey` is a reference type) or duplicate keys—relies on underlying `Dictionary<TKey, TItem>` to throw `ArgumentNullException`/`ArgumentException`.

- **No Thread Safety**:  
  No synchronization primitives are used. Concurrent access may corrupt state or cause race conditions in event firing.

- **Event Subscribers May Receive Unexpected `Item` Values**:  
  For `Remove` and `ClearAll`, `Item` is `default(TItem)`. Consumers must not assume `Item` is always meaningful.

- **No `Modified` Event for Direct Assignment**:  
  Since the indexer uses `Add` semantics, there is no way to distinguish between *adding a new key* and *updating an existing key* via the event—unless the consumer tracks state themselves.

- **Historical Quirk**:  
  The `ClearAll` event omits `Key` and `Item` (both `default`), while other operations populate them. This is consistent with the enum design but may require special handling in event handlers.

--- 

*Documentation generated from source files only. No external behavior or assumptions beyond the provided code.*