README
¶
filedialog
Native open/save/choose-directory panels, cgo-free.
path := filedialog.Open(filedialog.Options{
Title: "Open scene",
Extensions: []string{"afoil"},
})
if path != "" {
// user picked a file
}
out := filedialog.Save(filedialog.Options{
Title: "Save scene",
Filename: "untitled.afoil",
})
dir := filedialog.PickDirectory(filedialog.Options{
Title: "Choose migrations directory",
})
Each call returns the chosen path, or "" when the user cancels, when the
platform has no implementation, or when the panel cannot be shown (for example a
Linux process with no display). There is no error to inspect; a desktop app
treats all of those the same way — nothing was picked.
Threading
The panels are platform UI and must be called on the main thread. This package deliberately does not impose a threading model; the caller arranges to be on the main thread. For an Ebitengine app:
var path string
ebiten.RunOnMainThread(func() {
path = filedialog.Open(filedialog.Options{Extensions: []string{"afoil"}})
})
Platforms
| OS | Backend | Status |
|---|---|---|
| macOS | NSOpenPanel / NSSavePanel via the objc runtime (PickDirectory is NSOpenPanel in directory mode) |
✅ runs locally |
| Windows | Common Item Dialog (IFileOpenDialog / IFileSaveDialog, COM via purego) |
✅ builds + CI; not yet exercised on real hardware |
| Linux | GtkFileChooserNative (GTK3 or GTK4, chosen at runtime) |
✅ validated on real hardware (Debian 13, GTK3, xvfb) |
Linux notes
- GTK stack selection. Loading GTK3 and GTK4 into one process corrupts the
GObject type system, so the package first probes (
RTLD_NOLOAD, loads nothing) for a GTK the process already has — a glaze/GTK host app — and joins it. Only when neither is mapped does it load one fresh: GTK3 first, then GTK4. - Modal loop.
gtk_native_dialog_runwas removed in GTK4, so the modal is driven manually (set_modal+show+ theresponsesignal + main-loop iteration) — the same mechanismrunused internally, valid on both GTK3 and GTK4. - Headless. With no display
gtk_init_checkfails and every panel returns""instead of crashing; the package's GTK smoke test skips itself the same way (and runs for real under xvfb in CI).
Documentation
¶
Overview ¶
Package filedialog shows the operating system's native open, save, and choose-directory panels, cgo-free.
Threading: the panels are platform UI (AppKit, Win32/COM, GTK) and must be invoked on the program's main thread. This package does not impose a threading model — the caller is responsible for already being on the main thread. For example, an Ebitengine app wraps the call in ebiten.RunOnMainThread, and a webview host uses its own UI-thread dispatch.
Each function returns the chosen path, or "" when the user cancels, when the platform has no implementation, or when the panel cannot be shown (for example a Linux process with no display).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PickDirectory ¶ added in v0.1.8
PickDirectory shows a modal choose-directory panel and returns the chosen path ("" if cancelled).
Types ¶
type Options ¶
type Options struct {
// Title is the prompt shown prominently above the file list.
Title string
// Directory is the initial directory, as a filesystem path. Empty uses the
// platform default (usually the last-used directory).
Directory string
// Filename is the suggested file name. Used only by Save.
Filename string
// Extensions restricts selectable files to these extensions, given without
// the leading dot (e.g. {"afoil", "dat"}). Empty, or any "*"/"" entry,
// allows all files. Ignored by PickDirectory.
Extensions []string
}
Options configures a file panel. The zero value is valid: a default panel rooted at the platform's default directory with no type filtering.
Source Files