GtkPrintOperation
High-level Printing API
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 ::draw-page, which you are supposed
to catch 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_print_preview_render_page(),
gtk_print_operation_preview_end_preview() and
gtk_print_operation_preview_is_selected() are useful
when implementing a print preview.
Printing support was added in GTK+ 2.10.
#GtkPrintContext, #GtkPrintUnixDialog
@printoperation:
@context:
@printoperation:
@Returns:
@printoperation:
@widget:
@printoperation: the object which received the signal.
@arg1:
@printoperation: the object which received the signal.
@arg1:
@arg2:
@printoperation: the object which received the signal.
@arg1:
@printoperation: the object which received the signal.
@arg1:
@Returns:
@printoperation: the object which received the signal.
@arg1:
@arg2:
@arg3:
@Returns:
@printoperation: the object which received the signal.
@arg1:
@arg2:
@arg3:
@printoperation: the object which received the signal.
The status gives a rough indication of the completion
of a running print operation.
@GTK_PRINT_STATUS_INITIAL: The printing has not started yet; this
status is set initially, and while the print dialog is shown.
@GTK_PRINT_STATUS_PREPARING: This status is set while the begin-print
signal is emitted and during pagination.
@GTK_PRINT_STATUS_GENERATING_DATA: This status is set while the
pages are being rendered.
@GTK_PRINT_STATUS_SENDING_DATA: The print job is being sent off to the
printer.
@GTK_PRINT_STATUS_PENDING: The print job has been sent to the printer,
but is not printed for some reason, e.g. the printer may be stopped.
@GTK_PRINT_STATUS_PENDING_ISSUE: Some problem has occurred during
printing, e.g. a paper jam.
@GTK_PRINT_STATUS_PRINTING: The printer is processing the print job.
@GTK_PRINT_STATUS_FINISHED: The printing has been completed successfully.
@GTK_PRINT_STATUS_FINISHED_ABORTED: The printing has been aborted.
The @action parameter to gtk_print_operation_run()
determines what action the print operation should perform.
@GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG: Show the print dialog.
@GTK_PRINT_OPERATION_ACTION_PRINT: Start to print without showing
the print dialog, based on the current print settings.
@GTK_PRINT_OPERATION_ACTION_PREVIEW: Show the print preview.
@GTK_PRINT_OPERATION_ACTION_EXPORT: Export to a file. This requires
the export-filename property to be set.
A value of this type is returned by gtk_print_operation_run().
@GTK_PRINT_OPERATION_RESULT_ERROR: An error has occured.
@GTK_PRINT_OPERATION_RESULT_APPLY: The print settings should be stored.
@GTK_PRINT_OPERATION_RESULT_CANCEL: The print operation has been canceled,
the print settings should not be stored.
@GTK_PRINT_OPERATION_RESULT_IN_PROGRESS: The print operation is not complete
yet. This value will only be returned when running asynchronously.
Error codes that identify various errors that can occur while
using the GTK+ printing support.
@GTK_PRINT_ERROR_GENERAL: An unspecified error occurred.
@GTK_PRINT_ERROR_INTERNAL_ERROR: An internal error occurred.
@GTK_PRINT_ERROR_NOMEM: A memory allocation failed.
@GTK_PRINT_ERROR_INVALID_FILE: An error occurred while loading a page setup
or paper size from a key file.
The #GQuark used for #GtkPrintError errors.
@Returns:
@op:
@allow_async:
@op:
@error:
@op:
@default_page_setup:
@op:
@Returns:
@op:
@print_settings:
@op:
@Returns:
@op:
@job_name:
@op:
@n_pages:
@op:
@current_page:
@op:
@full_page:
@op:
@unit:
@op:
@filename:
@op:
@show_progress:
@op:
@track_status:
@op:
@label:
@op:
@action:
@parent:
@error:
@Returns:
@op:
@op:
@op:
@op:
@Returns:
@op:
@Returns:
@op:
@Returns:
@parent:
@page_setup:
@settings:
@Returns:
The type of function that is passed to gtk_print_run_page_setup_dialog_async().
This function will be called when the page setup dialog is dismissed, and
also serves as destroy notify for @data.
@page_setup: the #GtkPageSetup that has been
@data: user data that has been passed to
gtk_print_run_page_setup_dialog_async().
@parent:
@page_setup:
@settings:
@done_cb:
@data:
@printoperationpreview: the object which received the signal.
@arg1:
@arg2:
@printoperationpreview: the object which received the signal.
@arg1:
@preview:
@preview:
@page_nr:
@Returns:
@preview:
@page_nr: