PrintOperation
Superclasses: Object
Implemented Interfaces: 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 PrintUnixDialog
.
The typical way to use the high-level printing API is to create
a GtkPrintOperation
object with new
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 GtkPrintOperation
, the main one being
draw_page
, which you are supposed to handle
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.
Constructors
- class PrintOperation
- classmethod new() PrintOperation
Creates a new
GtkPrintOperation
.
Methods
- class PrintOperation
- cancel() None
Cancels a running print operation.
This function may be called from a
begin_print
,paginate
ordraw_page
signal handler to stop the currently running print operation.
- draw_page_finish() None
Signal that drawing of particular page is complete.
It is called after completion of page drawing (e.g. drawing in another thread). If
set_defer_drawing
was called before, then this function has to be called by application. Otherwise it is called by GTK itself.
- get_error() None
Call this when the result of a print operation is
ERROR
.It can be called either after
run
returns, or in thedone
signal handler.The returned
GError
will contain more details on what went wrong.
- get_n_pages_to_print() int
Returns the number of pages that will be printed.
Note that this value is set during print preparation phase (
PREPARING
), so this function should never be called before the data generation phase (GENERATING_DATA
). You can connect to thestatus_changed
signal and callget_n_pages_to_print()
when print status isGENERATING_DATA
.This is typically used to track the progress of print operation.
- get_print_settings() PrintSettings | None
Returns the current print settings.
Note that the return value is
None
until eitherset_print_settings
orrun
have been called.
- get_status() PrintStatus
Returns the status of the print operation.
Also see
get_status_string
.
- get_status_string() str
Returns a string representation of the status of the print operation.
The string is translated and suitable for displaying the print status e.g. in a
GtkStatusbar
.Use
get_status
to obtain a status value that is suitable for programmatic use.
- is_finished() bool
A convenience function to find out if the print operation is finished.
a print operation is finished if its status is either
FINISHED
orFINISHED_ABORTED
.Note: when you enable print status tracking the print operation can be in a non-finished state even after done has been called, as the operation status then tracks the print job status on the printer.
- run(action: PrintOperationAction, parent: Window | None = None) PrintOperationResult
Runs the print operation.
Normally that this function does not return until the rendering of all pages is complete. You can connect to the
status_changed
signal onop
to obtain some information about the progress of the print operation.Furthermore, it may use a recursive mainloop to show the print dialog.
If you set the [Gtk.PrintOperation:allow-async] property, the operation will run asynchronously if this is supported on the platform. The
done
signal will be emitted with the result of the operation when the it is done (i.e. when the dialog is canceled, or when the print succeeds or fails).if (settings != NULL) gtk_print_operation_set_print_settings (print, settings); if (page_setup != NULL) gtk_print_operation_set_default_page_setup (print, page_setup); g_signal_connect (print, "begin-print", G_CALLBACK (begin_print), &data); g_signal_connect (print, "draw-page", G_CALLBACK (draw_page), &data); res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, parent, &error); if (res == GTK_PRINT_OPERATION_RESULT_ERROR) { error_dialog = gtk_message_dialog_new (GTK_WINDOW (parent), GTK_DIALOG_DESTROY_WITH_PARENT, GTK_MESSAGE_ERROR, GTK_BUTTONS_CLOSE, "Error printing file:\n``%s``", error->message); g_signal_connect (error_dialog, "response", G_CALLBACK (gtk_window_destroy), NULL); gtk_window_present (GTK_WINDOW (error_dialog)); g_error_free (error); } else 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)); }
Note that
run()
can only be called once on a givenGtkPrintOperation
.- Parameters:
action – the action to start
parent – Transient parent of the dialog
- set_allow_async(allow_async: bool) None
Sets whether
run()
may return before the print operation is completed.Note that some platforms may not allow asynchronous operation.
- Parameters:
allow_async –
True
to allow asynchronous operation
- set_current_page(current_page: int) None
Sets the current page.
If this is called before
run
, the user will be able to select to print only the current page.Note that this only makes sense for pre-paginated documents.
- Parameters:
current_page – the current page, 0-based
- set_custom_tab_label(label: str | None = None) None
Sets the label for the tab holding custom widgets.
- Parameters:
label – the label to use, or
None
to use the default label
- set_default_page_setup(default_page_setup: PageSetup | None = None) None
Makes
default_page_setup
the default page setup forop
.This page setup will be used by
run
, but it can be overridden on a per-page basis by connecting to therequest_page_setup
signal.- Parameters:
default_page_setup – a
GtkPageSetup
- set_defer_drawing() None
Sets up the
GtkPrintOperation
to wait for calling of [method``Gtk``.PrintOperation.draw_page_finish from application.This can be used for drawing page in another thread.
This function must be called in the callback of the
draw_page
signal.
- set_embed_page_setup(embed: bool) None
Embed page size combo box and orientation combo box into page setup page.
Selected page setup is stored as default page setup in
GtkPrintOperation
.- Parameters:
embed –
True
to embed page setup selection in theGtkPrintUnixDialog
- set_export_filename(filename: str) None
Sets up the
GtkPrintOperation
to generate a file instead of showing the print dialog.The intended use of this function is for implementing “Export to PDF” actions. Currently, PDF is the only supported format.
“Print to PDF” support is independent of this and is done by letting the user pick the “Print to PDF” item from the list of printers in the print dialog.
- Parameters:
filename – the filename for the exported file
- set_has_selection(has_selection: bool) None
Sets whether there is a selection to print.
Application has to set number of pages to which the selection will draw by
set_n_pages
in a handler for thebegin_print
signal.- Parameters:
has_selection –
True
indicates that a selection exists
- set_job_name(job_name: str) None
Sets the name of the print job.
The name is used to identify the job (e.g. in monitoring applications like eggcups).
If you don’t set a job name, GTK picks a default one by numbering successive print jobs.
- Parameters:
job_name – a string that identifies the print job
- set_n_pages(n_pages: int) None
Sets the number of pages in the document.
This must be set to a positive number before the rendering starts. It may be set in a
begin_print
signal handler.Note that the page numbers passed to the
request_page_setup
anddraw_page
signals are 0-based, i.e. if the user chooses to print all pages, the last ::draw-page signal will be for pagen_pages
- 1.- Parameters:
n_pages – the number of pages
- set_print_settings(print_settings: PrintSettings | None = None) None
Sets the print settings for
op
.This is typically used to re-establish print settings from a previous print operation, see
run
.- Parameters:
print_settings –
GtkPrintSettings
- set_show_progress(show_progress: bool) None
If
show_progress
isTrue
, the print operation will show a progress dialog during the print operation.- Parameters:
show_progress –
True
to show a progress dialog
- set_support_selection(support_selection: bool) None
Sets whether selection is supported by
GtkPrintOperation
.- Parameters:
support_selection –
True
to support selection
- set_track_print_status(track_status: bool) None
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.This can allow your application to show things like “out of paper” issues, and when the print job actually reaches the printer.
This function is often implemented using some form of polling, so it should not be enabled unless needed.
- Parameters:
track_status –
True
to track status after printing
- set_unit(unit: Unit) None
Sets up the transformation for the cairo context obtained from
GtkPrintContext
in such a way that distances are measured in units ofunit
.- Parameters:
unit – the unit to use
- set_use_full_page(full_page: bool) None
If
full_page
isTrue
, the transformation for the cairo context obtained fromGtkPrintContext
puts the origin at the top left corner of the page.This may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet). Otherwise, the origin is at the top left corner of the imageable area (i.e. inside the margins).
- Parameters:
full_page –
True
to set up theGtkPrintContext
for the full page
Properties
- class PrintOperation
- props.allow_async: bool
Determines whether the print operation may run asynchronously or not.
Some systems don’t support asynchronous printing, but those that do will return
IN_PROGRESS
as the status, and emit thedone
signal when the operation is actually done.The Windows port does not support asynchronous operation at all (this is unlikely to change). On other platforms, all actions except for
EXPORT
support asynchronous operation.
- props.current_page: int
The current page in the document.
If this is set before
run
, the user will be able to select to print only the current page.Note that this only makes sense for pre-paginated documents.
- props.custom_tab_label: str
Used as the label of the tab containing custom widgets.
Note that this property may be ignored on some platforms.
If this is
None
, GTK uses a default label.
- props.default_page_setup: PageSetup
The
GtkPageSetup
used by default.This page setup will be used by
run
, but it can be overridden on a per-page basis by connecting to therequest_page_setup
signal.
- props.embed_page_setup: bool
If
True
, page size combo box and orientation combo box are embedded into page setup page.
- props.export_filename: str
The name of a file to generate instead of showing the print dialog.
Currently, PDF is the only supported format.
The intended use of this property is for implementing “Export to PDF” actions.
“Print to PDF” support is independent of this and is done by letting the user pick the “Print to PDF” item from the list of printers in the print dialog.
- props.has_selection: bool
Determines whether there is a selection in your application.
This can allow your application to print the selection. This is typically used to make a “Selection” button sensitive.
- props.job_name: str
A string used to identify the job (e.g. in monitoring applications like eggcups).
If you don’t set a job name, GTK picks a default one by numbering successive print jobs.
- props.n_pages: int
The number of pages in the document.
This must be set to a positive number before the rendering starts. It may be set in a
begin_print
signal handler.Note that the page numbers passed to the
request_page_setup
anddraw_page
signals are 0-based, i.e. if the user chooses to print all pages, the last ::draw-page signal will be for pagen_pages
- 1.
- props.n_pages_to_print: int
The number of pages that will be printed.
Note that this value is set during print preparation phase (
PREPARING
), so this value should never be get before the data generation phase (GENERATING_DATA
). You can connect to thestatus_changed
signal and callget_n_pages_to_print
when print status isGENERATING_DATA
.This is typically used to track the progress of print operation.
- props.print_settings: PrintSettings
The
GtkPrintSettings
used for initializing the dialog.Setting this property is typically used to re-establish print settings from a previous print operation, see
run
.
- props.status: PrintStatus
The status of the print operation.
- props.status_string: str
A string representation of the status of the print operation.
The string is translated and suitable for displaying the print status e.g. in a
GtkStatusbar
.See the
status
property for a status value that is suitable for programmatic use.
- props.support_selection: bool
If
True
, the print operation will support print of selection.This allows the print dialog to show a “Selection” button.
- props.track_print_status: bool
If
True
, the print operation will try to continue report on the status of the print job in the printer queues and printer.This can allow your application to show things like “out of paper” issues, and when the print job actually reaches the printer. However, this is often implemented using polling, and should not be enabled unless needed.
- props.unit: Unit
The transformation for the cairo context obtained from
GtkPrintContext
is set up in such a way that distances are measured in units ofunit
.
- props.use_full_page: bool
If
True
, the transformation for the cairo context obtained fromGtkPrintContext
puts the origin at the top left corner of the page.This may not be the top left corner of the sheet, depending on page orientation and the number of pages per sheet. Otherwise, the origin is at the top left corner of the imageable area (i.e. inside the margins).
Signals
- class PrintOperation.signals
- begin_print(context: PrintContext) None
Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts.
A typical use for ::begin-print is to use the parameters from the
PrintContext
and paginate the document accordingly, and then set the number of pages withset_n_pages
.- Parameters:
context – the
GtkPrintContext
for the current operation
- create_custom_widget() Object | None
Emitted when displaying the print dialog.
If you return a widget in a handler for this signal it will be added to a custom tab in the print dialog. You typically return a container widget with multiple widgets in it.
The print dialog owns the returned widget, and its lifetime is not controlled by the application. However, the widget is guaranteed to stay around until the
custom_widget_apply
signal is emitted on the operation. Then you can read out any information you need from the widgets.
- custom_widget_apply(widget: Widget) None
Emitted right before ::begin-print if you added a custom widget in the ::create-custom-widget handler.
When you get this signal you should read the information from the custom widgets, as the widgets are not guaranteed to be around at a later time.
- Parameters:
widget – the custom widget added in ::create-custom-widget
- done(result: PrintOperationResult) None
Emitted when the print operation run has finished doing everything required for printing.
result
gives you information about what happened during the run. Ifresult
isERROR
then you can callget_error
for more information.If you enabled print status tracking then
is_finished
may still returnFalse
after the ::done signal was emitted.- Parameters:
result – the result of the print operation
- draw_page(context: PrintContext, page_nr: int) None
Emitted for every page that is printed.
The signal handler must render the
page_nr
’s page onto the cairo context obtained fromcontext
usingget_cairo_context
.static void draw_page (GtkPrintOperation *operation, GtkPrintContext *context, int page_nr, gpointer user_data) { cairo_t *cr; PangoLayout *layout; double width, text_height; int layout_height; PangoFontDescription *desc; cr = gtk_print_context_get_cairo_context (context); width = gtk_print_context_get_width (context); cairo_rectangle (cr, 0, 0, width, HEADER_HEIGHT); cairo_set_source_rgb (cr, 0.8, 0.8, 0.8); cairo_fill (cr); layout = gtk_print_context_create_pango_layout (context); desc = pango_font_description_from_string ("sans 14"); pango_layout_set_font_description (layout, desc); pango_font_description_free (desc); pango_layout_set_text (layout, "some text", -1); pango_layout_set_width (layout, width * PANGO_SCALE); pango_layout_set_alignment (layout, PANGO_ALIGN_CENTER); pango_layout_get_size (layout, NULL, &layout_height); text_height = (double)layout_height / PANGO_SCALE; cairo_move_to (cr, width / 2, (HEADER_HEIGHT - text_height) / 2); pango_cairo_show_layout (cr, layout); g_object_unref (layout); }
Use
set_use_full_page
andset_unit
before starting the print operation to set up the transformation of the cairo context according to your needs.- Parameters:
context – the
GtkPrintContext
for the current operationpage_nr – the number of the currently printed page (0-based)
- end_print(context: PrintContext) None
Emitted after all pages have been rendered.
A handler for this signal can clean up any resources that have been allocated in the
begin_print
handler.- Parameters:
context – the
GtkPrintContext
for the current operation
- paginate(context: PrintContext) bool
Emitted after the ::begin-print signal, but before the actual rendering starts.
It keeps getting emitted until a connected signal handler returns
True
.The ::paginate signal is intended to be used for paginating a document in small chunks, to avoid blocking the user interface for a long time. The signal handler should update the number of pages using
set_n_pages
, and returnTrue
if the document has been completely paginated.If you don’t need to do pagination in chunks, you can simply do it all in the ::begin-print handler, and set the number of pages from there.
- Parameters:
context – the
GtkPrintContext
for the current operation
- preview(preview: PrintOperationPreview, context: PrintContext, parent: Window | None = None) bool
Gets emitted when a preview is requested from the native dialog.
The default handler for this signal uses an external viewer application to preview.
To implement a custom print preview, an application must return
True
from its handler for this signal. In order to use the providedcontext
for the preview implementation, it must be given a suitable cairo context withset_cairo_context
.The custom preview implementation can use
is_selected
andrender_page
to find pages which are selected for print and render them. The preview must be finished by callingend_preview
(typically in response to the user clicking a close button).- Parameters:
preview – the
GtkPrintOperationPreview
for the current operationcontext – the
GtkPrintContext
that will be usedparent – the
GtkWindow
to use as window parent
- request_page_setup(context: PrintContext, page_nr: int, setup: PageSetup) None
Emitted once for every page that is printed.
This gives the application a chance to modify the page setup. Any changes done to
setup
will be in force only for printing this page.- Parameters:
context – the
GtkPrintContext
for the current operationpage_nr – the number of the currently printed page (0-based)
setup – the
GtkPageSetup
- status_changed() None
Emitted at between the various phases of the print operation.
See
PrintStatus
for the phases that are being discriminated. Useget_status
to find out the current status.
- update_custom_widget(widget: Widget, setup: PageSetup, settings: PrintSettings) None
Emitted after change of selected printer.
The actual page setup and print settings are passed to the custom widget, which can actualize itself according to this change.
- Parameters:
widget – the custom widget added in ::create-custom-widget
setup – actual page setup
settings – actual print settings
Virtual Methods
- class PrintOperation
- do_begin_print(context: PrintContext) None
Signal emitted after the user has finished changing print settings in the dialog, before the actual rendering starts.
- Parameters:
context
- do_custom_widget_apply(widget: Widget) None
Signal emitted right before “begin-print” if you added a custom widget in the “create-custom-widget” handler.
- Parameters:
widget
- do_done(result: PrintOperationResult) None
Signal emitted when the print operation run has finished doing everything required for printing.
- Parameters:
result
- do_draw_page(context: PrintContext, page_nr: int) None
Signal emitted for every page that is printed.
- Parameters:
context
page_nr
- do_end_print(context: PrintContext) None
Signal emitted after all pages have been rendered.
- Parameters:
context
- do_paginate(context: PrintContext) bool
Signal emitted after the “begin-print” signal, but before the actual rendering starts.
- Parameters:
context
- do_preview(preview: PrintOperationPreview, context: PrintContext, parent: Window) bool
Signal emitted when a preview is requested from the native dialog.
- Parameters:
preview
context
parent
- do_request_page_setup(context: PrintContext, page_nr: int, setup: PageSetup) None
Emitted once for every page that is printed, to give the application a chance to modify the page setup.
- Parameters:
context
page_nr
setup
- do_update_custom_widget(widget: Widget, setup: PageSetup, settings: PrintSettings) None
Emitted after change of selected printer.
- Parameters:
widget
setup
settings