Author: Serhiy Storchaka <[email protected]>
State: Draft
Type: Project
Created: 03-Oct-2026
Tcl-Version: 9.1
Tk-Branch: x11-desktop-portal
Keywords: Tk, X11, file dialog, print, notification, portal
Vote: Pending
Forum: fc654a409b
Post-History:
Abstract
On X11, use the XDG desktop portal (the org.freedesktop.portal.* D-Bus
interfaces) for tk_getOpenFile, tk_getSaveFile,
tk_chooseDirectory, tk print and tk sysnotify, so that they show
the dialogs and notifications of the desktop (KDE Plasma, GNOME and others),
as they already do on Windows and macOS.
Rationale
On X11 Tk shows its own dialogs, which look and behave unlike those of other applications and lack what users expect: places, recent files, search, previews, network locations, the printers and options known to the desktop. The portal is the desktop-independent way to get native dialogs. All major Linux desktops implement it, and it is the only way for sandboxed applications (Flatpak, Snap). TIP 432 did the same for the Windows file dialogs.
Specification
Only X11 is affected. Safe interpreters never use the portal. libdbus is loaded at run time, so there is no new build dependency. The current implementations are used if libdbus, the session bus or the portal interface is missing, or if the portal ends a request neither with success nor with cancellation (then that interface is not used again).
File dialogs
The desktop's dialog is used unless tk_strictMotif is set; tk_chooseDirectory needs version 3 of the FileChooser interface. The options and results are the same. The dialog is transient for the toplevel of -parent, which does not receive pointer events while it is open (as with tk busy); destroying it closes the dialog, and the command returns an empty string.
Differences, documented in the manual pages:
- -confirmoverwrite false has no effect: the desktop always asks (as on macOS).
- -initialfile in tk_getOpenFile only selects the directory shown (as on macOS).
- -mustexist false does not allow non-existent directories (as on Windows and macOS); new ones can be created in the dialog.
tk print
The printer and job options are selected in the desktop's dialog and applied by the desktop. Tk uses the selected page size, margins, orientation and color mode to produce the document: a canvas as PostScript, centered and scaled down to fit; a text wrapped to the page width and converted to PDF with cupsfilter (without it, as plain text in portrait). When printing to a file, the document is converted to the selected format (PDF or PostScript) with cupsfilter, or ps2pdf for a canvas; without a converter an error is raised.
tk sysnotify
libnotify stays the first choice; the portal is used if it is not installed, before the window implemented in Tcl. For applications that are not sandboxed the portal attributes notifications to the program that started them (for example the terminal), while libnotify uses the Tk application name. In a sandbox libnotify uses the portal itself.
Disabling the portal
Open for discussion. As on Windows and macOS, where the native dialogs cannot be disabled either, this TIP adds no public option to disable the portal. The dialogs implemented in Tk can be called directly on all platforms, with the same options:
::tk::dialog::file:: open ?option value ...?
::tk::dialog::file:: save ?option value ...?
::tk::dialog::file::chooseDir:: ?option value ...?
::tk::MotifFDialog open|save ?option value ...?
The test suite uses the internal variable ::tk::portal::enabled. If there
is a need to use the implementations in Tk globally, a global variable such
as tk_useNativeDialogs (default true) can be added for all platforms.
Reference Implementation
The implementation is in Tk branch x11-desktop-portal. It was tested with the KDE Plasma 6.6, GTK and GNOME 50 portal backends.
Backwards Compatibility
Scripts need no changes. Where the portal is available the dialogs look
different and the option differences above apply. Internal settings of the
Tk dialogs (for example ::tk::dialog::file::showHiddenVar) do not affect
the desktop's dialogs.
Discussion
Issues of current portal backends: KDE Plasma 6.6 drops "pages per sheet" and the page size when printing, and reports successful prints as failed (so tk print does not treat that response as an error); GNOME 50 needs Nautilus for the file chooser.
The Settings portal (color scheme, accent color, contrast) could support dark mode in a separate TIP. There are no portals for color, font or message dialogs.
Copyright
This document has been placed in the public domain.