Skip to content

[maui-labs docs] Document Linux GTK4 Platform Backend and CSS Styling Updates #3537

Open

Description

@MauiBot

Source PR

dotnet/maui-labs#541

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:

  1. New GTK4 Platform README - Comprehensive documentation of the Microsoft.Maui.Platforms.Linux.Gtk4 platform 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
  2. 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)
  3. 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 overview
    • docs/dotnet-maui/platforms/index.md or 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 · ◷

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions