### Class

# Gtk PrintOperation

since: 4.0

#### Description [src]

    class Gtk.PrintOperation : GObject.Object
      implements Gtk.PrintOperationPreview {
      /* No available fields */
    }

`GtkPrintOperation` is the high-level, portable printing API.

It looks a bit different than other GTK dialogs such as the `GtkFileChooser`, since some platforms don’t expose enough infrastructure to implement a good print dialog. On such platforms, `GtkPrintOperation` uses the native print dialog. On platforms which do not provide a native print dialog, GTK uses its own, see `GtkPrintUnixDialog`.

The typical way to use the high-level printing API is to create a `GtkPrintOperation` object with `gtk_print_operation_new()` when the user selects to print. Then you set some properties on it, e.g. the page size, any `GtkPrintSettings` from previous print operations, the number of pages, the current page, etc.

Then you start the print operation by calling `gtk_print_operation_run()`. It will then show a dialog, let the user select a printer and options. When the user finished the dialog, various signals will be emitted on the `GtkPrintOperation`, the main one being `GtkPrintOperation::draw-page`, which you are supposed to handle and render the page on the provided `GtkPrintContext` using Cairo.

# The high-level printing API

    static GtkPrintSettings *settings = NULL;

    static void
    do_print (void)
    {
      GtkPrintOperation *print;
      GtkPrintOperationResult res;

      print = gtk_print_operation_new ();

      if (settings != NULL)
        gtk_print_operation_set_print_settings (print, settings);

      g_signal_connect (print, "begin_print", G_CALLBACK (begin_print), NULL);
      g_signal_connect (print, "draw_page", G_CALLBACK (draw_page), NULL);

      res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
                                     GTK_WINDOW (main_window), NULL);

      if (res == GTK_PRINT_OPERATION_RESULT_APPLY)
        {
          if (settings != NULL)
            g_object_unref (settings);
          settings = g_object_ref (gtk_print_operation_get_print_settings (print));
        }

      g_object_unref (print);
    }

By default `GtkPrintOperation` uses an external application to do print preview. To implement a custom print preview, an application must connect to the preview signal. The functions `gtk_print_operation_preview_render_page()`, `gtk_print_operation_preview_end_preview()` and `gtk_print_operation_preview_is_selected()` are useful when implementing a print preview.

Available since: 4.0

#### Ancestors

- GObject

#### Implements

- GtkPrintOperationPreview

#### Constructors

###### gtk_print_operation_new

Creates a new `GtkPrintOperation`.

since: 4.0

#### Instance methods

###### gtk_print_operation_cancel

Cancels a running print operation.

since: 4.0

###### gtk_print_operation_draw_page_finish

Signal that drawing of particular page is complete.

since: 4.0

###### gtk_print_operation_get_default_page_setup

Returns the default page setup.

since: 4.0

###### gtk_print_operation_get_embed_page_setup

Gets whether page setup selection combos are embedded.

since: 4.0

###### gtk_print_operation_get_error

Call this when the result of a print operation is `GTK_PRINT_OPERATION_RESULT_ERROR`.

since: 4.0

###### gtk_print_operation_get_has_selection

Gets whether there is a selection.

since: 4.0

###### gtk_print_operation_get_n_pages_to_print

Returns the number of pages that will be printed.

since: 4.0

###### gtk_print_operation_get_print_settings

Returns the current print settings.

since: 4.0

###### gtk_print_operation_get_status

Returns the status of the print operation.

since: 4.0

###### gtk_print_operation_get_status_string

Returns a string representation of the status of the print operation.

since: 4.0

###### gtk_print_operation_get_support_selection

Gets whether the application supports print of selection.

since: 4.0

###### gtk_print_operation_is_finished

A convenience function to find out if the print operation is finished.

since: 4.0

###### gtk_print_operation_run

Runs the print operation.

since: 4.0

###### gtk_print_operation_set_allow_async

Sets whether `gtk_print_operation_run()` may return before the print operation is completed.

since: 4.0

###### gtk_print_operation_set_current_page

Sets the current page.

since: 4.0

###### gtk_print_operation_set_custom_tab_label

Sets the label for the tab holding custom widgets.

since: 4.0

###### gtk_print_operation_set_default_page_setup

Makes `default_page_setup` the default page setup for `op`.

since: 4.0

###### gtk_print_operation_set_defer_drawing

Sets up the `GtkPrintOperation` to wait for calling of [method@Gtk.PrintOperation.draw_page_finish from application.

since: 4.0

###### gtk_print_operation_set_embed_page_setup

Embed page size combo box and orientation combo box into page setup page.

since: 4.0

###### gtk_print_operation_set_export_filename

Sets up the `GtkPrintOperation` to generate a file instead of showing the print dialog.

since: 4.0

###### gtk_print_operation_set_has_selection

Sets whether there is a selection to print.

since: 4.0

###### gtk_print_operation_set_job_name

Sets the name of the print job.

since: 4.0

###### gtk_print_operation_set_n_pages

Sets the number of pages in the document.

since: 4.0

###### gtk_print_operation_set_print_settings

Sets the print settings for `op`.

since: 4.0

###### gtk_print_operation_set_show_progress

If `show_progress` is `TRUE`, the print operation will show a progress dialog during the print operation.

since: 4.0

###### gtk_print_operation_set_support_selection

Sets whether selection is supported by `GtkPrintOperation`.

since: 4.0

###### gtk_print_operation_set_track_print_status

If track_status is `TRUE`, the print operation will try to continue report on the status of the print job in the printer queues and printer.

since: 4.0

###### gtk_print_operation_set_unit

Sets up the transformation for the cairo context obtained from `GtkPrintContext` in such a way that distances are measured in units of `unit`.

since: 4.0

###### gtk_print_operation_set_use_full_page

If `full_page` is `TRUE`, the transformation for the cairo context obtained from `GtkPrintContext` puts the origin at the top left corner of the page.

since: 4.0

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

##### Methods inherited from GtkPrintOperationPreview (3)

###### gtk_print_operation_preview_end_preview

Ends a preview.

since: 4.0

###### gtk_print_operation_preview_is_selected

Returns whether the given page is included in the set of pages that have been selected for printing.

since: 4.0

###### gtk_print_operation_preview_render_page

Renders a page to the preview.

since: 4.0

#### Properties

###### Gtk.PrintOperation:allow-async

Determines whether the print operation may run asynchronously or not.

since: 4.0

###### Gtk.PrintOperation:current-page

The current page in the document.

since: 4.0

###### Gtk.PrintOperation:custom-tab-label

Used as the label of the tab containing custom widgets.

since: 4.0

###### Gtk.PrintOperation:default-page-setup

The `GtkPageSetup` used by default.

since: 4.0

###### Gtk.PrintOperation:embed-page-setup

If `TRUE`, page size combo box and orientation combo box are embedded into page setup page.

since: 4.0

###### Gtk.PrintOperation:export-filename

The name of a file to generate instead of showing the print dialog.

since: 4.0

###### Gtk.PrintOperation:has-selection

Determines whether there is a selection in your application.

since: 4.0

###### Gtk.PrintOperation:job-name

A string used to identify the job (e.g. in monitoring applications like eggcups).

since: 4.0

###### Gtk.PrintOperation:n-pages

The number of pages in the document.

since: 4.0

###### Gtk.PrintOperation:n-pages-to-print

The number of pages that will be printed.

since: 4.0

###### Gtk.PrintOperation:print-settings

The `GtkPrintSettings` used for initializing the dialog.

since: 4.0

###### Gtk.PrintOperation:show-progress

Determines whether to show a progress dialog during the print operation.

since: 4.0

###### Gtk.PrintOperation:status

The status of the print operation.

since: 4.0

###### Gtk.PrintOperation:status-string

A string representation of the status of the print operation.

since: 4.0

###### Gtk.PrintOperation:support-selection

If `TRUE`, the print operation will support print of selection.

since: 4.0

###### Gtk.PrintOperation:track-print-status

If `TRUE`, the print operation will try to continue report on the status of the print job in the printer queues and printer.

since: 4.0

###### Gtk.PrintOperation:unit

The transformation for the cairo context obtained from `GtkPrintContext` is set up in such a way that distances are measured in units of `unit`.

since: 4.0

###### Gtk.PrintOperation:use-full-page

If `TRUE`, the transformation for the cairo context obtained from `GtkPrintContext` puts the origin at the top left corner of the page.

since: 4.0

#### Signals

###### Gtk.PrintOperation::begin-print

Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts.

since: 4.0

###### Gtk.PrintOperation::create-custom-widget

Emitted when displaying the print dialog.

since: 4.0

###### Gtk.PrintOperation::custom-widget-apply

Emitted right before ::begin-print if you added a custom widget in the ::create-custom-widget handler.

since: 4.0

###### Gtk.PrintOperation::done

Emitted when the print operation run has finished doing everything required for printing.

since: 4.0

###### Gtk.PrintOperation::draw-page

Emitted for every page that is printed.

since: 4.0

###### Gtk.PrintOperation::end-print

Emitted after all pages have been rendered.

since: 4.0

###### Gtk.PrintOperation::paginate

Emitted after the ::begin-print signal, but before the actual rendering starts.

since: 4.0

###### Gtk.PrintOperation::preview

Gets emitted when a preview is requested from the native dialog.

since: 4.0

###### Gtk.PrintOperation::request-page-setup

Emitted once for every page that is printed.

since: 4.0

###### Gtk.PrintOperation::status-changed

Emitted at between the various phases of the print operation.

since: 4.0

###### Gtk.PrintOperation::update-custom-widget

Emitted after change of selected printer.

since: 4.0

##### Signals inherited from GObject (1)

###### GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

since: 2.0

##### Signals inherited from GtkPrintOperationPreview (2)

###### GtkPrintOperationPreview::got-page-size

Emitted once for each page that gets rendered to the preview.

since: 4.0

###### GtkPrintOperationPreview::ready

The ::ready signal gets emitted once per preview operation, before the first page is rendered.

since: 4.0

#### Class structure

    struct GtkPrintOperationClass {
      GObjectClass parent_class;
      void (* done) (
        GtkPrintOperation* operation,
        GtkPrintOperationResult result
      );
      void (* begin_print) (
        GtkPrintOperation* operation,
        GtkPrintContext* context
      );
      gboolean (* paginate) (
        GtkPrintOperation* operation,
        GtkPrintContext* context
      );
      void (* request_page_setup) (
        GtkPrintOperation* operation,
        GtkPrintContext* context,
        int page_nr,
        GtkPageSetup* setup
      );
      void (* draw_page) (
        GtkPrintOperation* operation,
        GtkPrintContext* context,
        int page_nr
      );
      void (* end_print) (
        GtkPrintOperation* operation,
        GtkPrintContext* context
      );
      void (* status_changed) (
        GtkPrintOperation* operation
      );
      GtkWidget* (* create_custom_widget) (
        GtkPrintOperation* operation
      );
      void (* custom_widget_apply) (
        GtkPrintOperation* operation,
        GtkWidget* widget
      );
      gboolean (* preview) (
        GtkPrintOperation* operation,
        GtkPrintOperationPreview* preview,
        GtkPrintContext* context,
        GtkWindow* parent
      );
      void (* update_custom_widget) (
        GtkPrintOperation* operation,
        GtkWidget* widget,
        GtkPageSetup* setup,
        GtkPrintSettings* settings
      );

    }

No description available.

###### Class members

`parent_class: GObjectClass`

  The parent class.

`done: void (* done) ( GtkPrintOperation* operation, GtkPrintOperationResult result )`

  Signal emitted when the print operation run has finished doing everything required for printing.

`begin_print: void (* begin_print) ( GtkPrintOperation* operation, GtkPrintContext* context )`

  Signal emitted after the user has finished changing print settings in the dialog, before the actual rendering starts.

`paginate: gboolean (* paginate) ( GtkPrintOperation* operation, GtkPrintContext* context )`

  Signal emitted after the “begin-print” signal, but before the actual rendering starts.

`request_page_setup: void (* request_page_setup) ( GtkPrintOperation* operation, GtkPrintContext* context, int page_nr, GtkPageSetup* setup )`

  Emitted once for every page that is printed, to give the application a chance to modify the page setup.

`draw_page: void (* draw_page) ( GtkPrintOperation* operation, GtkPrintContext* context, int page_nr )`

  Signal emitted for every page that is printed.

`end_print: void (* end_print) ( GtkPrintOperation* operation, GtkPrintContext* context )`

  Signal emitted after all pages have been rendered.

`status_changed: void (* status_changed) ( GtkPrintOperation* operation )`

  Emitted at between the various phases of the print operation.

`create_custom_widget: GtkWidget* (* create_custom_widget) ( GtkPrintOperation* operation )`

  Signal emitted when displaying the print dialog.

`custom_widget_apply: void (* custom_widget_apply) ( GtkPrintOperation* operation, GtkWidget* widget )`

  Signal emitted right before “begin-print” if you added a custom widget in the “create-custom-widget” handler.

`preview: gboolean (* preview) ( GtkPrintOperation* operation, GtkPrintOperationPreview* preview, GtkPrintContext* context, GtkWindow* parent )`

  Signal emitted when a preview is requested from the native dialog.

`update_custom_widget: void (* update_custom_widget) ( GtkPrintOperation* operation, GtkWidget* widget, GtkPageSetup* setup, GtkPrintSettings* settings )`

  Emitted after change of selected printer.

#### Virtual methods

###### Gtk.PrintOperationClass.begin_print

Signal emitted after the user has finished changing print settings in the dialog, before the actual rendering starts.

since: 4.0

###### Gtk.PrintOperationClass.create_custom_widget

Signal emitted when displaying the print dialog.

since: 4.0

###### Gtk.PrintOperationClass.custom_widget_apply

Signal emitted right before “begin-print” if you added a custom widget in the “create-custom-widget” handler.

since: 4.0

###### Gtk.PrintOperationClass.done

Signal emitted when the print operation run has finished doing everything required for printing.

since: 4.0

###### Gtk.PrintOperationClass.draw_page

Signal emitted for every page that is printed.

since: 4.0

###### Gtk.PrintOperationClass.end_print

Signal emitted after all pages have been rendered.

since: 4.0

###### Gtk.PrintOperationClass.paginate

Signal emitted after the “begin-print” signal, but before the actual rendering starts.

since: 4.0

###### Gtk.PrintOperationClass.preview

Signal emitted when a preview is requested from the native dialog.

since: 4.0

###### Gtk.PrintOperationClass.request_page_setup

Emitted once for every page that is printed, to give the application a chance to modify the page setup.

since: 4.0

###### Gtk.PrintOperationClass.status_changed

Emitted at between the various phases of the print operation.

since: 4.0

###### Gtk.PrintOperationClass.update_custom_widget

Emitted after change of selected printer.

since: 4.0