The Linux Foundation


From The Linux Foundation


Requirements for the Common Printing Dialog and its API

Acceptable keywords for the requirements are limited to:

  • MUST [NOT]
  • MAY [NOT]


Application and Print Dialog communication shall use DBUS except for PDF content, for which sockets will be used.

Status: Approved

Option Icons

Applications and also printer drivers/PPDs may assign icons to options and choices. Icons from printer drivers/PPDs shall be embedded in the PPD and shall be UU-encoded (base64).

What format and size (in case of raster format) shall the icons be in?

Status: Pending


Applications may send preview of a document page to the dialog. The dialog must accept partial previews and notify the application if it needs additional pages. This will enable the dialog to quickly show a preview, even for large documents.

Status: Approved

Preview Format

Application shall send preview of a document page in PDF format

Sending preview as PDF is a burden to the dialog. Since previews are scaled down version the actual page a icon graphical format is sufficient
This should be okay for small previews, applications can choose to send a simplified document (e.g. without large graphics). A PDF preview will also look much better, because there are no problems with scaling.

Status: Pending

DBUS Service Name

The API for the common print dialog shall be accessible on the session bus under org.openprinting.PrintDialog

Status: Pending

Multiple Print Dialogs

The dialog backend must support more than one dialog at the same time. All of those dialogs will be accessible on the session bus, to avoid the overhead of private connections. Furthermore, this will allow us to use dbus service activation, i.e. no daemon is needed.

An application may run more than one printing dialog simultaneously. This will be useful for SDI applications, in which a single process might have many documents opened in different windows. Examples for such applications: gedit, firefox.

Status: Pending

Option Change Notification

The application will be notified whenever any print option changes (not just its own). It shall also have the possibility to fetch the current value of any option.

Status: Pending

Document Size

Applications may send the size of the final document to the dialog before sending the document itself. This allows the dialog to give the user some kind of feedback for the status of the print job transfer.

Status: Pending

Option Hints

There are many ways for a dialog to visualize an option of a specific type. For example, a numeric option might be shown as a slider, a spinbox, or even a combination of the two. Many applications also allow the user to choose the unit in which he specifies the option value (see the gimp for example).

Therefore, it would be nice if the dialog could get some more information about an option. Since this information is purely aesthetic and not compulsory, I propose to allow an application to add any number of Hints to an option.

Some examples:

  • "font" - for string options representing a font, in X naming scheme (gedit has font options)
  • "color" - for integer options representing RGBA color values
  • "existing-file" - for string options, dialog can supply file chooser
  • "resolution" - for real values representing a resolution, the dialog might offer different units (dots/inch, dots/cm, ...)
  • "length" - a length, a dialog might offer different units (inch, points, cm, mm, ...)

In the PPD file, we could introduce a keyword

*OPOptionHints <optionname>: Hint1, Hint2, ..., HintN

A dialog implementation may choose to ignore those hints.

Status: Pending

Application specific Presets and Tags

An application shall have the ability to add custom presets and tags.

Status: Pending

Option Saving

The dialog may remember printing options for each application and/or document. This should happen completely transparent to the application. saves printing settings (selected print queue and option settings) in its documents. To not require OOo to change the feature with the introduction of the Common Printing Dialog, the dialog should set the remembered options before OpenOffice sets its own options.

There should be some kind of configuration option for the user to turn this feature off.

Handling of "InstallableOptions" group in PPD

The "InstallableOptions" group in the PPD allows to configure which optional accessories are installed on a printer. This way choices in the user options which only make sense if an appropriate accessory is installed can get invalidated by conflict definitions ("*UIConstraints:"). The options in the "InstallableOptions" group are usually only configured by the system administrator or they are configured automatically. A user who simply wants to print does not need to see them, and he also does not need to see choices in the other options which are only useful for an accessory which is not installed.

So all options in the "InstallableOptions" group should never be shown by the dialog and of all the other options should not show any choices which conflict with settings of options in the "InstallableOptions" group. If after that an option reduces to 1 or 0 choices, this option should also not be shown.

Example: The "InstallableOptions" group has the option "DuplexUnit" with the choices "Installed" and "NotInstalled". "NotInstalled" naturally conflicts with "DuplexTumble" and "DuplexNoTumble" but not with "None" of the "Duplex" option. So in the case that a printer has no duplex unit installed the "DuplexUnit" option is set to "NotInstalled" and so "DuplexTumble" and "DuplexNoTumble" do not get shown. As the "Duplex" option then would show only "None", the "Duplex" option will not be shown at all and always the setting "None" be submitted.


The application has to communicate the following things with the dialog:

  • User clicks "Print": Application generates PDF from the document and sends it to the dialog, along with the list of application-specific options (all choices, ranges, icons, ...) and their settings, application-specific constraints for the printer or CUPS options, printer option settings and queue selection which were saved with the document, window ID of the application (to inform app when dialog gets killed).
  • Dialog loads list of print queues from CUPS, options for the currently selected queue, and shows the PDF in the preview and the quick selection buttons of the current printer. The dialog reports its window ID back to the app.
  • If user changes application-specific options, new settings are reported back to the app immediately and app sends new, updated PDF.
  • If user changes printer-specific options, CUPS options, or the print queue, nothing is reported back to the app. The preview gets updated.
  • If user clicks "Print" in the dialog, the PDF as it is currently is sent off into the print queue, along with a list of the settings for the CUPS options and the printer-specific options. The choice of the queue, the CUPS option settings and the settings of the printer-specific options are reported back to the application, so that the application can save them with the document to be used on the next printout.

[Article] [Discussion] [View source] [History]