Skip to content

HTML dialogs and popovers

These are in-document elements rendered by the host, not native OS dialogs (for those see file dialogs).

A modal <dialog>

<dialog id="confirm">
  <p>Delete this item?</p>
  <button id="confirm-yes">Delete</button> <button id="confirm-no">Cancel</button>
</dialog>
def ask(_event):
    document.show_dialog("confirm")            # modal=True by default

def answered(event):
    if event["element"] == "confirm-yes":
        delete_selected()
    document.close_dialog("confirm", "yes" if event["element"] == "confirm-yes" else "no")

document.on("click", ask, element="delete")
document.on("click", answered, element="confirm")

close_dialog(id, return_value) closes it and fires close with event["return_value"]. document.command("get_dialog", element="confirm") returns {"open", "modal", "return_value"}. Pressing Escape on a modal dialog is a native close request: the host fires cancel and close. As in HTML, that does not reset the return value, so track the outcome of the current opening in your own state when it matters. cancel is cancelable: document.prevent_default("confirm", "cancel") keeps the dialog open on Escape.

A form inside a dialog

Put a <form> in the dialog and handle its submit; close the dialog from the handler. This gives you validation and Enter-to-submit for free:

def on_save(_event):
    entries = {e["name"]: e.get("value", "") for e in document.form_data("settings-form")["entries"]}
    apply(entries)
    document.close_dialog("settings", "saved")

document.on("submit", on_save, element="settings-form")
document.on("close", lambda e: document.set_text("status", "Dialog closed"), element="settings")

Fill the form before show_dialog with set_value, set_checked and set_selected_values, and move focus with document.focus(...). Native validation (required, min, max) runs before submit, so an out-of-range value keeps the dialog open.

Report the outcome from the button and submit handlers rather than from close: after Escape the dialog still carries the return value of its previous closing. settings_dialog.py does this: Save writes the JSON file, applies the settings and calls close_dialog("settings", "saved"); Cancel calls close_dialog("settings", "cancelled").

Screenshot: py-sdk-settings_dialog

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

Popovers

<button id="help-button">?</button>
<div id="help" popover>Shortcuts: Ctrl+S saves, Escape cancels.</div>
document.on("click", lambda e: document.toggle_popover("help"), element="help-button")

show_popover, hide_popover and toggle_popover (returns the new open state) work on elements with the popover attribute. document.command("get_popover", element="help") returns {"open", "kind"}. Popovers and dialogs fire beforetoggle and toggle with old_state / new_state; these do not bubble, so subscribe on the element itself.


Source: nativehtmlkit-python/docs/guides/dialogs-and-popovers.md ยท edit the page there.