PrintOperation

Object Hierarchy:

Description:

[ CCode ( type_id = "gtk_print_operation_get_type ()" ) ]
public class PrintOperation : Object, PrintOperationPreview

`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 [class@Gtk.PrintUnixDialog].

The typical way to use the high-level printing API is to create a `GtkPrintOperation` object with [ctor@Gtk.PrintOperation.new] when the user selects to print. Then you set some properties on it, e.g. the page size, any [class@Gtk.PrintSettings] from previous print operations, the number of pages, the current page, etc.

Then you start the print operation by calling [method@Gtk.PrintOperation.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 [ signal@Gtk.PrintOperation:GtkPrintOperation:draw-page], which you are supposed to handle and render the page on the provided [ class@Gtk.PrintContext] using Cairo.

The high-level printing API

```c 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 [method@Gtk.PrintOperationPreview.render_page], [method@Gtk.PrintOperationPreview.end_preview] and [method@Gtk.PrintOperationPreview.is_selected] are useful when implementing a print preview.

Namespace: Gtk

Package: gtk4

Content:

Properties:

public bool allow_async { get; set; }
Determines whether the print operation may run asynchronously or not.
public int current_page { get; set; }
The current page in the document.
public string custom_tab_label { owned get; set; }
Used as the label of the tab containing custom widgets.
public PageSetup default_page_setup { get; set; }
The `GtkPageSetup` used by default.
public bool embed_page_setup { get; set; }
If true, page size combo box and orientation combo box are embedded into page setup page.
public string export_filename { owned get; set; }
The name of a file to generate instead of showing the print dialog.
public bool has_selection { get; set; }
Determines whether there is a selection in your application.
public string job_name { owned get; set; }
A string used to identify the job (e.
public int n_pages { get; set; }
The number of pages in the document.
public int n_pages_to_print { get; }
The number of pages that will be printed.
public PrintSettings print_settings { get; set; }
The `GtkPrintSettings` used for initializing the dialog.
public bool show_progress { get; set; }
Determines whether to show a progress dialog during the print operation.
public PrintStatus status { get; }
The status of the print operation.
public string status_string { get; }
A string representation of the status of the print operation.
public bool support_selection { get; set; }
If true, the print operation will support print of selection.
public bool track_print_status { get; set; }
If true, the print operation will try to continue report on the status of the print job in the printer queues and printer.
public Unit unit { get; set; }
The transformation for the cairo context obtained from `GtkPrintContext` is set up in such a way that distances are measured in units of unit.
public bool use_full_page { get; set; }
If true, the transformation for the cairo context obtained from `GtkPrintContext` puts the origin at the top left corner of the page.

Creation methods:

public PrintOperation ()
Creates a new `GtkPrintOperation`.

Methods:

public void cancel ()
Cancels a running print operation.
public void draw_page_finish ()
Signal that drawing of particular page is complete.
public unowned PageSetup get_default_page_setup ()
Returns the default page setup.
public bool get_embed_page_setup ()
Gets whether page setup selection combos are embedded
public void get_error () throws Error
Call this when the result of a print operation is gtk_print_operation_result_error.
public bool get_has_selection ()
Gets whether there is a selection.
public int get_n_pages_to_print ()
Returns the number of pages that will be printed.
public unowned PrintSettings? get_print_settings ()
Returns the current print settings.
public PrintStatus get_status ()
Returns the status of the print operation.
public unowned string get_status_string ()
Returns a string representation of the status of the print operation.
public bool get_support_selection ()
Gets whether the application supports print of selection
public bool is_finished ()
A convenience function to find out if the print operation is finished.
public PrintOperationResult run (PrintOperationAction action, Window? parent) throws Error
Runs the print operation.
public void set_allow_async (bool allow_async)
Sets whether run may return before the print operation is completed.
public void set_current_page (int current_page)
Sets the current page.
public void set_custom_tab_label (string? label)
Sets the label for the tab holding custom widgets.
public void set_default_page_setup (PageSetup? default_page_setup)
Makes default_page_setup the default page setup for this.
public void set_defer_drawing ()
Sets up the `GtkPrintOperation` to wait for calling of [method@Gtk.
public void set_embed_page_setup (bool embed)
Embed page size combo box and orientation combo box into page setup page.
public void set_export_filename (string filename)
Sets up the `GtkPrintOperation` to generate a file instead of showing the print dialog.
public void set_has_selection (bool has_selection)
Sets whether there is a selection to print.
public void set_job_name (string job_name)
Sets the name of the print job.
public void set_n_pages (int n_pages)
Sets the number of pages in the document.
public void set_print_settings (PrintSettings? print_settings)
Sets the print settings for this.
public void set_show_progress (bool show_progress)
If show_progress is true, the print operation will show a progress dialog during the print operation.
public void set_support_selection (bool support_selection)
Sets whether selection is supported by `GtkPrintOperation`.
public void set_track_print_status (bool track_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.
public void set_unit (Unit unit)
Sets up the transformation for the cairo context obtained from `GtkPrintContext` in such a way that distances are measured in units of unit.
public void set_use_full_page (bool 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.

Signals:

public virtual signal void begin_print (PrintContext context)
Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts.
public virtual signal unowned Object? create_custom_widget ()
Emitted when displaying the print dialog.
public virtual signal void custom_widget_apply (Widget widget)
Emitted right before begin_print if you added a custom widget in the create_custom_widget handler.
public virtual signal void done (PrintOperationResult result)
Emitted when the print operation run has finished doing everything required for printing.
public virtual signal void draw_page (PrintContext context, int page_nr)
Emitted for every page that is printed.
public virtual signal void end_print (PrintContext context)
Emitted after all pages have been rendered.
public virtual signal bool paginate (PrintContext context)
Emitted after the begin_print signal, but before the actual rendering starts.
public virtual signal bool preview (PrintOperationPreview preview, PrintContext context, Window? parent)
Gets emitted when a preview is requested from the native dialog.
public virtual signal void request_page_setup (PrintContext context, int page_nr, PageSetup setup)
Emitted once for every page that is printed.
public virtual signal void status_changed ()
Emitted at between the various phases of the print operation.
public virtual signal void update_custom_widget (Widget widget, PageSetup setup, PrintSettings settings)
Emitted after change of selected printer.

Inherited Members:

All known members inherited from class GLib.Object

All known members inherited from interface Gtk.PrintOperationPreview

render_page