Dialog settings

Customize picker and saver dialogs per platform with FileKitDialogSettings

FileKitDialogSettings customizes the file picker, directory picker, gallery picker, and file saver. Each platform has its own constructor, so build custom settings in platform code. FileKitDialogSettings.createDefault() works everywhere.

​

Settings

title · String? · default: "null" · JVM · macOS · Linux native · Windows native

Dialog title. macOS shows it as the panel message. Some save dialogs ignore it: see File saver.

parent · FileKitDialogParent? · default: "null" · JVM

Window that owns the dialog, for modality and stacking. See Parent window (JVM).

macOS · FileKitMacOSSettings · default: "FileKitMacOSSettings()" · JVM on macOS

Native panel options when a JVM app runs on macOS.

Show properties

canCreateDirectories · Boolean · default: "true"

Shows the New Folder button.

resolvesAliases · Boolean? · default: "null"

Alias resolution in open panels. null keeps the system behavior.

canCreateDirectories · Boolean · default: "true" · macOS native

Shows the New Folder button.

assetRepresentationMode · FileKitAssetRepresentationMode · default: "Automatic" · iOS

Photos picker format: Automatic, Current (avoid transcoding), or Compatible (transcode to a widely supported format, for example when a library can’t decode HEIC).

presenter · UIViewController? · default: "null" · iOS

View controller that presents the dialog. When null, the suspend API uses the top-most view controller and Compose launchers use the current LocalUIViewController.

title, canCreateDirectories · iOS

Accepted for parity, currently ignored.

Android and the web have no settings: use createDefault().

​

Share settings across platforms

Declare a function in commonMain and implement it per platform:

commonMain

expect fun createDialogSettings(): FileKitDialogSettings

Shared code then passes the result to any dialog:

suspend fun pickDocument(): PlatformFile? =
    FileKit.openFilePicker(dialogSettings = createDialogSettings())

​

Parent window (JVM)

Inside a Compose Desktop Window, the WindowScope versions of rememberFilePickerLauncher, rememberDirectoryPickerLauncher, and rememberFileSaverLauncher parent the dialog to that window, replacing any parent in your settings.

Elsewhere, pass the parent yourself:

jvmMain

fun dialogSettingsFor(window: java.awt.Window) = FileKitDialogSettings(
    parent = FileKitDialogParent.awt(window),
)

FileKitDialogParent also has windows(hwnd), x11(xid), and wayland(exportedHandle) factories for non-AWT windows. FileKit borrows the parent: keep the window alive until the dialog call returns. Invalid factory arguments and a parent the active dialog can’t use both throw IllegalArgumentException.

Supported parents per JVM dialog

Active JVM dialog	Accepted parents	Notes
Windows	AWT, Windows HWND, or none	An AWT window is resolved to an HWND when the dialog opens.
Linux XDG portal	AWT, X11 XID, Wayland export, or none	X11 identifiers are sent as lowercase hexadecimal.
Linux AWT fallback	AWT Frame or Dialog, or none	An X11 or Wayland parent fails when the portal is unavailable; it is not dropped silently.
Linux Swing directory fallback	Any AWT Window, or none	X11 and Wayland parents are not compatible.
macOS	AWT, or none	The dialog is application-modal, not a window-modal sheet.

Wayland handles

wayland() takes the unprefixed opaque handle exported through xdg_foreign. FileKit adds the wayland: portal prefix without normalizing the value. A raw wl_surface*, a Tao handle, or a string built from a pointer is not an exported Wayland handle. Empty handles and handles containing NUL are rejected.

Nucleus with the Tao backend

Nucleus 2.3.2 exposes the native identities needed to parent dialogs on Windows and Linux/X11. Convert the window yourself and pass the settings to a plain (non-WindowScope) launcher:

jvmMain

private fun NucleusWindow.fileKitDialogParent(): FileKitDialogParent? {
    unsafe.awtWindow?.let { return FileKitDialogParent.awt(it) }

    return when (Platform.Current) {
        Platform.Windows -> unsafe.taoWindow
            ?.nativeHandle
            ?.takeIf { it != 0L }
            ?.let(FileKitDialogParent::windows)
        Platform.Linux -> unsafe.taoWindow
            ?.x11WindowId
            ?.let(FileKitDialogParent::x11)
        else -> null
    }
}

val settings = FileKitDialogSettings(parent = nucleusWindow.fileKitDialogParent())

Don’t pass nucleusWindow.unsafe.taoHandle: it identifies the Tao event loop, not an operating-system window. On Wayland, x11WindowId is null, so this adapter opens an unparented dialog. The dialog is also unparented until the Nucleus window exposes a supported identity.

​

Other settings classes

Class	Used by	Properties
FileKitOpenCameraSettings	Camera picker	Android authority, iOS presenter
FileKitShareSettings	Share file	Android authority, addOptionChooseIntent; iOS presenter, addOptionUIActivityViewController, metaTitle
FileKitOpenFileSettings	Open with default app	Android authority

Upgrading from older versions

FileKit 0.15 replaced the JVM parentWindow property. Replace FileKitDialogSettings(parentWindow = window) with FileKitDialogSettings(parent = FileKitDialogParent.awt(window)). There is no compatibility property or constructor.

​

Related

• File picker
• Directory picker
• File saver