Settings Change Notifications

A feature that informs developers whenever one of the control’s settings is modified, allowing for immediate handling of configuration updates and logging of changes.

Overview

The Settings Change Notifications feature uses the OnSettingsChanged event to alert subscribers whenever a configurable property (such as CacheSize, EnableAsync, NegativePrefix, etc.) is updated. The event provides detailed information through SettingsChangedEventArgs, including the property name, its old value, and its new value. This facilitates dynamic responses and debugging in applications that rely on real-time configuration adjustments.

---

Key Points

Aspect	Description
Event Trigger	The OnSettingsChanged event is raised whenever a public property setting is updated.
Event Arguments	The event uses SettingsChangedEventArgs to supply details about the property change: the property name, its previous value, and the new value.
Dynamic Response	Developers can respond dynamically to changes in settings, such as updating the UI or logging changes for audit purposes.

Code Example

// Subscribe to the settings change notifications
var humanizer = new SiticoneHumanizerInt();
humanizer.OnSettingsChanged += (sender, e) =>
{
    Console.WriteLine($"Setting changed: {e.PropertyName} changed from {e.OldValue} to {e.NewValue}");
};

// Trigger a settings change by modifying a property
humanizer.CacheSize = 1500;

---

Best Practices

Practice	Recommendation
Implement Lightweight Handlers	Ensure that event handlers for OnSettingsChanged perform minimal processing to avoid slowing down the settings update process.
Log Critical Settings Changes	Use the event to log changes for important configuration settings to facilitate debugging and audits.
Validate and Sanitize Inputs	Before applying changes that trigger notifications, validate inputs to avoid unnecessary or erroneous updates that might lead to cascading changes.

Code Example

// Example: Logging settings changes for audit purposes
humanizer.OnSettingsChanged += (sender, e) =>
{
    // Log the change to a file or monitoring system
    LogSettingChange(e.PropertyName, e.OldValue, e.NewValue);
};

void LogSettingChange(string propertyName, object oldValue, object newValue)
{
    // Simplified logging example
    Console.WriteLine($"[LOG] {propertyName} updated from {oldValue} to {newValue}");
}

---

Common Pitfalls

Pitfall	Explanation
Heavy Processing in Handlers	Performing resource-intensive operations in the event handler may delay the update process or affect application performance.
Ignoring the Event	Failing to subscribe to the OnSettingsChanged event might result in missing crucial configuration updates that require application response.
Not Handling All Property Changes	Overlooking some property changes may lead to inconsistent application behavior if only a subset of updates is logged or processed.

Code Example

// Incorrect: A heavy operation inside the event handler causing performance issues
humanizer.OnSettingsChanged += (sender, e) =>
{
    // Simulate heavy processing that might block other operations
    System.Threading.Thread.Sleep(5000); 
    Console.WriteLine($"Setting {e.PropertyName} updated.");
};

---

Usage Scenarios

Scenario	How It Works
Dynamic UI Updates	Adjust the application UI in response to settings changes, ensuring that the interface reflects the most current configuration.
Real-Time Logging	Log all configuration changes in real time to maintain an audit trail of dynamic adjustments made during application runtime.
Adaptive Behavior	Modify application behavior based on settings changes, such as updating conversion formats or performance tuning parameters.

Code Example

// Example: Updating a UI element dynamically based on a settings change
humanizer.OnSettingsChanged += (sender, e) =>
{
    if (e.PropertyName == nameof(humanizer.CacheSize))
    {
        lblCacheSize.Text = $"Cache Size: {e.NewValue}";
    }
};

---

Real Life Usage Scenarios

Scenario	Explanation
Configuration Dashboards	In applications that provide configuration dashboards, use this event to instantly reflect changes made by administrators.
Performance Tuning Tools	For performance-critical applications, track changes in settings such as AsyncTimeout or CacheSize to fine-tune system responsiveness.
Audit Logging Systems	In regulated environments, maintain an audit log of configuration changes to comply with standards and support debugging efforts.

Code Example

// Example: Recording settings changes in an audit log
humanizer.OnSettingsChanged += (sender, e) =>
{
    // Append settings change information to an audit log
    AuditLog.RecordChange(e.PropertyName, e.OldValue, e.NewValue);
};

public static class AuditLog
{
    public static void RecordChange(string propertyName, object oldValue, object newValue)
    {
        // Simple audit log record
        Console.WriteLine($"[AUDIT] {DateTime.UtcNow}: {propertyName} changed from {oldValue} to {newValue}");
    }
}

---

Troubleshooting Tips

Tip	Details
Verify Subscription	Ensure that event handlers are correctly subscribed to OnSettingsChanged to catch all configuration updates.
Use Minimal Processing	If experiencing performance issues, reduce the workload in the event handler to ensure timely processing of settings changes.
Debug Logging	Incorporate detailed logging within the event handler to monitor which settings are being changed and diagnose potential issues.

Code Example

// Example: Debugging settings change notifications
humanizer.OnSettingsChanged += (sender, e) =>
{
    Debug.WriteLine($"[DEBUG] {e.PropertyName} changed from {e.OldValue} to {e.NewValue}");
};

---

Review

Aspect	Consideration
Responsiveness	The event-driven model provides immediate feedback on configuration changes, enabling quick adaptations in the application.
Developer Control	Detailed event arguments give developers complete insight into what setting has changed, along with its old and new values, facilitating precise control.
Ease of Integration	Simple subscription to the OnSettingsChanged event allows seamless integration into various application components, from UI updates to logging.

---

Summary

Summary Point	Description
Real-Time Notification	Notifies developers immediately when settings change, allowing for dynamic responses and adjustments within the application.
Detailed Information Provided	Provides property-specific information including the old and new values, ensuring clear tracking of configuration changes.
Facilitates Adaptive Application	Enables applications to adapt their behavior dynamically based on configuration updates, improving responsiveness and user experience.

Final Integration Example

using System;
using SiticoneNetFrameworkUI;

namespace DemoSettingsChangeNotifications
{
    class Program
    {
        static void Main(string[] args)
        {
            // Initialize the humanizer control
            var humanizer = new SiticoneHumanizerInt();

            // Subscribe to settings change notifications
            humanizer.OnSettingsChanged += (sender, e) =>
            {
                Console.WriteLine($"Setting '{e.PropertyName}' changed from {e.OldValue} to {e.NewValue}");
            };

            // Simulate various settings changes
            humanizer.CacheSize = 1200;             // Changing CacheSize
            humanizer.EnableAsync = true;           // Enabling asynchronous processing
            humanizer.NegativePrefix = "negative";  // Updating the negative number prefix

            // Keep the console window open
            Console.WriteLine("Press any key to exit.");
            Console.ReadKey();
        }
    }
}

---

This comprehensive documentation should provide developers with all the necessary details, best practices, usage scenarios, troubleshooting tips, and code examples to effectively integrate and utilize the Settings Change Notifications feature in their .NET WinForms applications.