=====Contents=====

  * [[https://www.linuxfoundation.org/#org.openprinting.PrintDialog.Manager_Interface|1 org.openprinting.PrintDialog.Manager Interface]]
    * [[https://www.linuxfoundation.org/#Description|1.1 Description]]
    * [[https://www.linuxfoundation.org/#Methods|1.2 Methods]]
      * [[https://www.linuxfoundation.org/#CreatePrintDialog|1.2.1 CreatePrintDialog]]
  * [[https://www.linuxfoundation.org/#org.openprinting.PrintDialog.PrintDialog_Interface|2 org.openprinting.PrintDialog.PrintDialog Interface]]
    * [[https://www.linuxfoundation.org/#Description_2|2.1 Description]]
    * [[https://www.linuxfoundation.org/#Methods_2|2.2 Methods]]
      * [[https://www.linuxfoundation.org/#Show|2.2.1 Show]]
      * [[https://www.linuxfoundation.org/#SetDocumentName|2.2.2 SetDocumentName]]
      * [[https://www.linuxfoundation.org/#SetNumberOfPages|2.2.3 SetNumberOfPages]]
      * [[https://www.linuxfoundation.org/#SetDocumentSize|2.2.4 SetDocumentSize]]
      * [[https://www.linuxfoundation.org/#RequestDocumentDataSocket|2.2.5 RequestDocumentDataSocket]]
      * [[https://www.linuxfoundation.org/#RequestPreviewDataSocket|2.2.6 RequestPreviewDataSocket]]
      * [[https://www.linuxfoundation.org/#AddOption|2.2.7 AddOption]]
      * [[https://www.linuxfoundation.org/#SetOptionIcon|2.2.8 SetOptionIcon]]
      * [[https://www.linuxfoundation.org/#SetChoiceIcon|2.2.9 SetChoiceIcon]]
      * [[https://www.linuxfoundation.org/#GetOptionValue|2.2.10 GetOptionValue]]
      * [[https://www.linuxfoundation.org/#SetOptionValue|2.2.11 SetOptionValue]]
      * [[https://www.linuxfoundation.org/#AddPreset|2.2.12 AddPreset]]
    * [[https://www.linuxfoundation.org/#Signals|2.3 Signals]]
      * [[https://www.linuxfoundation.org/#OptionChanged|2.3.1 OptionChanged]]
      * [[https://www.linuxfoundation.org/#Cancelled|2.3.2 Cancelled]]
      * [[https://www.linuxfoundation.org/#ReadyForDocumentData|2.3.3 ReadyForDocumentData]]
      * [[https://www.linuxfoundation.org/#NeedPreviewPage|2.3.4 NeedPreviewPage]]

====== org.openprinting.PrintDialog.Manager Interface ======

===== Description =====


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

===== Methods =====
 ==== CreatePrintDialog ====

<code>
 CreatePrintDialog(out 'o' dialog)</code>

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 [[https://www.linuxfoundation.org/#AddOption|AddOption]], and maybe even add some option presets with [[https://www.linuxfoundation.org/#AddPreset|AddPreset]]. It might also set the [[https://www.linuxfoundation.org/#SetDocumentName|name]] of the document, which will be included in the print job's name. Afterwards, the dialog can be [[https://www.linuxfoundation.org/#Show|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 [[https://www.linuxfoundation.org/#RequestDocumentDataSocket| RequestDocumentDataSocket]] and to transmit the document data on the returned socket. To transmit a lower quality version or only parts of the document, [[https://www.linuxfoundation.org/#RequestPreviewDataSocket|RequestPreviewDataSocket ]] can be used. The dialog will emit [[https://www.linuxfoundation.org/#ReadyForDocumentData| ReadyForDocumentData]] if the user starts the print job. This way, the full document data does not need to be transferred if the user [[https://www.linuxfoundation.org/#Cancelled|cancels]] the dialog.

===== Methods =====
 ==== Show ====

<code>
 Show()</code>

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

==== SetDocumentName ====

<code>
 SetDocumentName('s' name)</code>

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 ====

<code>
 SetNumberOfPages('i' pagecnt)</code>

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 ====

<code>
 SetDocumentSize('u' size)</code>

Set the size of the final document in bytes.

==== RequestDocumentDataSocket ====

<code>
 RequestDocumentDataSocket(out 's' socketname)</code>

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, [[https://www.linuxfoundation.org/#RequestPreviewDataSocket| 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 [[https://www.linuxfoundation.org/#ReadyForDocumentData| 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 [[https://www.linuxfoundation.org/#OptionChanged| OptionChanged ]] signal, a new socket must be requested.

==== RequestPreviewDataSocket ====

<code>
 RequestPreviewDataSocket(out 's' socktname, 'u' firstpage, 'b' canrequestmore)</code>

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 [[https://www.linuxfoundation.org/#NeedPreviewPage| 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 [[https://www.linuxfoundation.org/#RequestDocumentDataSocket| 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 [[https://www.linuxfoundation.org/#NeedPreviewPage| NeedPreviewPage]]. 

==== AddOption ====

<code>
 AddOption('(sssa(ss)vvvsasas)' option, out 'b' success)</code>

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 ====

<code>
 SetOptionIcon('s' option, 'ay' icon)</code>

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 ====

<code>
 SetChoiceIcon('s' option, 's' choice, 'ay' icon)</code>

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 ====

<code>
 GetOptionValue('s' name, out 'v' value)</code>

Returns the current value of an option.

==== SetOptionValue ====

<code>
 SetOptionValue('s' name, 'v' value, out 'b' success)</code>

Set an option to a new value.

==== AddPreset ====

<code>
 AddPreset('s' name, 's' options)</code>

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 ====

<code>
 OptionChanged('s' name, 'v' value)</code>

This signal is emitted whenever an option changed. This might be application specific options added with [[https://www.linuxfoundation.org/#AddOption|AddOption]], or printer specific options, such as "PageSize"

==== Cancelled ====

<code>
 Cancelled()</code>

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

==== ReadyForDocumentData ====

<code>
 ReadyForDocumentData()</code>

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 [[https://www.linuxfoundation.org/#RequestDocumentDataSocket| RequestDocumentDataSocket]]. The dialog object will be deleted after the document is transmitted.

==== NeedPreviewPage ====

<code>
 NeedPreviewPage('i' page)</code>

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 [[https://www.linuxfoundation.org/#RequestPreviewDataSocket| RequestPreviewDataSocket]]). In this case, the application should send a preview containing "page".