Warning

🚧 WORK IN PROGRESS (WIP) — Active Native Engine & Win32 Integration

• Active Calibration: Native Windows 11 Shell COM and Win32 interfaces (IFileOpenDialog, IFileSaveDialog, IProgressDialog, TaskDialogIndirect, and CredUI) are undergoing active testing and calibration across Windows 10 and 11 builds.
• FastJava Integration: FastDialog is designed as the zero-dependency, ultra-fast native system dialog runtime for the FastJava Suite, seamlessly integrating with FastWindow, FastTheme, and FastCore.

FastDialog 0.1.0 [ALPHA-2026-10-14] — Native Windows 11 Shell & COM Dialog Engine for Java

---

⚡ High-performance native Windows 10/11 Shell & COM dialog engine for Java.

FastDialog brings authentic Windows 11 Explorer dialogs directly to Java Swing, AWT, OpenGL, and CLI applications. It connects directly with the Windows Shell COM engine (IFileOpenDialog and IFileSaveDialog) to provide modern file pickers, multi-selection, folder pickers, and save dialogs with breadcrumb navigation, Quick Access / OneDrive pins, and native OS modality.

---

Quick Start

1. Modern Windows 11 Open File Dialog

import fastdialog.FastDialog;
import fastdialog.DialogFilter;

public class Demo {
    public static void main(String[] args) {
        // Open native Windows 11 file dialog with breadcrumbs and Quick Access
        String selectedFile = FastDialog.openFile(
            0, // Optional parent HWND
            "Select Source File",
            System.getProperty("user.home"),
            new DialogFilter("Java & Kotlin (*.java;*.kt)", "*.java;*.kt"),
            new DialogFilter("All Files (*.*)", "*.*")
        );

        if (selectedFile != null) {
            System.out.println("Selected: " + selectedFile);
        }
    }
}

2. Multi-File Selection

String[] files = FastDialog.openFiles(
    0,
    "Select Multiple Files",
    "C:\\Projects",
    new DialogFilter("Text Files (*.txt;*.md)", "*.txt;*.md")
);

3. Folder Picker

String folder = FastDialog.openFolder(0, "Choose Directory", "C:\\");

4. Save File Dialog with Extension Enforcement

String savePath = FastDialog.saveFile(
    0,
    "Export Report",
    System.getProperty("user.home"),
    "report.pdf",
    "pdf",
    new DialogFilter("PDF Documents (*.pdf)", "*.pdf")
);

---

Table of Contents

• Why FastDialog?
• Quick Start
• Key Features
• Real-World Use Cases
• Performance Benchmarks
• API Quick Reference
• Technical Demos & Benchmarks
• Installation
• Documentation
• Platform Support
• License
• Related Projects

---

Why FastDialog?

Standard Java dialogs (JFileChooser, java.awt.FileDialog) and Swing Look & Feels (like FlatLaf) either simulate file pickers in pure Java or rely on legacy Windows 95/2000 Win32 APIs. They lack modern Windows 11 Shell features, cause freezes on cloud drives (OneDrive), and introduce heavy heap allocation.

FastDialog bridges Java directly to the modern Windows 11 Shell COM architecture (IFileOpenDialog / IFileSaveDialog):

1. Authentic Windows 11 Fluent Chrome — Real OS Explorer dialogs featuring breadcrumb path bars, Quick Access pins, search, and native dark/light mode.
2. Direct Shell Namespace Integration — First-class handling of cloud storage (OneDrive, Dropbox) and network shares without JVM I/O thread freezes.
3. Unlimited Multi-Selection — Replaces fragile fixed-size C buffers with native IShellItemArray enumeration.
4. Deterministic & Lightweight — Instant sub-microsecond COM instantiation with zero GC allocation beyond the returned path strings.

Feature	Java Swing / FlatLaf	AWT FileDialog (Legacy Win32)	FastDialog (IFileOpenDialog)
Windows 11 UI & Shell	❌ Emulated Swing Component	❌ Legacy Win95/2000 style	✅ Authentic Windows 11 Fluent Explorer
Breadcrumbs & Quick Access	❌ Missing	❌ Missing	✅ Native Breadcrumbs & Pins
OneDrive & Cloud Drives	⚠️ Freezes on File I/O	⚠️ Inconsistent	✅ Native Shell Namespace
Folder Selection	❌ Clunky Swing tree	❌ Unsupported on Windows	✅ Dedicated Picker (FOS_PICKFOLDERS)
Multi-Selection Capacity	⚠️ High Heap Allocation	❌ Fixed buffer overflow risk	✅ Dynamic IShellItemArray
Footprint & Overhead	Heavy Swing widget tree	AWT peer allocations	Zero GC / Pure FastCore native loader

---

Key Features

• 🪟 Real Windows 11 Explorer Chrome — Direct COM instantiation of IFileOpenDialog and IFileSaveDialog.
• 📂 Multi-Selection — Efficient bulk file resolution via native IShellItemArray.
• 📁 Native Folder Picker — Clean folder selection using FOS_PICKFOLDERS.
• 🛡️ Modal Window Anchoring — Pass any native window handle (HWND) from FastTheme, FastWindow, or AWT to anchor the dialog modally.
• ⚡ Zero Bloat — Lightweight package requiring only Java 17+ and FastCore.

---

Real-World Use Cases

• 🛠️ Desktop Tooling & IDEs: Open project workspaces and multi-select source trees without Swing look-and-feel discrepancies.
• 🎨 Creative Studios & Asset Managers: Import bulk image/audio textures directly through Windows 11 Quick Access and cloud folders (OneDrive/Dropbox).
• 💾 Safe Export Pipelines: Save documents with enforced file extensions (.pdf, .json, .png) and native OS overwrite prompts (FOS_OVERWRITEPROMPT).
• ⚡ Lightweight CLI & TUI Tools: Spawn native Windows file pickers directly from console apps without loading massive Swing/AWT window trees into memory.

---

Performance Benchmarks

FastDialog is rigorously profiled using OpenJDK JMH (Java Microbenchmark Harness) to guarantee minimal dispatch latency and zero garbage collection pressure compared to heavyweight Swing widget hierarchies:

Benchmark Operation	Score (ops/ms)	Ops per Second	Memory Allocation
Native Bridge Availability (isNativeAvailable)	> 380,000 ops/ms	> 380 Million	0 bytes / op (Zero GC)
Filter Spec Traversal & Construction	> 12,000 ops/ms	> 12 Million	Sub-microsecond
Shell COM Instantiation (IFileOpenDialog)	< 1 µs	Direct Win32 COM dispatch	0 bytes JVM Heap (Off-Heap COM)

Run the benchmarks locally:

.\run-benchmark.bat

---

API Quick Reference

FastDialog Facade (fastdialog.FastDialog)

Method / Signature	Return Type	Description	Docs
FastDialog.openFile (hwnd, title, folder, filters...)	String	Opens modern Windows 11 file open dialog; returns absolute path or null.	Reference
FastDialog.openFileObj (hwnd, title, folder, filters...)	File	Same as openFile but returning a standard java.io.File.	Reference
FastDialog.openFiles (hwnd, title, folder, filters...)	String[]	Opens multi-select file dialog; returns array of selected paths.	Reference
FastDialog.saveFile (hwnd, title, folder, name, ext, filters...)	String	Opens modern Windows 11 save file dialog with overwrite prompt.	Reference
FastDialog.openFolder (hwnd, title, folder)	String	Opens native Windows folder picker dialog (FOS_PICKFOLDERS).	Reference
FastDialog.showTaskDialog (hwnd, title, instr, content, btns, icon)	int	Shows modern Windows 10/11 TaskDialog; returns pressed button ID.	Reference
FastDialog.showTaskDialog (hwnd, title, instr, content, details, check, links, icon)	TaskDialogResponse	Shows TaskDialog with Command Links, expandable details, and checkbox.	Reference
FastDialog.showInfo (title, instruction, content)	void	Displays modern information TaskDialog.	Reference
FastDialog.showConfirm (hwnd, title, instr, content)	boolean	Displays modern confirmation TaskDialog (returns true for YES).	Reference
FastDialog.createProgress (hwnd, title, line1)	NativeProgress	Starts asynchronous native Windows Progress Dialog (IProgressDialog).	Reference
FastDialog.promptCredentials (hwnd, title, message)	DialogCredentials	Native Windows Security dialog (Windows Hello / PIN / Password).	Reference
FastDialog.openWith (hwnd, filePath)	boolean	Native Windows "How do you want to open this file?" dialog (SHOpenWithDialog).	Reference
FastDialog.showAbout (hwnd, appTitle, info, iconPath)	boolean	Official native Windows About dialog (ShellAboutW).	Reference
FastDialog.pickColor (hwnd, initialRgb)	int	Native Windows Color Chooser (ChooseColorW); returns 32-bit ARGB.	Reference
FastDialog.pickFont (hwnd, initialFont)	DialogFont	Native Windows Font Chooser (ChooseFontW); returns selected font.	Reference
FastDialog.showInFolder (filePath)	boolean	Opens Windows Explorer and selects/highlights target file.	Reference
FastDialog.showProperties (hwnd, filePath)	boolean	Invokes native Windows Properties sheet for file or directory.	Reference
FastDialog.isNativeAvailable()	boolean	Checks if native fastdialog.dll JNI bridge is loaded and ready.	Reference

---

Technical Demos & Benchmarks

Case	Java Example	Launcher	Description
Windows 11 Open File Dialog	Demo.java	run-demo.bat	Interactive demonstration of modern Windows 11 file open dialog with breadcrumbs.
Windows 11 Multi-File Selection	MultiFile.java	run-demo-multi.bat	Bulk selection and extraction of multiple file paths via native IShellItemArray.
Windows 11 Folder Picker	Folder.java	run-demo-folder.bat	Dedicated Windows 11 directory picker using FOS_PICKFOLDERS.
Windows 11 Save File Dialog	Save.java	run-demo-save.bat	Native save file dialog with default suggested name, enforced extension, and overwrite warning.
Windows 10/11 Modern TaskDialog	TaskDialogDemo.java	run-demo-taskdialog.bat	Modern Windows TaskDialog with prominent header, body text, and icons.
Command Links & Details TaskDialog	CommandLinksDemo.java	run-demo-commandlinks.bat	TaskDialog with Windows Command Links buttons, expandable details, and checkbox.
Native Windows Progress Dialog	ProgressDemo.java	run-demo-progress.bat	Asynchronous Win32/COM progress bar with animated status, time estimation, and cancel button.
Windows Security Credentials	CredentialsDemo.java	run-demo-credentials.bat	Official Windows Security UI (Windows Hello, PIN, Username & Password).
Native "Open With" Dialog	OpenWithDemo.java	run-demo-openwith.bat	Windows 10/11 system dialog prompting the user to choose an application to open a file.
Native Windows About Box	AboutDemo.java	run-demo-about.bat	Official system About dialog with custom title, copyright, and icon.
Windows Native Color Chooser	ColorPicker.java	run-demo-color.bat	Native ChooseColorW returning 32-bit packed ARGB integer.
Windows Shell Reveal & Properties	ExplorerOps.java	run-demo-explorer.bat	"Reveal in Explorer" (SHOpenFolderAndSelectItems) and native Properties sheet.
Windows Native Font Chooser	FontPicker.java	run-demo-font.bat	Native ChooseFontW returning font family, size in pt, bold, and italic state.
JMH Microbenchmark Suite	Benchmark.java	run-benchmark.bat	Formal OpenJDK JMH throughput measurements across native JNI bridge and filter specs.

---

Installation

Option 1: Maven (Recommended)

Add the JitPack repository and dependencies to your pom.xml:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <!-- Core FastDialog Engine -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>FastDialog</artifactId>
        <version>0.1.0</version>
    </dependency>
    <!-- Required Native JNI loader -->
    <dependency>
        <groupId>com.github.andrestubbe</groupId>
        <artifactId>fastcore</artifactId>
        <version>0.1.0</version>
    </dependency>
</dependencies>

Option 2: Gradle (via JitPack)

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.github.andrestubbe:FastDialog:0.1.0'
    implementation 'com.github.andrestubbe:fastcore:0.1.0'
}

Option 3: Direct Download (No Build Tool)

Download the pre-built JARs directly to add them to your classpath:

1. 📦 FastDialog-0.1.0.jar (Core Library & Native DLL)
2. ⚙️ FastCore-0.1.0.jar (Required Native JNI loader)

---

Documentation

• REFERENCE.md: Exhaustive method contracts, parameters, and filter structures.
• PHILOSOPHY.md: Shell COM architecture vs. legacy Win32 / Swing design.
• ROADMAP.md: Planned milestone features (color pickers, font dialogs, print dialogs).
• CHANGELOG.md: Release notes and version history.
• COMPILE.md: Compilation guide for C++ native bridge and Java sources.

---

Platform Support

Platform	Architecture	Status	Notes
Windows 10/11	x64	✅ Fully Supported	Native COM IFileOpenDialog & IFileSaveDialog
Linux / macOS	Any	🟡 Backlog	Planned native portal / file chooser integration

---

License

MIT License — See LICENSE for details.

---

Related Projects

• FastTheme — Native Windows 11 styling, Mica/Acrylic backdrops & theming
• FastCore — High-speed native JNI library loader
• FastWindow — Lightweight Win32 native windowing engine
• FastUI — High-Performance GUI Framework

---

Part of the FastJava Ecosystem — Making the JVM faster. Small package. Maximum speed. Zero bloat. 🚀📋