Synopsis#include <gtk/gtk.h> GtkPrintOperation; enum GtkPrintStatus; enum GtkPrintOperationAction; enum GtkPrintOperationResult; enum GtkPrintError; #define GTK_PRINT_ERROR GtkPrintOperation* gtk_print_operation_new (void); void gtk_print_operation_set_allow_async (GtkPrintOperation *op, gboolean allow_async); void gtk_print_operation_get_error (GtkPrintOperation *op, GError **error); void gtk_print_operation_set_default_page_setup (GtkPrintOperation *op, GtkPageSetup *default_page_setup); GtkPageSetup* gtk_print_operation_get_default_page_setup (GtkPrintOperation *op); void gtk_print_operation_set_print_settings (GtkPrintOperation *op, GtkPrintSettings *print_settings); GtkPrintSettings* gtk_print_operation_get_print_settings (GtkPrintOperation *op); void gtk_print_operation_set_job_name (GtkPrintOperation *op, const gchar *job_name); void gtk_print_operation_set_n_pages (GtkPrintOperation *op, gint n_pages); void gtk_print_operation_set_current_page (GtkPrintOperation *op, gint current_page); void gtk_print_operation_set_use_full_page (GtkPrintOperation *op, gboolean full_page); void gtk_print_operation_set_unit (GtkPrintOperation *op, GtkUnit unit); void gtk_print_operation_set_export_filename (GtkPrintOperation *op, const gchar *filename); void gtk_print_operation_set_show_progress (GtkPrintOperation *op, gboolean show_progress); void gtk_print_operation_set_track_print_status (GtkPrintOperation *op, gboolean track_status); void gtk_print_operation_set_custom_tab_label (GtkPrintOperation *op, const gchar *label); GtkPrintOperationResult gtk_print_operation_run (GtkPrintOperation *op, GtkPrintOperationAction action, GtkWindow *parent, GError **error); void gtk_print_operation_cancel (GtkPrintOperation *op); GtkPrintStatus gtk_print_operation_get_status (GtkPrintOperation *op); const gchar* gtk_print_operation_get_status_string (GtkPrintOperation *op); gboolean gtk_print_operation_is_finished (GtkPrintOperation *op); GtkPageSetup* gtk_print_run_page_setup_dialog (GtkWindow *parent, GtkPageSetup *page_setup, GtkPrintSettings *settings); void (*GtkPageSetupDoneFunc) (GtkPageSetup *page_setup, gpointer data); void gtk_print_run_page_setup_dialog_async (GtkWindow *parent, GtkPageSetup *page_setup, GtkPrintSettings *settings, GtkPageSetupDoneFunc done_cb, gpointer data); GtkPrintOperationPreview; void gtk_print_operation_preview_end_preview (GtkPrintOperationPreview *preview); gboolean gtk_print_operation_preview_is_selected (GtkPrintOperationPreview *preview, gint page_nr); void gtk_print_operation_preview_render_page (GtkPrintOperationPreview *preview, gint page_nr); Properties"allow-async" gboolean : Read / Write "current-page" gint : Read / Write "custom-tab-label" gchar* : Read / Write "default-page-setup" GtkPageSetup* : Read / Write "export-filename" gchar* : Read / Write "job-name" gchar* : Read / Write "n-pages" gint : Read / Write "print-settings" GtkPrintSettings* : Read / Write "show-progress" gboolean : Read / Write "status" GtkPrintStatus : Read "status-string" gchar* : Read "track-print-status" gboolean : Read / Write "unit" GtkUnit : Read / Write "use-full-page" gboolean : Read / Write Signals"begin-print" : Run Last "create-custom-widget" : Run Last "custom-widget-apply" : Run Last "done" : Run Last "draw-page" : Run Last "end-print" : Run Last "paginate" : Run Last "preview" : Run Last "request-page-setup" : Run Last "status-changed" : Run Last "got-page-size" : Run Last "ready" : Run Last DescriptionGtkPrintOperation 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
Then you start the print operation by calling Example 41. 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
Printing support was added in GTK+ 2.10. Detailsenum GtkPrintStatustypedef enum { GTK_PRINT_STATUS_INITIAL, GTK_PRINT_STATUS_PREPARING, GTK_PRINT_STATUS_GENERATING_DATA, GTK_PRINT_STATUS_SENDING_DATA, GTK_PRINT_STATUS_PENDING, GTK_PRINT_STATUS_PENDING_ISSUE, GTK_PRINT_STATUS_PRINTING, GTK_PRINT_STATUS_FINISHED, GTK_PRINT_STATUS_FINISHED_ABORTED } GtkPrintStatus; The status gives a rough indication of the completion of a running print operation.
enum GtkPrintOperationActiontypedef enum { GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, GTK_PRINT_OPERATION_ACTION_PRINT, GTK_PRINT_OPERATION_ACTION_PREVIEW, GTK_PRINT_OPERATION_ACTION_EXPORT } GtkPrintOperationAction;
The
enum GtkPrintOperationResulttypedef enum { GTK_PRINT_OPERATION_RESULT_ERROR, GTK_PRINT_OPERATION_RESULT_APPLY, GTK_PRINT_OPERATION_RESULT_CANCEL, GTK_PRINT_OPERATION_RESULT_IN_PROGRESS } GtkPrintOperationResult;
A value of this type is returned by
enum GtkPrintErrortypedef enum { GTK_PRINT_ERROR_GENERAL, GTK_PRINT_ERROR_INTERNAL_ERROR, GTK_PRINT_ERROR_NOMEM, GTK_PRINT_ERROR_INVALID_FILE } GtkPrintError;
GTK_PRINT_ERROR#define GTK_PRINT_ERROR gtk_print_error_quark () The GQuark used for GtkPrintError errors. gtk_print_operation_new ()GtkPrintOperation* gtk_print_operation_new (void); Creates a new GtkPrintOperation.
Since 2.10 gtk_print_operation_set_allow_async ()void gtk_print_operation_set_allow_async (GtkPrintOperation *op, gboolean allow_async);
Sets whether the
Since 2.10 gtk_print_operation_get_error ()void gtk_print_operation_get_error (GtkPrintOperation *op, GError **error);
Call this when the result of a print operation is
Since 2.10 gtk_print_operation_set_default_page_setup ()void gtk_print_operation_set_default_page_setup (GtkPrintOperation *op, GtkPageSetup *default_page_setup);
Makes
This page setup will be used by
Since 2.10 gtk_print_operation_get_default_page_setup ()GtkPageSetup* gtk_print_operation_get_default_page_setup (GtkPrintOperation *op);
Returns the default page setup, see
Since 2.10 gtk_print_operation_set_print_settings ()void gtk_print_operation_set_print_settings (GtkPrintOperation *op, GtkPrintSettings *print_settings);
Sets the print settings for
Since 2.10 gtk_print_operation_get_print_settings ()GtkPrintSettings* gtk_print_operation_get_print_settings (GtkPrintOperation *op); Returns the current print settings.
Note that the return value is
Since 2.10 gtk_print_operation_set_job_name ()void gtk_print_operation_set_job_name (GtkPrintOperation *op, const gchar *job_name); 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.
Since 2.10 gtk_print_operation_set_n_pages ()void gtk_print_operation_set_n_pages (GtkPrintOperation *op, gint n_pages); 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 hander.
Note that the page numbers passed to the
"request-page-setup"
and "draw-page" signals are 0-based, i.e. if
the user chooses to print all pages, the last ::draw-page signal
will be for page
Since 2.10 gtk_print_operation_set_current_page ()void gtk_print_operation_set_current_page (GtkPrintOperation *op, gint current_page); Sets the current page.
If this is called before Note that this only makes sense for pre-paginated documents.
Since 2.10 gtk_print_operation_set_use_full_page ()void gtk_print_operation_set_use_full_page (GtkPrintOperation *op, gboolean full_page);
If
Since 2.10 gtk_print_operation_set_unit ()void gtk_print_operation_set_unit (GtkPrintOperation *op, GtkUnit unit);
Sets up the transformation for the cairo context obtained from
GtkPrintContext in such a way that distances are measured in
units of
Since 2.10 gtk_print_operation_set_export_filename ()void gtk_print_operation_set_export_filename (GtkPrintOperation *op, const gchar *filename); Sets up the GtkPrintOperation to generate a file instead of showing the print dialog. The indended 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.
Since 2.10 gtk_print_operation_set_show_progress ()void gtk_print_operation_set_show_progress (GtkPrintOperation *op, gboolean show_progress);
If
Since 2.10 gtk_print_operation_set_track_print_status ()void gtk_print_operation_set_track_print_status (GtkPrintOperation *op, gboolean track_status);
If track_status is This function is often implemented using some form of polling, so it should not be enabled unless needed.
Since 2.10 gtk_print_operation_set_custom_tab_label ()void gtk_print_operation_set_custom_tab_label (GtkPrintOperation *op, const gchar *label); Sets the label for the tab holding custom widgets.
Since 2.10 gtk_print_operation_run ()GtkPrintOperationResult gtk_print_operation_run (GtkPrintOperation *op, GtkPrintOperationAction action, GtkWindow *parent, GError **error); Runs the print operation, by first letting the user modify print settings in the print dialog, and then print the document.
Normally that this function does not return until the rendering of all
pages is complete. You can connect to the
"status-changed" signal on
If you call 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_widget_destroy), NULL); gtk_widget_show (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
Since 2.10 gtk_print_operation_cancel ()void gtk_print_operation_cancel (GtkPrintOperation *op); Cancels a running print operation. This function may be called from a "begin-print", "paginate" or "draw-page" signal handler to stop the currently running print operation.
Since 2.10 gtk_print_operation_get_status ()GtkPrintStatus gtk_print_operation_get_status (GtkPrintOperation *op);
Returns the status of the print operation.
Also see
Since 2.10 gtk_print_operation_get_status_string ()const gchar* gtk_print_operation_get_status_string (GtkPrintOperation *op); 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
Since 2.10 gtk_print_operation_is_finished ()gboolean gtk_print_operation_is_finished (GtkPrintOperation *op);
A convenience function to find out if the print operation
is finished, either successfully ( 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.
Since 2.10 gtk_print_run_page_setup_dialog ()GtkPageSetup* gtk_print_run_page_setup_dialog (GtkWindow *parent, GtkPageSetup *page_setup, GtkPrintSettings *settings);
Runs a page setup dialog, letting the user modify the values from
Note that this function may use a recursive mainloop to show the page
setup dialog. See
Since 2.10 GtkPageSetupDoneFunc ()void (*GtkPageSetupDoneFunc) (GtkPageSetup *page_setup, gpointer data);
The type of function that is passed to
gtk_print_run_page_setup_dialog_async ()void gtk_print_run_page_setup_dialog_async (GtkWindow *parent, GtkPageSetup *page_setup, GtkPrintSettings *settings, GtkPageSetupDoneFunc done_cb, gpointer data);
Runs a page setup dialog, letting the user modify the values from
In contrast to
Since 2.10 gtk_print_operation_preview_end_preview ()void gtk_print_operation_preview_end_preview (GtkPrintOperationPreview *preview); Ends a preview. This function must be called to finish a custom print preview.
Since 2.10 gtk_print_operation_preview_is_selected ()gboolean gtk_print_operation_preview_is_selected (GtkPrintOperationPreview *preview, gint page_nr); Returns whether the given page is included in the set of pages that have been selected for printing.
Since 2.10 gtk_print_operation_preview_render_page ()void gtk_print_operation_preview_render_page (GtkPrintOperationPreview *preview, gint page_nr);
Renders a page to the preview, using the print context that
was passed to the "preview" handler together
with Note that this function requires a suitable cairo context to be associated with the print context.
Since 2.10 Property DetailsThe
|
|
the GtkPrintOperation on which the signal was emitted |
|
the GtkPrintContext for the current operation |
|
user data set when the signal handler was connected. |
Since 2.10
"create-custom-widget"
signalGObject* user_function (GtkPrintOperation *operation, gpointer user_data) : Run Last
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.
|
the GtkPrintOperation on which the signal was emitted |
|
user data set when the signal handler was connected. |
Returns : |
A custom widget that gets embedded in the print dialog,
or NULL
|
Since 2.10
"custom-widget-apply"
signalvoid user_function (GtkPrintOperation *operation, GtkWidget *widget, gpointer user_data) : Run Last
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 guaraneed to be around at a later time.
|
the GtkPrintOperation on which the signal was emitted |
|
the custom widget added in create-custom-widget |
|
user data set when the signal handler was connected. |
Since 2.10
"done"
signalvoid user_function (GtkPrintOperation *operation, GtkPrintOperationResult result, gpointer user_data) : Run Last
Emitted when the print operation run has finished doing everything required for printing.
result
gives you information about what happened during the run.
If result
is GTK_PRINT_OPERATION_RESULT_ERROR
then you can call
gtk_print_operation_get_error()
for more information.
If you enabled print status tracking then
gtk_print_operation_is_finished()
may still return FALSE
after "done" was emitted.
|
the GtkPrintOperation on which the signal was emitted |
|
the result of the print operation |
|
user data set when the signal handler was connected. |
Since 2.10
"draw-page"
signalvoid user_function (GtkPrintOperation *operation, GtkPrintContext *context, gint page_nr, gpointer user_data) : Run Last
Emitted for every page that is printed. The signal handler
must render the page_nr
's page onto the cairo context obtained
from context
using gtk_print_context_get_cairo_context()
.
static void draw_page (GtkPrintOperation *operation, GtkPrintContext *context, gint page_nr, gpointer user_data) { cairo_t *cr; PangoLayout *layout; gdouble width, text_height; gint 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 = (gdouble)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 gtk_print_operation_set_use_full_page()
and
gtk_print_operation_set_unit()
before starting the print operation
to set up the transformation of the cairo context according to your
needs.
|
the GtkPrintOperation on which the signal was emitted |
|
the GtkPrintContext for the current operation |
|
the number of the currently printed page |
|
user data set when the signal handler was connected. |
Since 2.10
"end-print"
signalvoid user_function (GtkPrintOperation *operation, GtkPrintContext *context, gpointer user_data) : Run Last
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.
|
the GtkPrintOperation on which the signal was emitted |
|
the GtkPrintContext for the current operation |
|
user data set when the signal handler was connected. |
Since 2.10
"paginate"
signalgboolean user_function (GtkPrintOperation *operation, GtkPrintContext *context, gpointer user_data) : Run Last
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
gtk_print_operation_set_n_pages()
, and return TRUE
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.
|
the GtkPrintOperation on which the signal was emitted |
|
the GtkPrintContext for the current operation |
|
user data set when the signal handler was connected. |
Returns : |
TRUE if pagination is complete
|
Since 2.10
"preview"
signalgboolean user_function (GtkPrintOperation *operation, GtkPrintOperationPreview *preview, GtkPrintContext *context, GtkWindow *parent, gpointer user_data) : Run Last
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
provided context
for the preview implementation, it must be
given a suitable cairo context with gtk_print_context_set_cairo_context()
.
The custom preview implementation can use
gtk_print_operation_preview_is_selected()
and
gtk_print_operation_preview_render_page()
to find pages which
are selected for print and render them. The preview must be
finished by calling gtk_print_operation_preview_end_preview()
(typically in response to the user clicking a close button).
|
the GtkPrintOperation on which the signal was emitted |
|
the GtkPrintPreviewOperation for the current operation |
|
the GtkPrintContext that will be used |
|
the GtkWindow to use as window parent, or NULL
|
|
user data set when the signal handler was connected. |
Returns : |
TRUE if the listener wants to take over control of the preview
|
Since 2.10
"request-page-setup"
signalvoid user_function (GtkPrintOperation *operation, GtkPrintContext *context, gint page_nr, GtkPageSetup *setup, gpointer user_data) : Run Last
Emitted once for every page that is printed, to give
the application a chance to modify the page setup. Any changes
done to setup
will be in force only for printing this page.
|
the GtkPrintOperation on which the signal was emitted |
|
the GtkPrintContext for the current operation |
|
the number of the currently printed page |
|
the GtkPageSetup |
|
user data set when the signal handler was connected. |
Since 2.10
"status-changed"
signalvoid user_function (GtkPrintOperation *operation, gpointer user_data) : Run Last
Emitted at between the various phases of the print operation.
See GtkPrintStatus for the phases that are being discriminated.
Use gtk_print_operation_get_status()
to find out the current
status.
|
the GtkPrintOperation on which the signal was emitted |
|
user data set when the signal handler was connected. |
Since 2.10
"got-page-size"
signalvoid user_function (GtkPrintOperationPreview *printoperationpreview, GtkPrintContext *arg1, GtkPageSetup *arg2, gpointer user_data) : Run Last
|
the object which received the signal. |
|
|
|
|
|
user data set when the signal handler was connected. |
"ready"
signalvoid user_function (GtkPrintOperationPreview *printoperationpreview, GtkPrintContext *arg1, gpointer user_data) : Run Last
|
the object which received the signal. |
|
|
|
user data set when the signal handler was connected. |