Dialogs

A dialog is a top-level window made on another, its parent, as one that asks which file to open or whether to save. create-window makes one with :parent:

(win:create-window window-system &key (title "") (width 800) (height 600) app-id parent modal)
=> window

A dialog stays above its parent, opens over it, and is destroyed with it: destroy-window destroys a window's dialogs, with their own dialogs and popups, before the window. The window system may show it as a dialog, without a taskbar entry of its own. Otherwise a dialog is a window like any other, with a size, a scale and events of its own: draw nothing before window-configured-p is true.

Modal dialogs

With :modal t too, the user answers the dialog before going back to its parent:

(let ((dialog (win:create-window window-system :title "Save changes?" :width 360 :height 140
                                               :parent window :modal t)))
  ;; Draw it and handle its events until the user answers, then:
  (win:destroy-window dialog))

While a modal dialog is open, its parent and the parent's popups get no input that starts there:

Dropped for the parent and its popups	Still delivered
:key-press, :text, :preedit, :delete-surrounding	:key-release
:button-press, :scroll, :pointer-motion	:button-release
:close, when the user asks to close the parent	:close of a popup the window system dismissed
	:focus-in, :focus-out, :pointer-enter, :pointer-leave, :resize

Releases still come, so a key or button held when the dialog opened is released: a program that tracks what is held, as an input map of actions does, never sees a key stuck down. A modal dialog of a dialog keeps that dialog from input in turn. Once the last modal dialog of a window is destroyed, the window gets its input again.

A dialog that is not modal, as a search box, leaves its parent its input.

How windows are related

Function	Returns
(window-parent window)	The window it was made on: a dialog's parent, or a popup's; nil for a window of its own.
(window-modal-p window)	True for a modal dialog.
(window-dialogs window)	Its dialogs that are alive, oldest first.

Errors

create-window signals dialog-error for :modal t without a :parent, and for a parent that is a popup or belongs to another window system; closed-error for a destroyed parent. A dialog opened from a popup, as from a menu, is made on the top-level window the popup is on.

On each platform

• Wayland: a dialog is an xdg-shell toplevel given its parent with xdg_toplevel.set_parent, and marked as a dialog, modal or not, through xdg-dialog-v1 where the compositor offers xdg_wm_dialog_v1. The compositor decides where the dialog goes and how it and its parent look, and learns of the parent only once the parent has been drawn. It may deliver input to a modal dialog's parent all the same: cl-windowing drops it, as xdg-dialog asks of clients. See Wayland Backend.
• Windows: a dialog is a window owned by its parent's window, with no button on the taskbar, opened over the middle of its parent within the work area of its display. A modal one disables its parent's window while it is open, as Windows' dialog boxes do: Windows gives the parent no input, and shows the dialog when the user clicks the parent. See Win32 Backend.