Skip to content

Native file dialogs

Window.open_files, save_file and choose_folder show the platform's own dialog, parented to the window (on Linux through the desktop portal).

from nativehtmlkit import RpcError

FILTERS = [{"name": "Text files", "extensions": ["txt", "md", "csv"]}]   # no dots

def open_clicked(_event):
    future = window.open_files(title="Open a text file", filters=FILTERS, wait=False)
    future.add_done_callback(opened)

def opened(future):
    try:
        result = future.result()           # {"cancelled": bool, "paths": [...]}
    except RpcError as error:
        status(f"No file dialog here (code {error.code})")
        return
    if result["cancelled"]:
        status("Cancelled")
        return
    load(Path(result["paths"][0]))

document.on("click", open_clicked, element="open")

With wait=False the event callback returns at once, so other events keep flowing while the dialog is open. The done-callback runs on an SDK completion thread and may call any SDK method. future.cancel() asks the host to close the dialog.

Blocking

result = window.save_file(title="Export", file_name="report.csv", filters=[{"name": "CSV", "extensions": ["csv"]}])
if not result["cancelled"]:
    Path(result["paths"][0]).write_text(csv_text, encoding="utf-8")

wait=True (the default) has no timeout. Inside an event callback it holds up all later document and window events until the user answers (close/quit decisions are still handled). That is fine for scripts, less so for interactive windows.

Options and results

Method Options paths
open_files multiple=False, title, directory, filters one or more paths
save_file file_name, title, directory, filters one path (the file is not created for you)
choose_folder title, directory one directory

paths is empty and cancelled is True when the user cancelled.

When dialogs are unavailable

Headless runs (NATIVEHTMLKIT_TEST_MODE=1) and sessions without a dialog service raise RpcError -32001; a second dialog on the same window raises -32005. Check app.capabilities()["file_dialogs"] up front (the top-level flag: does the host offer dialogs in this session?) or handle the error as above. capabilities()["features"]["file_dialogs"]["available"] is None ("not observed") on a native desktop with Core 1.0.3, so do not treat None as "no dialogs". Either way, and keep a fallback (a path input field) where it matters. (checksum.py combines both.)

Screenshot: py-sdk-checksum

Real capture on KDE Plasma 6.6 Wayland with the released packages.

Reading the chosen file

Paths are plain strings: use pathlib.Path. Check the size before reading, decode explicitly and show content with set_value/set_text (never as markup). The file_viewer.py example does this, lists a chosen folder and saves with "Save As…".

Screenshot: py-sdk-file_viewer

Real capture on KDE Plasma 6.6 Wayland with the released packages.

<input type="file"> in a form is an alternative: the host shows the picker on click and document.files("upload") or form_data return the chosen paths.


Source: nativehtmlkit-python/docs/guides/file-dialogs.md · edit the page there.