native_core 1.0.1
native_core: ^1.0.1 copied to clipboard
Zero-dependency desktop window, display, and single-instance lifecycle primitives for Flutter across Linux, macOS, and Windows.
native_core #
Zero-dependency desktop window, display, and single-instance lifecycle primitives for Flutter across Linux, macOS, and Windows.
native_core replaces nativeapi, window_manager, and screen_retriever with pure dart:ffi bindings to OS system libraries and zero external hosted dependencies — requiring zero modifications to stock flutter create host runner files.
| Platform | Support | Implementation |
|---|---|---|
| Linux | GTK 3.24+ (X11 & Wayland) |
libgtk-3.so.0, libgdk-3.so.0, libgobject-2.0.so.0, libgio-2.0.so.0 |
| macOS | macOS 13.0+ (arm64 & x86_64) |
/usr/lib/libobjc.A.dylib, AppKit, CoreGraphics |
| Windows | Windows 10 / 11 (x64 & arm64) |
user32.dll, comctl32.dll, dwmapi.dll, gdi32.dll, shcore.dll, kernel32.dll |
Platform Capability Matrix #
| Capability | Linux (GTK3) |
macOS (AppKit) |
Windows (Win32) |
|---|---|---|---|
Custom frameless window (TitleBarStyle.hidden) |
✅ (hideLinuxNativeTitleBar) |
✅ (FullSizeContentView) |
✅ (SetWindowSubclass + DWM) |
| Hidden/tray window resolution & foreground focus | ✅ (X11 server time) | ✅ (activate + orderFrontRegardless) |
✅ (FLUTTER_RUNNER_WIN32_WINDOW + AttachThreadInput) |
Multi-monitor bounds, workArea, DPI scaleFactor |
✅ (GdkMonitor) |
✅ (NSScreen + CoreGraphics fallback) |
✅ (EnumDisplayMonitors + GetDpiForMonitor) |
Single-instance guard + secondary IPC (ensureSingleInstance) |
✅ (Unix Domain Socket) | ✅ (Unix Domain Socket) | ✅ (Named Mutex + WM_COPYDATA) |
Interactive window drag (startPlatformWindowDragging) |
✅ (with GDK_BUTTON_RELEASE) |
✅ (performWindowDragWithEvent:) |
✅ (WM_NCLBUTTONDOWN / HTCAPTION) |
Native erase background brush (backgroundColor) |
Stored in memory | Stored in memory | ✅ (GDI brush on WM_ERASEBKGND) |
Native window system menu (showSystemMenu) |
Returns false |
Returns false |
✅ (GetSystemMenu + TrackPopupMenu) |
Features #
- Zero External Dependencies: Depends exclusively on the Flutter SDK (
flutter). - Self-Contained Custom Frameless Windows (
TitleBarStyle.hidden):- Windows:
SetWindowSubclasshandlesWM_NCCALCSIZE, DWM shadow & rounded corners, 8-direction resize hit-testing (preserving Fitts's Law top-right corner clicks when maximized),WM_GETMINMAXINFOminimumSizeenforcement,WM_ERASEBKGNDWHITE_BRUSHflash suppression without live DXGI resize strobe flicker, andWM_WINDOWPOSCHANGINGcoordination with stockflutter_window.cpp(SetNextFrameCallback). - macOS: Combines
NSWindowTitleHidden,setTitlebarAppearsTransparent:YES, andNSWindowStyleMaskFullSizeContentView(1 << 15), with Hot Restart-safeNativeCoreWindowDelegatemethod rebinding. - Linux: Directly hides
GtkHeaderBar(hideLinuxNativeTitleBar) without adding 132px CSD shadow gutters on Wayland, and synthesizesGDK_BUTTON_RELEASEafter native grabs (startPlatformWindowDragging,showPlatformWindowSystemMenu).
- Windows:
- Configurable Single-Instance Process Guard (
Application.instance.ensureSingleInstance):- Supports both
InstanceMode.singleInstance(default) andInstanceMode.multiInstance. - Windows: Uses a session-scoped Named Mutex (
CreateMutexW+WaitForSingleObject(0)), delegates Foreground Lock viaAllowSetForegroundWindow, and forwards CLI arguments & working directory (SecondInstancePayload) viaWM_COPYDATA. - Linux & macOS: Uses a user-scoped Unix Domain Socket under the 104-byte BSD/macOS path limit with automatic
SIGKILLstale-socket recovery.
- Supports both
- Close-to-Tray Window Resolution & Foreground Restore (
mainWindow):- Resolves hidden (
SW_HIDE/orderOut:/gtk_widget_hide) primary windows reliably across all 3 desktop OSes and restores foreground focus.
- Resolves hidden (
- Multi-Monitor Work Areas (
DisplayManager): Queries physical monitorbounds, taskbar/dock-safeworkArea, and DPIscaleFactornormalized to a top-left desktop coordinate origin. - Optional Non-Fatal Diagnostics (
NativeCoreDiagnostics.onError): Zero-overhead in production (nullby default), with full operation context & stack traces when enabled during development.
Installation #
dependencies:
native_core: ^1.0.1
Quick Start #
import 'package:flutter/widgets.dart';
import 'package:native_core/native_core.dart';
Future<void> main(List<String> args) async {
WidgetsFlutterBinding.ensureInitialized();
final isPrimary = await Application.instance.ensureSingleInstance(
appId: 'com.example.desktop_workspace',
mode: args.contains('--multi-instance')
? InstanceMode.multiInstance
: InstanceMode.singleInstance,
arguments: args,
onSecondInstance: (payload) {
// Handle forwarded arguments from a secondary launch.
},
);
if (!isPrimary) return;
final window = mainWindow;
if (window != null) {
if (!hideLinuxNativeTitleBar(window)) {
window.titleBarStyle = TitleBarStyle.hidden;
}
window
..minimumSize = const NativeSize(640, 420)
..title = 'Desktop Workspace'
..center()
..show()
..focus();
}
runApp(const SizedBox.shrink());
}
License #
Apache License 2.0 — Copyright 2026 Infradise Inc. See LICENSE.