Package limn.backend

Interface FileDialogs

public interface FileDialogs

The platform's own file and folder choosers, owned by a window: NativeWindow.fileDialogs(). Each call opens the chooser tied to that window (a sheet on macOS, a dialog owned by it on Windows, the desktop portal's chooser parented to it on Linux) and returns at once; the answer completes the returned stage on the UI thread when the user picks or cancels. The application keeps running meanwhile: its windows draw, animations advance, timers fire. UI thread only.

An empty answer means cancelled, and is also what a headless or embedded backend answers (NONE), so a caller needs no headless branch.

One at a time per window. A window shows one chooser, as the platforms do; a request made while one is open on the same window completes empty at once.

These are the platform's own panels, so how they look, where they appear, and which shortcuts and sidebar places they offer are the platform's to decide, not the toolkit theme's, and not this API's.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final record	FileDialogs.Filter	A file-name filter: a human-readable description plus glob patterns, e.g.

Field Summary

Fields

Modifier and Type	Field	Description
static final FileDialogs	NONE	Headless/embedded implementation: every dialog resolves empty at once, as if cancelled.

Method Summary

Modifier and Type	Method	Description
CompletionStage<Optional<Path>>	chooseFolder(String title, @Nullable Path initial)	Asks for an existing folder.
CompletionStage<Optional<Path>>	openFile(String title, @Nullable Path initial, @Nullable FileDialogs.Filter filter)	Asks for one existing file to open.
CompletionStage<List<Path>>	openFiles(String title, @Nullable Path initial, @Nullable FileDialogs.Filter filter)	Like openFile(java.lang.String, java.nio.file.Path, limn.backend.FileDialogs.Filter) allowing several files.
CompletionStage<Optional<Path>>	saveFile(String title, @Nullable Path initial, @Nullable FileDialogs.Filter filter)	Asks for a destination file to save to; the platform's chooser asks about overwriting.

Field Details

NONE

static final FileDialogs NONE

Headless/embedded implementation: every dialog resolves empty at once, as if cancelled.

Method Details

openFile

CompletionStage<Optional<Path>> openFile(String title,
 @Nullable Path initial,
 @Nullable FileDialogs.Filter filter)

Asks for one existing file to open.

Parameters:

title - dialog title

initial - initial path (a directory, or a file to preselect); null for the platform's default

filter - name filter, or null for all files

Returns:

the chosen file, or empty if cancelled, on the UI thread

openFiles

CompletionStage<List<Path>> openFiles(String title,
 @Nullable Path initial,
 @Nullable FileDialogs.Filter filter)

Like openFile(java.lang.String, java.nio.file.Path, limn.backend.FileDialogs.Filter) allowing several files.

Returns:

the chosen files, or an empty list if cancelled, on the UI thread

saveFile

CompletionStage<Optional<Path>> saveFile(String title,
 @Nullable Path initial,
 @Nullable FileDialogs.Filter filter)

Asks for a destination file to save to; the platform's chooser asks about overwriting.

Parameters:

initial - a directory, or a file name or path to suggest; null for the default

Returns:

the chosen destination, or empty if cancelled, on the UI thread

chooseFolder

CompletionStage<Optional<Path>> chooseFolder(String title,
 @Nullable Path initial)

Asks for an existing folder.

Returns:

the chosen folder, or empty if cancelled, on the UI thread