Dialog settings

Customize the dialogs with platform-specific settings

FileKit allows you to customize dialog behavior with platform-specific settings. Each platform has its own settings class that can be configured according to your needs.

Platform-Specific Settings

JVM Settings

On JVM platforms (Windows, macOS, Linux), you can customize:

• title: Set a custom title for the dialog
• parent: Set the typed parent window identity used for modality and stacking
• macOS: Configure macOS-specific settings

val settings = FileKitDialogSettings(
    title = "Select a file",
    parent = FileKitDialogParent.awt(window),
    macOS = FileKitMacOSSettings(
        resolvesAliases = false,
        canCreateDirectories = true
    )
)

FileKitDialogParent represents one canonical parent, with factories for each supported JVM window system:

FileKitDialogParent.awt(window)
FileKitDialogParent.windows(hwnd)
FileKitDialogParent.x11(xid)
FileKitDialogParent.wayland(exportedHandle)

The parent is borrowed. Keep the AWT window, HWND, X11 window, or Wayland export alive until the suspending picker call completes. FileKit never takes ownership or extends its lifetime.

Active JVM picker	Accepted parents	Notes
Windows	AWT, Windows HWND, or no parent	An AWT window is resolved to an HWND when the dialog opens.
Linux XDG portal	AWT, X11 XID, Wayland export, or no parent	X11 identifiers are sent as lowercase hexadecimal.
Linux AWT fallback	AWT Frame/Dialog, or no parent	A native X11 or Wayland parent fails if the portal is unavailable; it is not silently dropped.
Linux Swing directory fallback	Any AWT Window, or no parent	Native X11 and Wayland parents are not compatible.
macOS on JVM	AWT, or no parent	The current runModal() implementation is application-modal and does not establish a window-modal sheet.

wayland() accepts the unprefixed opaque handle exported through xdg_foreign. FileKit adds the wayland: portal prefix without trimming or normalizing the value. A raw wl_surface*, a Tao handle, and a string that you invented from a pointer are not exported Wayland handles.

Invalid factory arguments, such as a zero HWND, an out-of-range XID, or an empty Wayland handle, throw IllegalArgumentException. A valid parent that the active picker cannot use, or an AWT parent that cannot resolve to a native identifier, throws FileKitPickerException before opening the dialog.

Compose Desktop

The WindowScope.remember*Launcher extensions automatically use the scope’s AWT window and replace any parent already present in the supplied settings. For a plain launcher or direct picker call, provide it explicitly:

Window(onCloseRequest = ::exitApplication) {
    val dialogSettings = FileKitDialogSettings(
        parent = FileKitDialogParent.awt(this.window)
    )
    App(dialogSettings)
}

Migrating from FileKit 0.14

The JVM settings API intentionally changed in FileKit 0.15. Replace:

FileKitDialogSettings(parentWindow = window)

with:

FileKitDialogSettings(parent = FileKitDialogParent.awt(window))

There is no compatibility parentWindow property or constructor.

Nucleus with the Tao backend

Nucleus 2.3.2 exposes the native identities needed to parent Tao dialogs on Windows and Linux/X11. Adapt the framework-specific window locally and pass the resulting settings to a plain, non-WindowScope launcher:

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())
val launcher = rememberFilePickerLauncher(
    dialogSettings = settings,
    onError = { failure -> showError(failure.message) },
    onResult = { file ->
        // Use the selected file, or null when the user cancelled.
    },
)

Do not pass nucleusWindow.unsafe.taoHandle: it is an opaque Tao event-loop identity, not an operating-system dialog parent. On Wayland, x11WindowId is null, so this adapter deliberately opens an unparented dialog. Wayland parent exports and macOS NSWindow sheets are deferred pending community feedback; both require lifecycle handling beyond these direct Windows and X11 conversions. The dialog also remains unparented when the Nucleus window has not exposed a supported identity yet.

iOS and macOS Settings

On iOS and macOS, you can configure:

• title: Set a custom title for the dialog
• canCreateDirectories: Allow or prevent directory creation in dialogs (default: true)

On iOS, you can also configure:

• assetRepresentationMode: Choose the Photos picker asset representation mode (default: Automatic)
• presenter: Set the UIViewController used to present native dialogs. If null, FileKit uses the current top-most controller.

val settings = FileKitDialogSettings(
    title = "Save document",
    canCreateDirectories = true,
    assetRepresentationMode = FileKitAssetRepresentationMode.Automatic
)

The iOS Photos picker supports these asset representation modes:

• Automatic: Let the system choose the best representation
• Current: Prefer the original/current representation and avoid transcoding when possible
• Compatible: Prefer a broadly compatible representation, even if transcoding is required

Use Compatible when picked image bytes need to be decoded by libraries that may not support every Apple-native image format, such as HEIF/HEIC.

Android, Web, and WASM

These platforms currently don’t have any specific settings to configure. Use the default settings:

val settings = FileKitDialogSettings.createDefault()

Using DialogSettings in KMP

When working with Kotlin Multiplatform projects, you might need to handle platform-specific settings differently. Here’s how to use expect/actual to manage dialog settings:

For platforms that need specific configuration, use expect/actual:

// commonMain
expect fun createDialogSettings(): FileKitDialogSettings

// desktopMain
actual fun createDialogSettings(): FileKitDialogSettings {
    return FileKitDialogSettings(
        title = "Select a file",
        parent = FileKitDialogParent.awt(window),
        macOS = FileKitMacOSSettings(
            canCreateDirectories = true
        )
    )
}

// iosMain
actual fun createDialogSettings(): FileKitDialogSettings {
    return FileKitDialogSettings(
        assetRepresentationMode = FileKitAssetRepresentationMode.Automatic
    )
}

// androidMain, jsMain
actual fun createDialogSettings(): FileKitDialogSettings {
    return FileKitDialogSettings.createDefault()
}

You can then use the platform-specific settings in your shared code:

class SharedViewModel {
    private val dialogSettings = createDialogSettings()
    
    suspend fun pickFile() {
        FileKit.openFilePicker(
            dialogSettings = dialogSettings
        )
    }
}

This approach allows you to:

• Keep your common code platform-agnostic
• Provide platform-specific configurations where needed
• Maintain type safety across platforms

Platform-specific settings are continuously evolving. You can ask for a feature or report a bug on the GitHub repository.