.. _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 `_. * ``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 `_. * ``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