> ## Documentation Index
> Fetch the complete documentation index at: https://filekit.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```kotlin theme={null}
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:

```kotlin theme={null}
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. |

<Note>
  `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.
</Note>

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:

```kotlin theme={null}
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:

```kotlin theme={null}
FileKitDialogSettings(parentWindow = window)
```

with:

```kotlin theme={null}
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:

```kotlin theme={null}
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.

```kotlin theme={null}
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:

```kotlin theme={null}
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**:

```kotlin theme={null}
// 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:

```kotlin theme={null}
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

<Note>
  Platform-specific settings are continuously evolving. You can ask for a feature or report a bug on the [GitHub repository](https://github.com/vinceglb/FileKit/issues).
</Note>