README_en.md

LVGLSharp

中文 | English

LVGLSharp is a cross-platform WinForms-style UI stack built on top of LVGL. The main application-facing package is LVGLSharp.Forms, while the rest of the package lineup separates runtime hosting, native assets, low-level bindings, and supporting infrastructure.

Repository development baseline: 9.5.0.5

• Documentation: https://lvglsharp.net/
• Roadmap: https://github.com/IoTSharp/LVGLSharp/blob/main/ROADMAP.md
• Changelog: https://github.com/IoTSharp/LVGLSharp/blob/main/CHANGELOG.md

The project is still evolving quickly and should be evaluated carefully before production use.

Features

• WinForms-style API compatibility with Control, Form, Button, Label, TextBox, CheckBox, RadioButton, ComboBox, ListBox, PictureBox, Panel, GroupBox, FlowLayoutPanel, TableLayoutPanel, ProgressBar, TrackBar, NumericUpDown, RichTextBox, and related control infrastructure.
• Full LVGL interop through LVGLSharp.Interop, generated with ClangSharpPInvokeGenerator so the complete LVGL C API remains reachable from .NET.
• Layered runtime packages for Windows, Linux, Headless, macOS, and Remote paths, with current stable emphasis on Windows, Linux, and Headless flows.
• NativeAOT-friendly publishing and multi-RID native asset distribution through LVGLSharp.Native.
• Automatic runtime registration through buildTransitive when runtime packages are referenced.
• Cross-platform drawing primitives via LVGLSharp.Drawing without a dependency on System.Drawing.

Preview

The screenshots below come from the captured demo output under docs/images.

12-Package Lineup

The repository currently maintains a 12-package line, and the table below uses live NuGet badges for version and download counts across the full list.

Package	Version	Downloads	Status	Description
LVGLSharp.Forms			Published on NuGet	Main WinForms-style application package and runtime-registration entry point.
LVGLSharp.Core			Published on NuGet	Shared runtime abstractions, fonts, diagnostics, and host helpers.
LVGLSharp.Drawing			Published on NuGet	Cross-platform drawing primitives used by runtimes and UI layers.
LVGLSharp.Interop			Published on NuGet	Auto-generated low-level LVGL P/Invoke bindings.
LVGLSharp.Native			Published on NuGet	RID-specific native LVGL assets and publish-time targets.
LVGLSharp.Runtime.Windows			Published on NuGet	Windows desktop runtime with Win32 hosting support.
LVGLSharp.Runtime.Linux			Published on NuGet	Linux runtime covering WSLg, X11, Wayland, SDL, and FrameBuffer paths.
LVGLSharp.Runtime.Headless			Published on NuGet	Headless runtime for offscreen rendering, snapshots, and automation.
LVGLSharp.Runtime.MacOs			Published on NuGet	Early macOS runtime package with diagnostics and host scaffolding.
LVGLSharp.Runtime.Remote			Published on NuGet	Remote-session abstractions, frame transport, and VNC/RDP-oriented runtime pieces.
LVGLSharp.WPF			Published on NuGet	WPF-like bootstrap and XAML runtime loader built on top of LVGLSharp.Forms and LVGLSharp.Runtime.Windows.
LVGLSharp.Analyzers			Published on NuGet	Roslyn analyzers that validate runtime-package usage and related build-time patterns.

All 12 packages are now documented and maintained as published packages, with live NuGet badges used for versions and download counts across the full list.

LVGLSharp.Forms already carries the analyzers transitively. In most applications you start with LVGLSharp.Forms plus the runtime package that matches the host you want.

Quick Start

1. Project file

The recommended starting point is the same multi-target pattern used by the demos in this repository:

<PropertyGroup>
  <TargetFrameworks>net10.0-windows;net10.0</TargetFrameworks>
</PropertyGroup>

<PropertyGroup Condition="'$(TargetFramework)' == 'net10.0-windows'">
  <UseWindowsForms>true</UseWindowsForms>
</PropertyGroup>

<PropertyGroup Condition="'$(TargetFramework)' == 'net10.0'">
  <UseLVGLSharpForms>true</UseLVGLSharpForms>
  <PublishAot>true</PublishAot>
</PropertyGroup>

<ItemGroup Condition="'$(TargetFramework)' == 'net10.0'">
  <PackageReference Include="LVGLSharp.Forms" Version="*" />
  <PackageReference Include="LVGLSharp.Runtime.Windows" Version="*" />
  <PackageReference Include="LVGLSharp.Runtime.Linux" Version="*" />
</ItemGroup>

Add LVGLSharp.Runtime.Headless when you need snapshots or automation. Add LVGLSharp.Runtime.Remote or LVGLSharp.Runtime.MacOs only when you are intentionally exploring those paths.

2. Entry point

The UseLVGLSharpForms=true target uses the normal startup pattern:

ApplicationConfiguration.Initialize();
Application.Run(new MainForm());

3. Publish examples

dotnet publish -f net10.0 -r linux-arm64 -c Release
dotnet publish -f net10.0 -r linux-x64 -c Release
dotnet publish -f net10.0-windows -r win-x64 -c Release

Current Runtime Status

Area	Status	Notes
WinForms compatibility layer	Usable	Core controls, form lifecycle, and basic layout patterns are already available.
Windows runtime	Usable	One of the current stable host paths.
Linux WSLg / X11	Usable	Main desktop-side Linux validation path.
Linux FrameBuffer	Usable	Main device-side Linux path.
Linux Wayland / SDL	Experimental	Implemented, but still needs more validation and release discipline.
Headless Offscreen	Usable	Supports PNG snapshots, screenshots, and regression-entry scenarios.
Linux DRM/KMS	Scaffolded	DrmView exists, but the native backend still needs to be completed.
macOS runtime	Early package boundary	Diagnostics, context, and surface/frame-buffer scaffolding are in the repository and package.
Remote runtime	Early package boundary	VNC / RDP abstractions, sessions, and transport skeletons are present.

See the roadmap for the fuller engineering status and priority order.

Community

The documentation site, Issues, and the WeChat group are all valid ways to discuss usage, cross-platform adaptation, and troubleshooting.

License

This project is licensed under the MIT License.