Dialog windows should be set transient for the main application window they were spawned from.
This allows window managers to e.g. keep the dialog on top of the main window, or center the dialog over the main window. Dialog.with_buttons and other convenience functions in GTK+ will sometimes call set_transient_for on your behalf.
Passing null for parent unsets the current transient window.
On Wayland, this function can also be used to attach a new POPUP to a TOPLEVEL parent already mapped on screen so that the POPUP will be created as a subsurface-based window SUBSURFACE which can be positioned at will relatively to the TOPLEVEL surface.
On Windows, this function puts the child window on top of the parent, much as the window manager would have done on X.
| this |
a Window |
| parent |
parent window, or null |