PropertyGrid/Examples/AdvancedExample/README.md

Advanced PropertyGrid Example

This example demonstrates advanced features of the Avalonia PropertyGrid control with a comprehensive configuration editor.

Features Demonstrated

1. Nested Object Properties

• DatabaseSettings - Complex nested object with multiple properties
• NetworkSettings - Another nested object showing hierarchical data
• Both nested objects implement INotifyPropertyChanged for real-time updates

2. Data Validation

• Required fields: ServerName, Hostname, ConnectionString
• Range validation:
  • MaxConnections (1-1000)
  • Port (1-65535)
  • CompressionLevel (0-9)
• String length: ServerName (3-50 characters)
• Validation errors are displayed in the PropertyGrid

3. Property Categories

Properties are organized into logical categories:

• Server Configuration - Server name, connections, security
• Logging - Logging settings and configuration
• Network - Network and connectivity settings
• Database - Database connection and performance
• Security - Authentication and access control
• Performance - Caching and optimization
• Appearance - UI theme and visual settings
• Metadata - Read-only system information

4. Property Change Notifications

• Implements INotifyPropertyChanged interface
• Real-time UI updates when properties change
• Computed properties (e.g., RequiresCertificate) automatically update based on other properties
• LastModified timestamp updates automatically

5. Read-Only Properties

• RequiresCertificate - Computed based on ConnectionType
• ThemeColorName - Computed based on ThemeColor
• CreatedDate, LastModified, ConfigurationId - Metadata properties
• VIN in the basic example - Demonstration of fixed values

6. Various Data Types

• Strings: ServerName, ApiKey, ConnectionString
• Numbers: Int (MaxConnections, Port), Decimal (Price in basic example)
• Enums: ConnectionType, LogLevel, DatabaseProvider (with descriptions)
• Boolean: EnableLogging, UseProxy, EnableRetry
• DateTime: CreatedDate, LastModified
• TimeSpan: Timeout
• Guid: ConfigurationId
• Color: ThemeColor (Avalonia.Media.Color)
• Collections: List for AllowedIPs

7. Enum Descriptions

Enums include [Description] attributes for user-friendly display:

public enum ConnectionType
{
	[Description("Plain HTTP connection")]
	Http,

	[Description("Secure HTTPS/SSL connection")]
	Ssl,
	// ...
}

8. Special Property Attributes

• [PasswordPropertyText(true)] - Hides API key text
• [EditorBrowsable(EditorBrowsableState.Advanced)] - Groups advanced properties
• [Display] - Custom names, descriptions, and ordering
• [Category] - Logical grouping

9. Property Ordering

Properties are ordered using the Order parameter in [Display] attribute:

[Display(Name = "Server Name", Order = 1)]
[Display(Name = "Max Connections", Order = 2)]

10. Search and Filter

The PropertyGrid includes built-in search functionality to quickly find properties across all categories.

Code Structure

AdvancedExample/
├── Models/
│   └── AdvancedConfiguration.cs    # Main configuration model
│       ├── AdvancedConfiguration   # Root configuration object
│       ├── NetworkSettings         # Nested network settings
│       ├── DatabaseSettings        # Nested database settings
│       └── Enums                   # ConnectionType, LogLevel, DatabaseProvider
├── MainWindow.axaml                # UI with PropertyGrid
├── MainWindow.axaml.cs             # Window code-behind
├── App.axaml                       # Application definition
├── App.axaml.cs                    # Application startup
└── Program.cs                      # Entry point

Running the Example

1. Build the solution:

   dotnet build Examples/AdvancedExample/AdvancedExample.csproj
   

2. Run the application:

   dotnet run --project Examples/AdvancedExample/AdvancedExample.csproj
   

Key Concepts

INotifyPropertyChanged Implementation

protected bool SetProperty<T>(ref T field, T value, [CallerMemberName] string? propertyName = null)
{
	if (EqualityComparer<T>.Default.Equals(field, value))
		return false;

	field = value;
	LastModified = DateTime.Now;
	OnPropertyChanged(propertyName);
	return true;
}

Computed Properties

public bool RequiresCertificate => ConnectionType == ConnectionType.Ssl;

Nested Objects

[Display(Name = "Database Settings", Description = "Database connection settings")]
[Category("Database")]
public DatabaseSettings DatabaseSettings { get; set; }

Comparison with QuickStartExample

Feature	QuickStartExample	AdvancedExample
Properties	~10 basic properties	25+ properties including nested
Categories	5 categories	7 categories
Validation	None	Multiple validation rules
Nested Objects	None	2 nested objects
Change Notifications	No	Full INotifyPropertyChanged
Computed Properties	None	RequiresCertificate
Data Types	Basic types	Extended types including TimeSpan, Guid, Lists

Best Practices Demonstrated

1. ✅ Use meaningful category names
2. ✅ Provide descriptions for all properties
3. ✅ Implement validation where appropriate
4. ✅ Use INotifyPropertyChanged for reactive UIs
5. ✅ Order properties logically
6. ✅ Mark read-only properties appropriately
7. ✅ Use nested objects for complex configurations
8. ✅ Add descriptions to enum values
9. ✅ Use appropriate data types
10. ✅ Keep related properties in the same category

Further Enhancements

Consider these additional features for even more advanced scenarios:

• Custom property editors
• Dynamic property generation
• Property value converters
• Conditional property visibility
• Multi-object editing
• Undo/Redo functionality
• Save/Load configuration
• Property value validation with custom validators

License

This example is part of the Avalonia.PropertyGrid demonstration projects.