The Linux Foundation

 
OpenPrinting/CPDAPI

From The Linux Foundation

Contents

org.openprinting.PrintDialog.Manager Interface

Description

PrintDialog.Manager is responsible for creating and managing PrintDialog objects for multiple applications.

Methods

CreatePrintDialog

 CreatePrintDialog(out 'o' dialog)

Creates a new print dialog for the calling application.

Arguments
dialog
Object path to the newly created PrintDialog.

org.openprinting.PrintDialog.PrintDialog Interface

Description

A PrintDialog object represents one instance of a printing dialog. Applications can create PrintDialogs with Manager.CreatePrintDialog.

Typically, an application will first add some custom options with AddOption, and maybe even add some option presets with AddPreset. It might also set the name of the document, which will be included in the print job's name. Afterwards, the dialog can be shown to the user.

Depending on the size and complexity of the document, an application might want to send the whole document as a preview or only parts of it, maybe of lower quality. The PrintDialog interface supports both approaches: To send the whole document, it suffices to call RequestDocumentDataSocket and to transmit the document data on the returned socket. To transmit a lower quality version or only parts of the document, RequestPreviewDataSocket can be used. The dialog will emit ReadyForDocumentData if the user starts the print job. This way, the full document data does not need to be transferred if the user cancels the dialog.

Methods

Show

 Show()

Shows the dialog. This should be called after all configuration (e.g. adding of options or presets) has been done.

SetDocumentName

 SetDocumentName('s' name)

Set the name of the document that will be printed.

The job title will have the document name in it. Furthermore, it might appear in the window title of the printing dialog.

Arguments
name
The name of the document

SetNumberOfPages

 SetNumberOfPages('i' pagecnt)

Set the number of pages of the final document.

This method needs to be called only if the provided preview does not contain all pages of the final document.

SetDocumentSize

 SetDocumentSize('u' size)

Set the size of the final document in bytes.

RequestDocumentDataSocket

 RequestDocumentDataSocket(out 's' socketname)

Returns the address of a local domain socket on which document data can be send to the dialog.

An application may send document data before the user initiates the actual print action. In this case, the data will be used by the dialog to show a preview of the document. If the document is too large, RequestPreviewDataSocket can be used to send a preview which may be of lower quality and does not include all pages of the final document.

In any case, the dialog emits ReadyForDocumentData when the document data is ultimately needed. At the latest, an application should send the document after receiving this signal.

The socket will be closed by the dialog after the whole document has been transmitted. To transmit a different version of the document, for example in response to a OptionChanged signal, a new socket must be requested.

RequestPreviewDataSocket

 RequestPreviewDataSocket(out 's' socktname, 'u' firstpage, 'b' canrequestmore)

Returns the address of a local domain socket on which preview data can be send to the dialog.

This method allows applications to send a lower quality of the document, which need not include all pages of the final document. The dialog sends NeedPreviewPage if the user wants to see pages in the preview which are not yet transmitted.

If the whole document shall be used as a preview, use RequestDocumentDataSocket instead. This avoids transmitting the whole document twice.

Arguments
socktname
The name of the socket on which the server will listen for the preview data.
firstpage
The page number of the "real" document to which the first page in the preview corresponds. Note: The first page is "1", not "0".
canrequestmore
If true, the dialog can request more preview data with NeedPreviewPage.

AddOption

 AddOption('(sssa(ss)vvvsasas)' option, out 'b' success)

Adds an application specific option.

An option structure consists of:

  • The name of the option (string).
  • A human readable version of the option name (string).
  • The option type (string).
  • Predefined choices for this option as array of string tuples, where the first string is the choice name and the second one is a human readable version (array of string tuples).
  • The default value (variant).
  • The minimum value. For string and password options, this is the minimum character count (variant).
  • The maximum value. For string and password options, this is the minimum character count (variant).
  • A posix-style regular expression, which valid string and password values must match (string).
  • Tags associated with the option (array of strings).
  • Option hints (array of strings).
Arguments
option
The option structure.
success
True if the option was successfully added.

SetOptionIcon

 SetOptionIcon('s' option, 'ay' icon)

Sets an icon for an option.

Arguments
option
The name of the option for which the icon shall be set.
icon
The icon data, base64-coded.

SetChoiceIcon

 SetChoiceIcon('s' option, 's' choice, 'ay' icon)

Sets an icon for predefined choice of an option.

Arguments
option
The name of the option.
choice
The name of the choice for which the icon shall be set.
icon
The icon data, base64 endcoded.

GetOptionValue

 GetOptionValue('s' name, out 'v' value)

Returns the current value of an option.

SetOptionValue

 SetOptionValue('s' name, 'v' value, out 'b' success)

Set an option to a new value.

AddPreset

 AddPreset('s' name, 's' options)

Add a preset to the dialog. Presets are a quick and easy way for users to set multiple options at the same time.

Arguments
name
The name of the preset.
options
Option settings as a single string in the form "option1=value1 option2=value2 ...".

Signals

OptionChanged

 OptionChanged('s' name, 'v' value)

This signal is emitted whenever an option changed. This might be application specific options added with AddOption, or printer specific options, such as "PageSize"

Cancelled

 Cancelled()

This signal is emitted if a user cancels the dialog. The "PrintDialog" object will not be accessible anymore.

ReadyForDocumentData

 ReadyForDocumentData()

This signal is emitted after the user initiates the print process (i.e. clicks "Print"). If an application has not yet send its document data it should do so now, by requesting a socket connection with RequestDocumentDataSocket. The dialog object will be deleted after the document is transmitted.

NeedPreviewPage

 NeedPreviewPage('i' page)

This signal is emitted if the user browses through the document preview and the hits a page with has not yet been send by the application (see RequestPreviewDataSocket). In this case, the application should send a preview containing "page".


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