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<string> for AllowedIPs

### 7. **Enum Descriptions**
Enums include `[Description]` attributes for user-friendly display:
```csharp
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:
```csharp
[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:
   ```bash
   dotnet build Examples/AdvancedExample/AdvancedExample.csproj
   ```

2. Run the application:
   ```bash
   dotnet run --project Examples/AdvancedExample/AdvancedExample.csproj
   ```

## Key Concepts

### INotifyPropertyChanged Implementation
```csharp
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
```csharp
public bool RequiresCertificate => ConnectionType == ConnectionType.Ssl;
```

### Nested Objects
```csharp
[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.