# .NET MAUI Linux Platform API Documentation

## Overview

The .NET MAUI Linux Platform provides native Linux desktop support for .NET MAUI applications using SkiaSharp for rendering. It supports both X11 and Wayland display servers.

## Getting Started

### Installation

```bash
dotnet add package Microsoft.Maui.Controls.Linux
```

Or using the project template:

```bash
dotnet new install Microsoft.Maui.Linux.Templates
dotnet new maui-linux -n MyApp
```

### Basic Application Structure

```csharp
using Microsoft.Maui.Platform.Linux;

public class Program
{
    public static void Main(string[] args)
    {
        var app = LinuxApplication.CreateBuilder()
            .UseApp<App>()
            .Build();

        app.Run();
    }
}
```

## Core Components

### LinuxApplication

Entry point for Linux MAUI applications.

```csharp
public class LinuxApplication
{
    // Creates a new application builder
    public static LinuxApplicationBuilder CreateBuilder();

    // Gets the current application instance
    public static LinuxApplication Current { get; }

    // Gets the main window
    public IWindow MainWindow { get; }

    // Runs the application
    public void Run();

    // Quits the application
    public void Quit();
}
```

### LinuxApplicationBuilder

```csharp
public class LinuxApplicationBuilder
{
    // Sets the MAUI application type
    public LinuxApplicationBuilder UseApp<TApp>() where TApp : Application;

    // Configures the window
    public LinuxApplicationBuilder ConfigureWindow(Action<WindowOptions> configure);

    // Forces a specific display server
    public LinuxApplicationBuilder UseDisplayServer(DisplayServerType type);

    // Builds the application
    public LinuxApplication Build();
}
```

## View Controls

### SkiaButton

A clickable button control.

```csharp
public class SkiaButton : SkiaView
{
    public string Text { get; set; }
    public SKColor TextColor { get; set; }
    public SKColor BackgroundColor { get; set; }
    public float CornerRadius { get; set; }
    public float FontSize { get; set; }
    public event EventHandler? Clicked;
}
```

### SkiaEntry

A text input control.

```csharp
public class SkiaEntry : SkiaView, IInputContext
{
    public string Text { get; set; }
    public string Placeholder { get; set; }
    public SKColor TextColor { get; set; }
    public SKColor PlaceholderColor { get; set; }
    public float FontSize { get; set; }
    public bool IsPassword { get; set; }
    public int MaxLength { get; set; }
    public event EventHandler<TextChangedEventArgs>? TextChanged;
    public event EventHandler? Completed;
}
```

### SkiaSlider

A value slider control.

```csharp
public class SkiaSlider : SkiaView
{
    public double Value { get; set; }
    public double Minimum { get; set; }
    public double Maximum { get; set; }
    public SKColor TrackColor { get; set; }
    public SKColor ThumbColor { get; set; }
    public event EventHandler<ValueChangedEventArgs>? ValueChanged;
}
```

### SkiaScrollView

A scrollable container.

```csharp
public class SkiaScrollView : SkiaView
{
    public SkiaView? Content { get; set; }
    public float HorizontalScrollOffset { get; set; }
    public float VerticalScrollOffset { get; set; }
    public ScrollOrientation Orientation { get; set; }
    public event EventHandler? Scrolled;
}
```

### SkiaImage

An image display control.

```csharp
public class SkiaImage : SkiaView
{
    public SKBitmap? Source { get; set; }
    public ImageAspect Aspect { get; set; }
    public void LoadFromFile(string path);
    public void LoadFromStream(Stream stream);
}
```

## Layout Controls

### SkiaStackLayout

Arranges children in a stack.

```csharp
public class SkiaStackLayout : SkiaLayoutView
{
    public StackOrientation Orientation { get; set; }
    public float Spacing { get; set; }
}
```

### SkiaGrid

Arranges children in a grid.

```csharp
public class SkiaGrid : SkiaLayoutView
{
    public List<GridLength> RowDefinitions { get; }
    public List<GridLength> ColumnDefinitions { get; }
    public float RowSpacing { get; set; }
    public float ColumnSpacing { get; set; }

    public static void SetRow(SkiaView view, int row);
    public static void SetColumn(SkiaView view, int column);
    public static void SetRowSpan(SkiaView view, int span);
    public static void SetColumnSpan(SkiaView view, int span);
}
```

## Page Controls

### SkiaTabbedPage

A page with tab navigation.

```csharp
public class SkiaTabbedPage : SkiaLayoutView
{
    public int SelectedIndex { get; set; }
    public void AddTab(string title, SkiaView content, string? iconPath = null);
    public void RemoveTab(int index);
    public void ClearTabs();
    public event EventHandler? SelectedIndexChanged;
}
```

### SkiaFlyoutPage

A page with flyout/drawer navigation.

```csharp
public class SkiaFlyoutPage : SkiaLayoutView
{
    public SkiaView? Flyout { get; set; }
    public SkiaView? Detail { get; set; }
    public bool IsPresented { get; set; }
    public float FlyoutWidth { get; set; }
    public bool GestureEnabled { get; set; }
    public FlyoutLayoutBehavior FlyoutLayoutBehavior { get; set; }
    public event EventHandler? IsPresentedChanged;
}
```

### SkiaShell

Full navigation container with flyout, tabs, and URI routing.

```csharp
public class SkiaShell : SkiaLayoutView
{
    public bool FlyoutIsPresented { get; set; }
    public ShellFlyoutBehavior FlyoutBehavior { get; set; }
    public float FlyoutWidth { get; set; }
    public string Title { get; set; }
    public bool NavBarIsVisible { get; set; }
    public bool TabBarIsVisible { get; set; }

    public void AddSection(ShellSection section);
    public void NavigateToSection(int sectionIndex, int itemIndex = 0);
    public void GoToAsync(string route);

    public event EventHandler? FlyoutIsPresentedChanged;
    public event EventHandler<ShellNavigationEventArgs>? Navigated;
}
```

## Services

### Input Method Service (IME)

Provides international text input support.

```csharp
public interface IInputMethodService
{
    bool IsActive { get; }
    string PreEditText { get; }

    void Initialize(nint windowHandle);
    void SetFocus(IInputContext? context);
    void SetCursorLocation(int x, int y, int width, int height);
    bool ProcessKeyEvent(uint keyCode, KeyModifiers modifiers, bool isKeyDown);
    void Reset();

    event EventHandler<TextCommittedEventArgs>? TextCommitted;
    event EventHandler<PreEditChangedEventArgs>? PreEditChanged;
}

// Factory
var imeService = InputMethodServiceFactory.Instance;
```

### Accessibility Service (AT-SPI2)

Provides screen reader support.

```csharp
public interface IAccessibilityService
{
    bool IsEnabled { get; }

    void Initialize();
    void Register(IAccessible accessible);
    void Unregister(IAccessible accessible);
    void NotifyFocusChanged(IAccessible? accessible);
    void NotifyPropertyChanged(IAccessible accessible, AccessibleProperty property);
    void NotifyStateChanged(IAccessible accessible, AccessibleState state, bool value);
    void Announce(string text, AnnouncementPriority priority = AnnouncementPriority.Polite);
}

// Factory
var accessibilityService = AccessibilityServiceFactory.Instance;
```

## Rendering Optimization

### DirtyRectManager

Tracks invalidated regions for efficient redraw.

```csharp
public class DirtyRectManager
{
    public int MaxDirtyRects { get; set; }
    public bool NeedsFullRedraw { get; }
    public bool HasDirtyRegions { get; }

    public void SetBounds(SKRect bounds);
    public void Invalidate(SKRect rect);
    public void InvalidateAll();
    public void Clear();
    public SKRect GetCombinedDirtyRect();
    public void ApplyClipping(SKCanvas canvas);
}
```

### RenderCache

Caches rendered content for static views.

```csharp
public class RenderCache : IDisposable
{
    public long MaxCacheSize { get; set; }
    public long CurrentCacheSize { get; }

    public bool TryGet(string key, out SKBitmap? bitmap);
    public void Set(string key, SKBitmap bitmap);
    public void Invalidate(string key);
    public void InvalidatePrefix(string prefix);
    public void Clear();
    public SKBitmap GetOrCreate(string key, int width, int height, Action<SKCanvas> render);
}
```

### TextRenderCache

Caches rendered text for performance.

```csharp
public class TextRenderCache : IDisposable
{
    public int MaxEntries { get; set; }
    public SKBitmap GetOrCreate(string text, SKPaint paint);
    public void Clear();
}
```

## Event Args

### TextChangedEventArgs

```csharp
public class TextChangedEventArgs : EventArgs
{
    public string OldTextValue { get; }
    public string NewTextValue { get; }
}
```

### ValueChangedEventArgs

```csharp
public class ValueChangedEventArgs : EventArgs
{
    public double OldValue { get; }
    public double NewValue { get; }
}
```

### PointerEventArgs

```csharp
public class PointerEventArgs : EventArgs
{
    public float X { get; }
    public float Y { get; }
    public PointerButton Button { get; }
    public bool Handled { get; set; }
}
```

## Enumerations

### DisplayServerType

```csharp
public enum DisplayServerType
{
    Auto,
    X11,
    Wayland
}
```

### FlyoutLayoutBehavior

```csharp
public enum FlyoutLayoutBehavior
{
    Default,
    Popover,
    Split,
    SplitOnLandscape,
    SplitOnPortrait
}
```

### ShellFlyoutBehavior

```csharp
public enum ShellFlyoutBehavior
{
    Disabled,
    Flyout,
    Locked
}
```

### AccessibleRole

```csharp
public enum AccessibleRole
{
    Unknown, Window, Application, Panel, Frame, Button,
    CheckBox, RadioButton, ComboBox, Entry, Label,
    List, ListItem, Menu, MenuItem, ScrollBar,
    Slider, StatusBar, Tab, Text, ProgressBar,
    // ... and more
}
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `MAUI_DISPLAY_SERVER` | Force display server: `x11`, `wayland`, or `auto` |
| `MAUI_INPUT_METHOD` | Force IME: `ibus`, `xim`, or `none` |
| `GTK_A11Y` | Set to `none` to disable accessibility |

## System Requirements

- .NET 8.0 or .NET 9.0
- Linux with X11 or Wayland
- libX11 (for X11 support)
- libwayland-client (for Wayland support)
- libibus-1.0 (optional, for IBus IME)
- libatspi (optional, for accessibility)