OpenMaui.Controls.Linux.Maps 10.0.70.3

OpenMaui Linux Platform

A comprehensive Linux platform implementation for .NET MAUI using SkiaSharp rendering.

Developed by MarketAlly Pte Ltd Lead Architect: David H. Friedel Jr.

Overview

This project brings .NET MAUI to Linux desktops with native X11/Wayland support, hardware-accelerated Skia rendering, and full platform service integration.

Key Features

• Full Control Library: 50+ controls including Button, Label, Entry, Shapes, CarouselView, RefreshView, SwipeView, and more
• Native Integration: First-class X11 and native Wayland support (xdg-shell, wp_viewporter, fractional-scale-v1, zxdg_decoration_manager_v1, zwp_primary_selection_v1) — programmatically selectable or auto-detected
• Accessibility: AT-SPI2 screen reader support and high contrast mode
• Platform Services: Native wl_data_device_manager clipboard and drag-and-drop (no wl-clipboard subprocess required), zwp_primary_selection_v1 middle-click paste, file picker, notifications, global hotkeys, CUPS printing, system tray icons via StatusNotifierItem
• Input Methods: IBus / XIM on X11 + native zwp_text_input_v3 on Wayland with full delete_surrounding_text round-trip for compositor-integrated IMEs (GNOME Pinyin/Hangul/Anthy, native Fcitx5)
• High DPI: Automatic scale factor detection for GNOME, KDE, and X11; fractional scale handled via Wayland viewporter for pixel-exact rendering at non-integer scales (1.25x, 1.5x, 1.75x)
• Theming: AppThemeBinding live propagation across the entire view tree — CollectionView items, pushed pages, Shell content, and flyout regions all flip on theme toggle
• Window decorations: Server-side decorations (KDE/Sway) or client-side titlebar drawn in Skia with full drag/resize/close/maximize/minimize (GNOME/Mutter)
• MediaElement: Opt-in OpenMaui.Controls.Linux.MediaElement package backs CommunityToolkit.Maui.MediaElement with GStreamer (playbin + appsink → Skia). MediaHardwareAcceleration.Prefer boosts VA-API / NVDEC / V4L2 / MediaSDK decoder ranks when those plugins are installed
• Maps: Opt-in OpenMaui.Controls.Linux.Maps package backs Microsoft.Maui.Controls.Maps with OpenStreetMap raster tiles in Skia — pan/zoom, pin & polyline overlays, persistent XDG tile cache. Plus a standalone SkiaMap view for code-first map UI

Quick Start

Installation

# Install the templates
dotnet new install OpenMaui.Linux.Templates

# Create a new project (choose one):
dotnet new openmaui-linux -n MyApp           # Code-based UI
dotnet new openmaui-linux-xaml -n MyApp      # XAML-based UI (recommended)

cd MyApp
dotnet run

Manual Installation

dotnet add package OpenMaui.Controls.Linux

Optional: MediaElement (video / audio playback)

CommunityToolkit.Maui.MediaElement on Linux requires the opt-in sibling package that adds the GStreamer-backed handler:

dotnet add package CommunityToolkit.Maui.MediaElement
dotnet add package OpenMaui.Controls.Linux.MediaElement

Then in your MauiProgram.cs:

builder
    .UseMauiApp<App>()
    .UseMauiCommunityToolkitMediaElement(isAndroidForegroundServiceEnabled: false)
    .UseLinux()
    .UseLinuxMediaElement();   // Linux backend; no-op on Windows/Android/iOS/macCatalyst

System dependencies (GStreamer + plugin sets):

# Fedora
sudo dnf install gstreamer1-plugins-good gstreamer1-plugins-bad-free \
                 gstreamer1-plugins-ugly-free gstreamer1-libav gstreamer1-vaapi

# Ubuntu/Debian
sudo apt install gstreamer1.0-plugins-good gstreamer1.0-plugins-bad \
                 gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-vaapi

gstreamer1-vaapi enables hardware-accelerated decode on Intel/AMD GPUs; substitute the nvdec plugin for NVIDIA. Software decode works without either.

To explicitly bias playbin toward the hardware decoders when they are installed:

using Microsoft.Maui.Platform.Linux.MediaElement.Services;

builder.UseLinuxMediaElement(MediaHardwareAcceleration.Prefer);

Auto keeps the default behavior, Prefer bumps HW decoder factory ranks above SW, and Disable demotes them.

Optional: Maps (OpenStreetMap)

Microsoft.Maui.Controls.Maps on Linux uses the opt-in sibling package that adds an OSM raster-tile renderer:

dotnet add package Microsoft.Maui.Controls.Maps
dotnet add package OpenMaui.Controls.Linux.Maps

Then in your MauiProgram.cs:

builder
    .UseMauiApp<App>()
    .UseMauiMaps()
    .UseLinux()
    .UseLinuxMaps();   // Linux backend; no-op on Windows/Android/iOS/macCatalyst

Tiles are fetched from tile.openstreetmap.org on first view and cached under $XDG_CACHE_HOME/openmaui/osm-tiles. To use a self-hosted or commercial tile server, override the URL template at startup:

using Microsoft.Maui.Platform.Linux.Maps.Services;

OsmTileService.Default.UrlTemplate = "https://my-tiles.example.com/{z}/{x}/{y}.png";

For code-first map UI without Microsoft.Maui.Controls.Maps, the package also exposes a standalone SkiaMap view that subclasses SkiaView:

using Microsoft.Maui.Platform.Linux.Maps.Views;

var map = new SkiaMap { CenterLatitude = 35.68, CenterLongitude = 139.65, ZoomLevel = 11 };
map.Pins.Add(new MapPin { Latitude = 35.68, Longitude = 139.65, Label = "Tokyo" });

OSM's tile usage policy requires displaying attribution; SkiaMap renders the credit overlay automatically (toggle with ShowAttribution).

XAML Support

OpenMaui fully supports standard .NET MAUI XAML syntax. Use the familiar XAML workflow:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             x:Class="MyApp.MainPage">
    <VerticalStackLayout>
        <Label Text="Hello, OpenMaui!" FontSize="32" />
        <Button Text="Click me" Clicked="OnButtonClicked" />
        <Entry Placeholder="Enter text..." />
        <Slider Minimum="0" Maximum="100" />
    </VerticalStackLayout>
</ContentPage>

// MauiProgram.cs
var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseLinux();  // Enable Linux with XAML support (auto-detects X11/Wayland)

Backend Selection (X11 / Wayland)

Pick exactly one — calls are no-ops on Windows/Android/iOS so they're safe in cross-platform MauiProgram.cs:

builder
    .UseMauiApp<App>()
    .UseLinux();      // auto-detect from session (default)
    // .UseX11();     // force X11/XWayland — most stable, recommended for WebView-heavy apps
    // .UseWayland(); // prefer native Wayland; auto-falls back to X11 if Wayland unavailable

Native Wayland uses xdg-shell + wp_viewporter for fractional-scale rendering and ssd via zxdg_decoration_manager_v1. The X11 path remains the default fallback and is fully supported. Environment overrides (MAUI_PREFER_X11=1, GDK_BACKEND=x11) still work and take effect before the builder runs.

Supported Controls

Platform Services

Accessibility

• AT-SPI2: Screen reader support for ORCA and other assistive technologies
• High Contrast: Automatic detection and color palette support
• Keyboard Navigation: Full keyboard accessibility

Requirements

• .NET 10.0 SDK or later
• Linux (kernel 5.4+)
• X11 or Wayland
• SkiaSharp native libraries

System Dependencies

Ubuntu/Debian:

sudo apt-get install libx11-dev libxrandr-dev libxcursor-dev libxi-dev libgl1-mesa-dev libfontconfig1-dev

Fedora:

sudo dnf install libX11-devel libXrandr-devel libXcursor-devel libXi-devel mesa-libGL-devel fontconfig-devel

Documentation

• Getting Started Guide
• FAQ - Visual Studio Integration
• API Reference
• Contributing Guide

Sample Applications

Full sample applications are available in the maui-linux-samples repository:

Distribution

Package your OpenMaui app as a portable AppImage with a single command:

dotnet tool install --global OpenMaui.AppImage
dotnet appimage

Auto-detects your executable and icon, generates a .desktop file, and produces a self-contained AppImage that runs on most Linux distributions. See the OpenMaui.AppImage repository for details.

Quick Example

// MauiProgram.cs
using Microsoft.Maui.Hosting;
using Microsoft.Maui.Platform.Linux.Hosting;

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseLinux();   // or .UseX11() / .UseWayland() to force a backend

var app = builder.Build();
LinuxApplication.Run(app, args);

Building from Source

# Primary repository
git clone https://github.com/open-maui/maui-linux.git

# Or from GitHub mirror
git clone https://github.com/open-maui/maui-linux.git

cd maui-linux
dotnet build
dotnet test

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Note: Please submit issues and pull requests on GitHub.

Architecture

┌─────────────────────────────────────────────────┐
│                  .NET MAUI                       │
│              (Virtual Views)                     │
├─────────────────────────────────────────────────┤
│                  Handlers                        │
│         (Platform Abstraction)                   │
├─────────────────────────────────────────────────┤
│              Skia Views                          │
│        (SkiaButton, SkiaLabel, etc.)            │
├─────────────────────────────────────────────────┤
│           SkiaSharp Rendering                    │
│         (Hardware Accelerated)                   │
├─────────────────────────────────────────────────┤
│              X11 / Wayland                       │
│          (Display Server)                        │
└─────────────────────────────────────────────────┘

Styling and Data Binding

OpenMaui supports the full MAUI styling and data binding infrastructure:

XAML Styles

<ContentPage.Resources>
    <ResourceDictionary>
        <Color x:Key="PrimaryColor">#5C6BC0</Color>
        <Style TargetType="Button">
            <Setter Property="BackgroundColor" Value="{StaticResource PrimaryColor}" />
            <Setter Property="TextColor" Value="White" />
        </Style>
    </ResourceDictionary>
</ContentPage.Resources>

Data Binding

<Label Text="{Binding Title}" />
<Entry Text="{Binding Username, Mode=TwoWay}" />
<Button Command="{Binding SaveCommand}" IsEnabled="{Binding CanSave}" />

Visual State Manager

All interactive controls support VSM states: Normal, PointerOver, Pressed, Focused, Disabled.

<Button Text="Hover Me">
    <VisualStateManager.VisualStateGroups>
        <VisualStateGroup x:Name="CommonStates">
            <VisualState x:Name="Normal">
                <VisualState.Setters>
                    <Setter Property="BackgroundColor" Value="#2196F3"/>
                </VisualState.Setters>
            </VisualState>
            <VisualState x:Name="PointerOver">
                <VisualState.Setters>
                    <Setter Property="BackgroundColor" Value="#42A5F5"/>
                </VisualState.Setters>
            </VisualState>
        </VisualStateGroup>
    </VisualStateManager.VisualStateGroups>
</Button>

Roadmap

• Core control library (50+ controls)
• Platform services integration
• Accessibility (AT-SPI2)
• Input method support (IBus/XIM)
• High DPI support
• Drag and drop
• Global hotkeys
• BindableProperty for all controls
• Visual State Manager integration
• XAML styles and StaticResource
• Data binding (OneWay, TwoWay, IValueConverter)
• App icon support (MauiIcon build targets, .desktop integration)
• Dark mode for all picker popups
• DPI-aware popup rendering with edge detection
• MAUI Shapes (Ellipse, Line, Rectangle, Polygon, Polyline, Path)
• Native Wayland backend (xdg-shell, wp_viewporter, fractional-scale-v1, decoration-manager)
• Programmatic backend selection (UseX11() / UseWayland())
• AppThemeBinding live propagation through Shell, NavigationPage, and CollectionView item trees
• GTK4 interop layer (Gtk4InteropService with GTK3 fallback)
• Client-side decorations for GNOME-Wayland sessions (10.0.60.10)
• Native wl_data_device_manager clipboard — zero subprocess overhead, works without wl-clipboard (10.0.60.11)
• zwp_text_input_v3 IME for native Wayland (Fcitx5 / GNOME Pinyin) (10.0.60.12)
• MediaElement / video support via GStreamer — opt-in OpenMaui.Controls.Linux.MediaElement sibling package (10.0.60.13)
• MAUI 10.0.70 alignment — default-template CS1508 fix, Wayland-shim deployment fix, Essentials registration fix for MAUI 10's split SetDefault/SetCurrent naming (10.0.70.1)
• IInputContext.DeleteSurrounding — zwp_text_input_v3.delete_surrounding_text round-trips into SkiaEntry / SkiaEditor with full UTF-8 byte → UTF-16 char conversion (10.0.70.2)
• Primary-selection clipboard — zwp_primary_selection_v1 binding + PrimarySelectionService, SkiaEntry / SkiaEditor push on drag-end and paste on middle-click (10.0.70.2)
• Native wl_data_device_manager drag-and-drop — first functional Linux DnD path, file-drop URI decoding, source-side start_drag (10.0.70.2)
• Hardware video acceleration tuning — MediaHardwareAcceleration.Prefer boosts VA-API / NVDEC / V4L2 / MediaSDK decoder ranks (10.0.70.2)
• System tray icons — TrayIcon over libappindicator3 / libayatana-appindicator3 (StatusNotifierItem on the session bus) (10.0.70.2)
• CUPS printing — PrintService enumerates printers, submits files, renders Skia pages to PDF via SKDocument and prints (10.0.70.2)
• Maps integration (OpenStreetMap) — opt-in OpenMaui.Controls.Linux.Maps sibling package backs Microsoft.Maui.Controls.Maps with OSM raster tiles, pin / polyline overlays, persistent XDG tile cache (10.0.70.2)

Up next

• set_surrounding_text for text-input-v3 — pass focused entry text + caret to IME for better word suggestions
• Hardware video decode zero-copy — explicit pipeline construction for direct compositor-surface playback (Prefer mode already covers decoder selection)
• XAML Hot Reload
• Live Visual Tree debug tool
• Tray icon _NET_WM_SYSTEM_TRAY fallback for desktops without an SNI host
• Maps satellite / hybrid layers and filled-shape (polygon / circle) overlays
• CUPS print preview / options dialog
• Tmds.DBus migration to replace the dbus-monitor subprocess in Fcitx5InputMethodService

License

Copyright (c) 2025-2026 MarketAlly Pte Ltd. Licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• MarketAlly Pte Ltd - Project development and maintenance
• SkiaSharp - 2D graphics library
• .NET MAUI - Cross-platform UI framework
• The .NET community
• A very special thank you to the Anthropic team for delivering on the promise I hold most dear — that an individual with enough energy and persistence can still make a difference