Repository navigation
[maui-labs docs] Document Linux GTK4 Platform Backend and CSS Styling Updates #3537
Description
Source PR
PR Title: Fix GTK CSS composition and pixel font sizing
Author: Gerald Versluis
Merge Date: 2026-09-29
Summary of Changes
PR #541 improves the Linux GTK4 platform backend with:
-
New GTK4 Platform README - Comprehensive documentation of the
Microsoft.Maui.Platforms.Linux.Gtk4platform backend, including:- Control and handler support matrix (Label, Button, Entry, Editor, CheckBox, Switch, Slider, Picker, CollectionView, ListView, TableView, CarouselView, NavigationPage, Shell, etc.)
- Platform features: Native GTK4 rendering, Blazor Hybrid support, gestures, animations, transforms, theming, lifecycle events
- CSS styling behavior and handler composition model
-
CSS Styling Improvements:
- Per-widget mapper style preservation
- Default restoration on reset
- Proper CSS composition across handlers
- Pixel font size handling (logical pixels matching MAUI device-independent sizes)
-
Bug Fixes: Fixes Remote simulator should now work #540 related to CSS property preservation and pixel font sizing
Documentation Pages Affected
- New or updated pages needed:
docs/developer-tools/index.md- Add Linux GTK4 platform to platform support overviewdocs/dotnet-maui/platforms/index.mdor similar - Add GTK4 platform backend documentation- Potentially:
docs/dotnet-maui/platforms/linux/- New section for Linux/GTK4 platform
Suggested Changes
1. Update docs/developer-tools/index.md or main platforms page to include:
Add Linux GTK4 to the supported platforms list:
| Platform | Backend | Package | Status |
|---|---|---|---|
| Windows (WPF) | WPF | Microsoft.Maui.Platforms.Windows.WPF |
Experimental |
| macOS (AppKit) | AppKit | Microsoft.Maui.Platforms.MacOS |
Experimental |
| Linux (GTK4) | GTK4 | Microsoft.Maui.Platforms.Linux.Gtk4 |
Experimental |
2. Create new or update platform documentation page with GTK4 section:
## Linux / GTK4
The Linux GTK4 platform backend brings .NET MAUI applications to Linux desktops using GTK4 rendering via GirCore bindings.
### Supported Controls
- **Basic Controls**: Label, Button, Entry, Editor, CheckBox, Switch, Slider, Stepper, ProgressBar, ActivityIndicator, Image, ImageButton, BoxView, RadioButton
- **Input & Selection**: Picker, DatePicker, TimePicker, SearchBar
- **Collections**: CollectionView (virtualized), ListView, TableView, CarouselView, SwipeView, RefreshView, IndicatorView
- **Layouts**: StackLayout, Grid, FlexLayout, AbsoluteLayout, ScrollView, ContentView, Border, Frame
- **Pages & Navigation**: ContentPage, NavigationPage, TabbedPage, FlyoutPage, Shell
- **Shapes**: Rectangle, Ellipse, Line, Path, Polygon, Polyline (Cairo-rendered)
- **Other**: GraphicsView (Cairo), WebView (WebKitGTK)
### Platform Features
- Native GTK4 rendering with every control mapped to a real GTK4 widget
- Blazor Hybrid support for hosting Blazor components in GTK windows
- Full gesture support: Tap, Pan, Swipe, Pinch, and Pointer gestures
- Animations: TranslateTo, FadeTo, ScaleTo, RotateTo at ~60fps
- Transforms: TranslationX/Y, Rotation, Scale via Gsk.Transform
- VisualStateManager with Normal, PointerOver, Pressed, Disabled, Focused states
- ControlTemplate support with ContentPresenter
- Font icon support with embedded font registration
- FormattedText with Pango markup (colors, fonts, sizes, formatting)
- Alerts, dialogs, and modal pages via GTK4 windows
- Brushes and gradients (SolidColor, LinearGradient, RadialGradient)
- MenuBar and context menus
- Automatic light/dark theme detection
### CSS Styling
The GTK4 backend uses CSS for styling. Font sizes are specified in logical pixels (px), matching MAUI's device-independent units. Handler CSS is composed per widget and preserved across updates:
- Font, color, spacing, background, and border updates preserve one another
- Custom handlers should pass complete CSS fragments on every update
- Use `property` key for distinct independently-updated properties
- Most recently updated fragment wins for overlapping declarations
### Quick Start
Install the GTK4 platform:
\`\`\`bash
dotnet add package Microsoft.Maui.Platforms.Linux.Gtk4 --prerelease
\`\`\`
Add GTK4 to your MauiProgram:
\`\`\`csharp
var builder = MauiApp.CreateBuilder()
.UseMauiApp(App)()
.UseGtk4(); // Enable GTK4 platform
var app = builder.Build();
app.Run();
\`\`\`
For more details, see [Linux GTK4 Platform README](https://github.com/dotnet/maui-labs/blob/main/platforms/Linux.Gtk4/README.md) in the maui-labs repository.3. Update TOC (docs/TOC.yml) to include the new Linux/GTK4 platform section if creating a new page.
Notes
- The GTK4 platform is marked as experimental/early stage
- Complete feature matrix and examples are available in the platform's README
- Consider linking to the repository's GTK4 documentation for detailed platform API reference
- CSS styling behavior is a key architectural aspect that developers should understand when creating custom handlers
Generated by PR Documentation Check for issue #541 · ◷
Activity