--- 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` Module Documentation --- ## 1. Purpose The `SettingsCollection` class provides a dictionary-based collection that notifies subscribers of changes (add, remove, modify, clear) via the `CollectionItemPropertyChanged` event. It extends `IDictionary` 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 : IDictionary` #### Event - **`CollectionItemPropertyChanged`** `event EventHandler>` Fired whenever an item is added, removed, modified, or the collection is cleared. #### Properties (from `IDictionary`) - **`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 Keys { get; }` Returns the collection of keys. - **`Values`** `ICollection 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`) - **`Add(TKey key, TItem value)`** Adds a key-value pair. Fires `CollectionItemPropertyChanged` with `ChangeSettingType.Add`. - **`Add(KeyValuePair 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 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 item)`** `bool Contains(KeyValuePair 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[] array, int arrayIndex)`** Throws `NotImplementedException`. - **`GetEnumerator()`** `IEnumerator> GetEnumerator()` Returns an enumerator over the collection. - **`IEnumerable.GetEnumerator()`** Explicit implementation of `IEnumerable.GetEnumerator()`. --- ### `SettingsChangedEventArgs : 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`, `ICollection`, `ICollection`, `IEnumerator`, `IDictionary`. - **`System`** Provides `EventArgs`, `EventHandler`, `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[], int)` throws `NotImplementedException`. This violates the `ICollection>` contract and may cause runtime failures if used (e.g., via LINQ’s `ToArray()` or `ToList()`). - **`Contains(KeyValuePair)` 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` 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.*