- 1 Requirements for the Common Printing Dialog and its API
- 2 General
Requirements for the Common Printing Dialog and its API
Acceptable keywords for the requirements are limited to:
- SHALL [NOT]
- MUST [NOT]
- MAY [NOT]
Application and Print Dialog communication shall use DBUS except for PDF content, for which sockets will be used.
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?
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.
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.
DBUS Service Name
The API for the common print dialog shall be accessible on the session bus under org.openprinting.PrintDialog
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.
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.
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.
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.
- "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.
Application specific Presets and Tags
An application shall have the ability to add custom presets and tags.
The dialog may remember printing options for each application and/or document. This should happen completely transparent to the application.
OpenOffice.org 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.