GtkPrintOperation is the high-level, portable printing API.
It looks a bit different than other GTK+ dialogs such as the FileChooser, 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
PrintOperation when the user selects to print. Then you
set some properties on it, e.g. the page size, any PrintSettings from previous
print operations, the number of pages, the current page, etc.
Then you start the print operation by calling 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
PrintOperation, the main one being draw_page, which you are
supposed to catch and render the page on the provided PrintContext 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 render_page,
end_preview and
is_selected are useful when implementing a print
preview.
- 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; }
- 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; }
- 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
PrintContext 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 PrintContext puts the origin at the top left corner of the
page (which may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet).
- public void cancel ()
Cancels a running print operation.
- public void draw_page_finish ()
Signalize that drawing of particular page is complete.
- public unowned PageSetup get_default_page_setup ()
- public bool get_embed_page_setup ()
- public void get_error () throws Error
Call this when the result of a print operation is
gtk_print_operation_result_error, either as returned by
run, or in the
done signal handler.
- public bool get_has_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 ()
- public bool is_finished ()
A convenience function to find out if the print operation is finished,
either successfully (gtk_print_status_finished) or unsuccessfully (
gtk_print_status_finished_aborted).
- public PrintOperationResult run (PrintOperationAction action, Window? parent) throws Error
Runs the print operation, by first letting the user modify print settings in
the print dialog, and then print the document.
- public void set_allow_async (bool allow_async)
Sets whether the
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 PrintOperation to wait for calling of
draw_page_finish from application.
- 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 PrintOperation 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 PrintOperation
.
- 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
PrintContext 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 PrintContext puts the origin
at the top left corner of the page (which may not be the top left corner of the sheet, depending on page orientation and the number of pages
per sheet).