maui-linux/docs/GETTING_STARTED.md

Getting Started with .NET MAUI on Linux

This guide will help you get started with building .NET MAUI applications for Linux.

Prerequisites

• .NET 9.0 SDK or later
• Linux distribution (Ubuntu 22.04+, Fedora 38+, Arch Linux, etc.)
• X11 or Wayland display server

Installing 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

Arch Linux:

sudo pacman -S libx11 libxrandr libxcursor libxi mesa fontconfig

Creating a New Project

Using the Template (Recommended)

1. Install the template:

dotnet new install OpenMaui.Linux.Templates

2. Create a new project:

dotnet new maui-linux -n MyApp
cd MyApp

3. Run your application:

dotnet run

Manual Setup

1. Create a new console application:

dotnet new console -n MyMauiLinuxApp
cd MyMauiLinuxApp

2. Add the NuGet package:

dotnet add package OpenMaui.Controls.Linux

3. Update your Program.cs:

using Microsoft.Maui.Platform;
using OpenMaui.Platform.Linux;

var app = new LinuxApplication();

app.MainPage = new ContentPage
{
    Content = new VerticalStackLayout
    {
        Children =
        {
            new Label { Text = "Hello, MAUI on Linux!" },
            new Button { Text = "Click Me" }
        }
    }
};

app.Run();

Project Structure

A typical MAUI Linux project has this structure:

MyApp/
├── App.cs              # Application entry and configuration
├── MainPage.cs         # Main page of your app
├── Program.cs          # Application bootstrap
├── MyApp.csproj        # Project file
└── Resources/          # Images, fonts, and other assets
    ├── Images/
    └── Fonts/

Basic Controls

All controls use standard .NET MAUI types (Color, Rect, Size, Thickness) for full API compliance.

Labels

using Microsoft.Maui.Graphics;

var label = new Label
{
    Text = "Hello World",
    TextColor = Color.FromRgb(33, 33, 33),  // MAUI Color
    FontSize = 16
};

Buttons

var button = new Button
{
    Text = "Click Me",
    BackgroundColor = Color.FromRgb(33, 150, 243)  // MAUI Color
};
button.Clicked += (s, e) => Console.WriteLine("Clicked!");

Text Input

var entry = new Entry
{
    Placeholder = "Enter text...",
    MaxLength = 100
};
entry.TextChanged += (s, e) => Console.WriteLine($"Text: {e.NewTextValue}");

Layouts

// Vertical stack
var vstack = new VerticalStackLayout
{
    Spacing = 10,
    Children =
    {
        new Label { Text = "Item 1" },
        new Label { Text = "Item 2" }
    }
};

// Horizontal stack
var hstack = new HorizontalStackLayout
{
    Spacing = 8
};

Advanced Controls

CarouselView

var carousel = new CarouselView
{
    Loop = true,
    PeekAreaInsets = new Thickness(20),
    ItemsSource = new[] { "Page 1", "Page 2", "Page 3" },
    ItemTemplate = new DataTemplate(() =>
    {
        var label = new Label();
        label.SetBinding(Label.TextProperty, ".");
        return label;
    })
};
carousel.PositionChanged += (s, e) =>
    Console.WriteLine($"Position: {e.CurrentPosition}");

RefreshView

var refreshView = new RefreshView
{
    Content = myScrollableContent,
    RefreshColor = Colors.Blue  // MAUI Color
};
refreshView.Refreshing += async (s, e) =>
{
    await LoadDataAsync();
    refreshView.IsRefreshing = false;
};

SwipeView

var swipeView = new SwipeView
{
    Content = new Label { Text = "Swipe me" }
};
swipeView.RightItems = new SwipeItems
{
    new SwipeItem
    {
        Text = "Delete",
        BackgroundColor = Colors.Red  // MAUI Color
    }
};

MenuBar

var menuBar = new MenuBar();
var fileMenu = new MenuBarItem { Text = "File" };
fileMenu.Add(new MenuFlyoutItem { Text = "New", KeyboardAccelerators = { new KeyboardAccelerator { Modifiers = KeyboardAcceleratorModifiers.Ctrl, Key = "N" } } });
fileMenu.Add(new MenuFlyoutItem { Text = "Open" });
fileMenu.Add(new MenuFlyoutSeparator());
fileMenu.Add(new MenuFlyoutItem { Text = "Exit" });
menuBar.Add(fileMenu);

Platform Services

Clipboard

var clipboard = new ClipboardService();
await clipboard.SetTextAsync("Copied text");
var text = await clipboard.GetTextAsync();

File Picker

var picker = new FilePickerService();
var result = await picker.PickAsync(new PickOptions
{
    FileTypes = new[] { ".txt", ".md" }
});

Notifications

var notifications = new NotificationService();
notifications.Show("Title", "Message body", "app-icon");

Global Hotkeys

var hotkeys = new GlobalHotkeyService();
hotkeys.Initialize();
int id = hotkeys.Register(HotkeyKey.F1, HotkeyModifiers.Control);
hotkeys.HotkeyPressed += (s, e) =>
{
    if (e.Id == id) Console.WriteLine("Ctrl+F1 pressed!");
};

Accessibility

High Contrast Mode

var highContrast = new HighContrastService();
highContrast.Initialize();
if (highContrast.IsHighContrastEnabled)
{
    var colors = highContrast.GetColors();
    // Apply high contrast colors to your UI
}

HiDPI Support

var hidpi = new HiDpiService();
hidpi.Initialize();
float scale = hidpi.ScaleFactor;
// Scale your UI elements accordingly

Building for Release

dotnet publish -c Release -r linux-x64 --self-contained

Or for ARM64:

dotnet publish -c Release -r linux-arm64 --self-contained

Troubleshooting

Display Issues

• Ensure X11 or Wayland is running
• Check that SkiaSharp native libraries are installed
• Verify graphics drivers are up to date

Font Rendering

• Install fontconfig and common fonts
• Set the FONTCONFIG_PATH environment variable if needed

Input Method (IME)

• For CJK input, ensure IBus or Fcitx is installed and configured
• Set GTK_IM_MODULE=ibus or QT_IM_MODULE=ibus

Next Steps

• Explore the API Documentation
• Check out the Sample Applications
• Read the Contributing Guide