Improvements to printing portal

[AdrianVovk]

Right now the printing portal exposes two UX flows:

1. Simplified: app has a document ready to go, calls Print(), the portal presents a dialog to choose a printer and edit some page settings, and finally prints

2. Two-step: app doesn't have a document ready to go. Calls PreparePrint(), the portal presents a dialog to choose a printer and page settings. Next, app can present its own dialog with additional print settings and possibly a preview. Once user confirms the operation, app calls Print() and the portal skips an extra dialog due to the previous PreparePrint() call

These flows have some problems:

1. The portal dialog lacks a preview, and so it's hard for the user to guess what the result of their various changes will be. Even if the app has its own preview dialog, the UX of having to re-open the portal dialog to change some page settings is sub-optimal

2. Apps may want to have their own settings to incorporate into the print dialog. For instance: browsers may have a setting to show/hide the header/footer; presentation apps may have settings regarding the inclusion of speaker notes; etc.

This discussion is about finding ways to address these problems. I see a few potential solutions:

• Make the Print portal chattier, so that whenever a setting changes it sends an update to the app. The app, in turn, re-renders a new print preview and that gets shown in the portal
  • Something to consider: re-rendering might be expensive if the output is going to be a 500-page PDF, so we need to re-render only visible pages and ask the app for new previews as the user scrolls around
• Allow apps to add their own additional settings to the print dialog's UI
  • How complex would this be?!
• Alternatively: maybe the print portal can be reworked to just expose all the necessary information directly to the app, and then the app could have its own print dialog in-process.
  - This would mean each app would have its own inconsistent printing UI...
  - Another negative is that toolkits would probably have to handle this printing UI, but toolkits like GTK explicitly want to move away from handling printing due to its simultaneous complexity and niche-ness (i.e. very few apps need to ever print anything)

[AdrianVovk]

At LAS we discussed that we should try giving a look at what this API looks like on other platforms. Here are my findings:

iOS: main print API

iOS has something similar-ish to a potential future chatty portal: the OS gives the app a UIPrintInteractionController singleton that it can use to request a print dialog. The dialog includes a preview of the print, and settings to pick the printer and page settings.

There are a few different mutually-exclusive ways that an app feeds the data-to-print into iOS's printing API:

1. The app can give iOS a list of "print-ready objects", which are defined as either: path to PDF file, data of a PDF file, image in one of a list of supported image file formats

2. The app can give iOS a single implementation of a UIPrintFormatter, which are simple pre-defined classes to turn various data types into rendered mutli-page print content. Known implementations of these classes include:

   • UISimpleTextPrintFormatter: prints text. You construct the object with either a plain text string or an "attributed string" (equivalent to Pango's markup), and it will contain all the logic to render that text buffer into a print document, possibly across pages
   • UIMarkupTextPrintFormatter: prints HTML markup. You construct the object w/ HTML markup and it renders the HTML for the print job
   • UIViewPrintFormatter: Generic super-class for rendering UI widgets ("views" in iOS's toolkit) to the printer. Can be obtained from the following widgets:
     • WKWebView: Browser engine
     • UITextView: Rich text renderer + editor widget. Similar to Gtk.TextView
     • MKMapView: Map widget. Similar to Shumate.Map in GTK

3. The app can completely control the content of the pages by subclassing UIPrintPageRenderer and doing custom drawing in the callbacks.

   • An interesting note is that the app can still use PrintFormatter objects here. Each page has a stack of print formatter objects that may be associated with it, and the app gets to call into them. For instance, if you want to print some plain text but underlay a logo underneath it, what you'd do is construct a SimpleTextPrintFormatter to render the text, but then also implement a custom UIPrintPageRenderer. Simplifying a little bit, in the custom renderer's drawPage method you'd simply draw your logo and then call into the print formatter's draw method to render the text
   • The rendering is done using the widget toolkit's rendering APIs (similar to how we've historically used Cairo both for print rendering and the widget toolkit itself in GTK). It's unclear, to me, what wire format iOS is using to transfer the rendered print preview thumbnail out of the app and into the print dialog via IPC

In summary, the app gives the platform an object that knows how to render the contents of the document given any set of print settings. The platform can then use this object to re-render individual pages for a print preview, and finally uses the same object to print the real document once the user confirms the print operation.

iOS: secondary print API

iOS seems to have a second print API that goes something like this:

• The app can ask that the OS shows a printer chooser dialog. This allows the user to pick a printer
• The selected printer is returned to the app
• The app can present its own print settings UI, with its own preview, or do whatever it wants
• Eventually the app can then ask the platform to print on a specific pre-selected printer given the app's own preferred print settings (given a limited set of print settings). The app feeds the data-to-print into the print API the same way it did in the main print API.
• The platform prints the document, presumably without an additional prompt

I suspect this is here because the main print API doesn't have the option for an app to include app-specific printing settings. So instead, apps would have to implement the printing UI entirely on their own? Unclear

Android

Android's print API is rather similar to the custom-rendering case of iOS. The app subclasses the PrintDocumentAdapter class, which has callbacks that allow the app to render the contents of the page. There are two important callbacks:

• onLayout is called whenever print settings are changed. The app recalculates how many pages of output there will be
• onWrite is called to render a specific range of pages. Unlike iOS, platform rendering primitives are not involved here! The app generates a PDF file of the requested page ranges, and then writes that PDF file into a platform-provided file descriptor that is then sent over the wire to the print service.

To print a document:

1. The app obtains an IPC connection to the system's print service
2. The app constructs its subclass of PrintDocumentAdapter, and asks the print service to start a print job for that adapter
3. The print service shows the print settings UI
4. As the user configures the print settings, the adapter's onLayout and onWrite are called repeatedly to render the print preview in PDF format. Presumably, the platform parses and renders that PDF into the print preview
5. Once the user confirms the final print settings, the adapter's methods are called again to generate the final high-quality print
6. The print service streams the app's output PDF data to the printer

macOS

macOS uses the AppKit printing framework, and there's a fundamental difference here with the mobile APIs. The print dialog is handled in-process of the app! This lets the app inject its own settings into the dialog, simply by directly inserting its own widgets into the dialog (the dialog provides an API for the app to create its own settings section and add UI there)

This means that apps have permission to access the full list of known printers, printer settings, etc. Translating this into Linux-speak, it would be like having the print portal be a proxy for the Common Print Dialog Backends. Perhaps there might be a permission prompt for "allow the app to access printers" but then after that the app can do whatever it wants.

macOS's print API is integrated deep into the UI toolkit, and it obtains the data-to-print by rendering UI tooklit widgets. Apps create a print dialog and point it at a widget, attach any extra app-specific settings to the dialog, and then finally run the print operation. This causes the dialog to appear, and the print settings are used to tweak the widget tree's rendering/layout as they change, and the widget as re-rendered into the print preview (and final print output)

Conclusions/Observations

• A chatty IPC protocol where the app is asked to re-render page ranges on the fly for print preview purposes is common practice on other platforms
• Platforms that do their print dialogs out-of-process do not expose a way for apps to attach custom settings into the print UI!
• Platforms that do their print dialogs out-of-process are all mobile operating systems. It appears that out-of-process printing is unprecedented on the desktop (like many of the things we're trying to achieve with portals...)
• Doing the print dialog in-process is probably going to be a no-go in GTK for the same reason that we've never had a print preview UI: the PDF rendering library we'd be using, poppler, is strictly GPL and that means we cannot link against it from GPL-incompatible apps.

[AdrianVovk]

I wonder: would the Common Print Dialog Backends have some sort of standardized way to communicate a list of custom settings to the dialog UI? Or is it relying on the dialog to know what that specific setting is and have specific code to render that setting? I'm wondering if we could re-use the same wire format to let apps expose arbitrary settings up into the print dialog without needing the print dialog to have knowledge of all the possible settings an app may request.

We do have some precedent to add app-controlled settings to portal UI. See choices in OpenFile(). We expose a way for apps to declare simple drop-down menus and checkboxes. Maybe something like this is enough to handle the majority of cases in the print dialogs too?

[tillkamppeter]

@AdrianVovk The interpretation of strings to determine data types is only for preserving the existing API of CPDB,

@AdrianVovk @Souptik-De for the new function/method "get-all-options" (or perhaps better "get-all-capabilities") we can use a more advanced data structure containing also fields for each option's data type. The data types have to be determined by the CPDB backends naturally, so IPP is only talked by the CUPS backend.

@Souptik-De Single-choice enumerated-choice options usually do not make sense in an interactive print dialog, as the user cannot change the value, so displaying them in the dialog is only clutter. Therefore, if, when rendering the print dialog, a single-choice enumerated-choice option is found, it can be skipped. One can assume here that the print job is done with that one choice set. Only if this single choice influences how the app has to render the job, it needs to get conveyed through to the job (imagine a printer which supports only one single page size, like for example a dye-sublimation photo printer, or even an instant-film photo printer).

@bakayu any function we will add to CPDB, we will also add to the Rust bindings.

[bakayu]

As long as org.openprinting.Backend.xml is updated correctly, extending the existing Rust bindings wouldn't be a problem.

[tillkamppeter]

@Souptik-De is currently working on extending CPDB with the appropriate functionality without removing its existing APIs. Especially a function gets added to return a structure of all options and capabilities with localized human-readable strings:

• cpdb-libs: Define structures and methods for all printer capabilities and implement functions to create and delete printer capabilities OpenPrinting/cpdb-libs#95
• cpdb-backend-cups: Add capability management functions and integrate with D-Bus interface OpenPrinting/cpdb-backend-cups#67

[tillkamppeter]

I have merged @Souptik-De 's PRs on cpdb-libs and cpdb-backend-cups right now.

Thanks a lot for your quick fix, Souptik!

[tillkamppeter]

And for our portals (for all desktops, each dialog just has to use CPDB) we are now prepared for all CUPS versions: 2.x, 2.5.x, and 3.x, as the CUPS backend of CPDB builds and runs with the CUPS libraries of each of said CUPS versions now.

[tillkamppeter]

@swick wrote in an e-mail reply:

Thanks Till and Adrian!

I think a Print Portal with a updating preview, like Till is suggesting, is the right direction given the review done by Adrian (specifically on how this works on Android and iOS), and the desire to drop in-toolkit print dialogs in GTK.

For me the question is how we should actually make this happen. Maybe we need a org.freedesktop.portal.Print2 portal?

I think the same and for how to name it, I would use org.freedesktop.portal.PreviewPrint to clearly tell the difference to the old API.

[bakayu]

A quick question on this. Would apps that support printing need to be updated accordingly with the future org.freedesktop.portal.PreviewPrint portal so they can re-render the preview?

[AdrianVovk]

I don't think this needs to be a new portal. We could add a method like PreparePrintWithPreview to the existing portal

[swick]

FWIW, it might make sense to do a new Print2 portal if we want to deprecate the current API (in the sense that we're not going to add anything, and we don't want people to use it ideally).

[AdrianVovk]

IDK, I think there's value in the simplified Print() call for apps that just have ready-made PDFs to print and will be unable to do anything useful with a chattier version of the protocol. PreparePrint would probably be the only thing we deprecate

[bakayu]

Hello All,
Pasting my email here to discuss my approach publicly. I wrote:

---

The core problem, as I understand it:

• The current PreparePrint to Print two-step flow is fundamentally incompatible with live preview, because the document only arrives at the portal after the user has finished configuring settings in PreparePrint.
• Preview is only possible during Print, but user interactivity ends when PreparePrint closes.

My Proposed direction:

A single long-lived call with D-Bus signals.

• Collapse both steps into one call, for example org.freedesktop.portal.PreviewPrint, where:
• The initial call includes the document (as a file descriptor) and the app's initial settings.
• Whenever the user changes a preview-affecting option (page size, color mode, margin, etc.), the portal emits a D-Bus signal back to the app.
  The app responds by re-rendering and passing a new file descriptor back via a corresponding signal.
  The call completes only when the user clicks "Print" (triggering a full render) or cancels. Here, the app finally delivers the fully rendered document and submits it to the print queue. (Similar to how firefox does it).

This turns the interaction into a signal-driven feedback loop rather than a series of disconnected method calls.

Key design points:

• Why a single call? A single open call with signals avoids re-orchestrating a new D-Bus session on every settings change. The portal holds state naturally for the lifetime of the call. Otherwise we may keep it a 2 method API. The first method will collect settings while providing a rich preview, and the second method will submit an fd with the fully rendered document, similar to how the current portal API works.
• Partial re-render: As stated earlier in this email thread, re-rendering documents is expensive, so we should only render and re-render visible parts of the document. Signals should carry the visible page range so the app only re-renders what is currently on screen, the full render should be requested only at the final "Print" confirmation.
• App-specific settings are already handled by the existing API. The current PreparePrint spec already supports apps passing their own settings. I think we can reuse this same mechanism in the new API where the app declares its settings capabilities at call start (e.g., header/footer toggle for browsers, scaling for spreadsheets), and the portal surfaces them in the UI. No new schema is needed for this part, just a clear convention.

Regards,
Ayush Chauhan

---

@AdrianVovk replied:

Hi Ayu,

Thanks for reaching out!

Could we have this discussion publicly, on the xdg-desktop-portal discussion? It would be useful to document what's going on for posterity, if at all possible

Overall, this approach matches with what I'd have in mind. However, I've also got a few pieces of immediate feedback:

1. A single long-lived method call is a little problematic in DBus. Portals have the concept of a "Session" to handle these kinds of long-running operations with back/forth discussion. So rather than a PreparePrint, maybe the app calls PreparePrintWithPreview, which returns a session and starts emitting signals attached to that session. The app could then call something like UpdatePreview() to give the updated preview to the portal to render.

2. I don't see an API for apps to pass custom settings to PreparePrint, and for the print dialog to present those settings. Could you clarify what you're referring to?

Best,
Adrian

I agree with (1), this design makes more sense.

As for (2): In org.freedesktop.portal.Print.PreparePrint, when calling PreparePrint the app can pass a settings vardict, which is defined by the portal as:

The settings and page_setup vardict contain hints for the initial state of the print dialog.

The settings to be used for printing depend on the printer's capabilities, and in case of CPDB they are queried by the backend and provided to the Print Dialog when the Print Dialog is opened, but the apps themselves may also provide an "initial set of settings" that can be merged with the settings provided by the print backends.

We can use the same pattern, additionally we may need to add standardized keys to allow certain apps to pass additional settings such as header/footer toggle for browsers, scaling for spreadsheets, etc. So that portals across different Desktop Environments all agree on the same set of settings definitions and behave the same with all apps.

EDIT: This actually might not be a good solution, see my reply below.

[AdrianVovk]

Yeah this (your reply about the fact that the portal has no idea how to present these settings) is what I meant when I wrote my point (2). It's also what I was discussing with Till in #2016 (comment)

Summarizing the other thread: we do need to define some schema for apps to communicate their settings to the print dialog. Luckily, there's already something like that for print dialogs to consume: according to Till, CPDB can somehow communicate settings to the dialog that the dialog has never seen before, with enough information for the dialog to render these settings. If we can reuse that schema in the portal API as much as possible, the print dialogs would be able to consume app-specific settings with the same code paths as custom printer settings from the printer/CUPS/CPDB.

Anyway, perhaps the conversation of what app-specific settings will look like should go into that thread, and we keep this thread about the approach to the actual signaling?

[bakayu]

I apologize for the confusion, I jumped to conclusions too hastily.

According to you, in our new PreparePrintWithPreview method the portal would return a session to the app, and then the app can return updated previews to the portal. A question on this- What exactly would the flow look like when the Portal requests a new preview?

[AdrianVovk]

I'd imagine that the signal would be similar to the return value of PreviewPrint right now: it'd communicate the current state of all the print settings in the portal dialog, just without closing the dialog. Perhaps with the addition of a list of pages to render previews for. As you scroll around in the dialog, it would re-emit that signal to fetch different ranges of pages. While we wait for the app to respond with a preview, we show the user a blank page and maybe a spinner animation on that page?

Once the app recieves the signal, it just runs its print rendering machinery for that page and calls UpdatePreview with the result, along with the page numbers it has rendered. We'd probably want the app to communicate back either PDF instructions or a pre-rendered pixel buffer of the page's thumbnail? PDF data is probably easiest, since it's what the app will be generating for us anyway once the final print operation is confirmed.

I would imagine that the dialog will keep around some kind of size-limited cache of rendered page previews. As you scroll around, more and more of this cache gets filled in. For small documents, we could probably hold the whole thing in cache as the user scrolls around. Then once the user changes any setting, we clear the whole cache and start emitting the signal again to ask the app for updated previews.

[bakayu]

Thanks for the explanation!

This flow make sense, in this we would just need to categorize what type of settings would require a re-render of the app. For example common CPDB settings exposed by the dialog such as print on sides, paper tray and paper type selection, print quality, printing in reverse orders would not require a re-render of the document. Only settings such as changing the orientation, page size, layout, margins and scale, borders and app-specific settings would require a re-render of the document.

Another thing to note: For page selection, if a user picks a custom range say 1, 100 and the app only has rendered maybe pages from 1-20, the app would need to render and send information of the 100th page (In this case it wouldn't just be a range relative to the current page). To allow control over which pages/parts of the documents are to be rendered, we should let the Print dialogs be responsible for enforcing ranges/limits and then requesting data accordingly, this let's print dialogs define their own user experience without being restricted by the API. This would probably be implementation detail on the developer side, just a thing we may need to document.

[AdrianVovk]

Right, I would imagine that the dialog will simply manipulate the value of the page-ranges setting when it emits the signal. Let's say the configured page ranges are 1-5,7,15 and the user has scrolled all the way to the bottom. Well then the dialog would want to render just the visible pages in the scroll view. Let's say there are three pages that fit in there. So the dialog would replace page-ranges with 5,7,15 and the app would render through the same code paths it does anyways.

[tillkamppeter]

For app-specific options, what has to be done in any form:

• When initially calling the print dialog, send a list of app-specific options, each with machine-readable/CLI name, human-readable name (can be translated to the user's UI language), specification of data type, with a list of the possible settings/choices, and the current/default setting for each. For the settings/choices, depending on data type:
  • Enumerated choice: a list of choices, each with machine-readable/CLI name and human-readable name/translation
  • Integer: Range min ... max
  • String/password: Max length, allowed characters, is it string or password?
• In the dialog introduce some area/tab for app-specific options, display the widgets for the options from the list
• If the user changes the setting of an app-specific option, the new setting is sent somehow to the app, so that it can re-render the preview, like if a job-changing printer options, like for example when from the printer options the PageSize is changed.

[tillkamppeter]

This way the dialog does not need to "understand" the app-specific options, as it only displays them (using the human-readable strings) and keeps the app informed what the user has selected (as machine-readable names). The preview is then re-rendered by the app (so the settings are actually executed by the app).

The dialog and also the app also does not need to "understand" all the options which the printer reports. Only the media geometry (page size/margins) and color mode (gray/color) need to be passed on to the app so that it re-creates its preview based on this info.

The other printer-specific settings are usually only passed on to the printer when the job is printed.

Some of the printer-specific could also be illustrated in the preview, for example duplex marking the page border where the binding is (or arrange the preview as double pages, like open books), or N-up by arranging the preview appropriately.

[jackpot51]

If there is a revision, I'd also want to drop SVG support. The reason is that the multi-page SVG working draft was dropped, and many SVG renderers do not support it. Programs that generate multi-page output would therefore have to choose a page to render to SVG, or generate a non-compliant SVG.