.. _org.freedesktop.portal.Print:

============================
 Print
============================

-----------
Description
-----------

.. _org.freedesktop.portal.Print Description:

Portal for printing

The Print portal allows sandboxed applications to print.

Due to the way in which printing requires bi-directional communication,
using this portal will often require applications to make multiple requests.
First, use `org.freedesktop.portal.Print.PreparePrint`_ to obtain print settings,
use them to format your output, then use `org.freedesktop.portal.Print.Print`_
to print the formatted document. It is expected that high-level toolkit
APIs such as GtkPrintOperation will hide most of this complexity.

This documentation describes version 3 of this interface.



.. _org.freedesktop.portal.Print Properties:

----------
Properties
----------

.. _org.freedesktop.portal.Print:version:

org.freedesktop.portal.Print:version
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    version readable u




.. _org.freedesktop.portal.Print Methods:

-------
Methods
-------

.. _org.freedesktop.portal.Print.PreparePrint:

org.freedesktop.portal.Print.PreparePrint
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    PreparePrint (
      IN parent_window s,
      IN title s,
      IN settings a{sv},
      IN page_setup a{sv},
      IN options a{sv},
      OUT handle o
    )



Presents a print dialog to the user and returns print settings
and page setup.

Supported keys in the ``options`` vardict:

* ``handle_token`` (``s``)

  A string that will be used as the last element of the ``handle``. Must be a valid
  object path element. See the :ref:`org.freedesktop.portal.Request` documentation for
  more information about the ``handle``.

* ``modal`` (``b``)

  Whether to make the dialog modal. Defaults to yes.

* ``accept_label`` (``s``)

  Label for the accept button. Mnemonic underlines are allowed.

  This option was added in version 2.

* ``supported_output_file_formats`` (``as``)

  File formats supported by the app to use for print-to-file. If not set, all formats
  are assumed to be supported. The following values are allowed: "pdf", "ps", and "svg".

  This option was added in version 3.

The following results get returned via the :ref:`org.freedesktop.portal.Request::Response` signal:

* ``settings`` (``a{sv}``)

  Print settings as set up by the user in the print dialog.

  The following keys are supported in the print settings vardict:

  * ``orientation`` (``s``)

    One of ``landscape``, ``portrait``, ``reverse_landscape`` or ``reverse_portrait``.

  * ``paper-format`` (``s``)

    A paper name according to `PWG 5101.1-2002 <ftp://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn10-20020226-5101.1.pdf>`_.

  * ``paper-width`` (``s``)

    Paper width, in millimeters.

  * ``paper-height`` (``s``)

    Paper height, in millimeters.

  * ``n-copies`` (``s``)

    The number of copies to print.

  * ``default-source`` (``s``)

    The default paper source.

  * ``quality`` (``s``)

    Print quality, one of normal, high, low or draft.

  * ``resolution`` (``s``)

    The resolution, sets both resolution-x and resolution-y.

  * ``use-color`` (``s``)

    Whether to use color, one of true or false.

  * ``duplex`` (``s``)

    Duplex printing mode, one of simplex, horizontal or vertical.

  * ``collate`` (``s``)

    Whether to collate copies, one of true or false.

  * ``reverse`` (``s``)

    Whether to reverse the order of printed pages, one of true or false.

  * ``media-type`` (``s``)

    A media type according to `PWG 5101.1-2002 <ftp://ftp.pwg.org/pub/pwg/candidates/cs-pwgmsn10-20020226-5101.1.pdf>`_.

  * ``dither`` (``s``)

    The dithering to use, one of ``fine``, ``none``, ``coarse``,
    ``lineart``, ``grayscale`` or ``error-diffusion``.

  * ``scale`` (``s``)

    The scale in percent.

  * ``print-pages`` (``s``)

    What pages to print, one of all, selection, current or ranges.

  * ``page-ranges`` (``s``)

    A list of page ranges, formatted like this: `0-2,4,9-11`.

    .. note::

      Page ranges are 0-based, even if the are displayed as 1-based when presented to the user.

  * ``page-set`` (``s``)

    What pages to print, one of all, even or odd.

  * ``finishings`` (``s``)

    Finishings.

  * ``number-up`` (``s``)

    The number of pages per sheet.

  * ``number-up-layout`` (``s``)

    One of ``lrtb``, ``lrbt``, ``rltb``, ``rlbt``, ``tblr``, ``tbrl``,
    ``btlr``, ``btrl``.

  * ``output-bin`` (``s``)

  * ``resolution-x`` (``s``)

    The horizontal resolution in dpi.

  * ``resolution-y`` (``s``)

    The vertical resolution in dpi.

  * ``printer-lpi`` (``s``)

    The resolution in lpi (lines per inch).

  * ``output-basename`` (``s``)

    Basename to use for print-to-file.

  * ``output-file-format`` (``s``)

    Format to use for print-to-file, one of PDF, PS, SVG.

  * ``output-uri`` (``s``)

    The uri used for print-to-file.

* ``page-setup`` (``a{sv}``)

  Page setup as set up by the user in the print dialog.

  The following keys are supported in the page setup vardict:

  * ``PPDName`` (``s``)

    The PPD name.

  * ``Name`` (``s``)

    The name of the page setup.

  * ``DisplayName`` (``s``)

    User-visible name for the page setup.

  * ``Width`` (``d``)

    Paper width in millimeters.

  * ``Height`` (``d``)

    Paper height in millimeters.

  * ``MarginTop`` (``d``)

    Top margin in millimeters.

  * ``MarginBottom`` (``d``)

    Bottom margin in millimeters.

  * ``MarginLeft`` (``d``)

    Left margin in millimeters.

  * ``MarginRight`` (``d``)

    Right margin in millimeters.

  * ``Orientation`` (``s``)

    Orientation, one of portrait, landscape, reverse-portrait or reverse-landscape.

* ``token`` (``u``)

  Token that can be passed to a subsequent `org.freedesktop.portal.Print.Print`_ call to
  bypass the print dialog.



parent_window
  Identifier for the application window, see :doc:`window-identifiers`

title
  Title for the print dialog

settings
  Serialized print settings

page_setup
  Serialized page setup

options
  Vardict with optional further information

handle
  Object path for the :ref:`org.freedesktop.portal.Request` object representing this call



.. _org.freedesktop.portal.Print.Print:

org.freedesktop.portal.Print.Print
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    Print (
      IN parent_window s,
      IN title s,
      IN fd h,
      IN options a{sv},
      OUT handle o
    )



Asks to print a file.

The file must be passed in the form of a file descriptor open for reading.
This ensures that sandboxed applications only print files that they have
access to.

If a valid token is present in the ``options``, then this call will print
with the settings from the Print call that the token refers to. If
no token is present, then a print dialog will be presented to the user.

Note that it is up to the portal implementation to determine how long
it considers tokens valid.

Supported keys in the ``options`` vardict:

* ``handle_token`` (``s``)

  A string that will be used as the last element of the ``handle``. Must be a valid
  object path element. See the :ref:`org.freedesktop.portal.Request` documentation for
  more information about the ``handle``.

* ``modal`` (``b``)

  Whether to make the dialog modal. Defaults to yes.

* ``token`` (``u``)

  Token that was returned by a previous `org.freedesktop.portal.Print.PreparePrint`_ call.

* ``supported_output_file_formats`` (``as``)

  File formats supported by the app to use for print-to-file. If not set, all formats
  are assumed to be supported. The following values are allowed: "pdf", "ps", and "svg".

  This option was added in version 3.



parent_window
  Identifier for the application window, see :doc:`window-identifiers`

title
  Title for the print dialog

fd
  File descriptor for reading the content to print

options
  Vardict with optional further information

handle
  Object path for the :ref:`org.freedesktop.portal.Request` object representing this call


