Class

GtkPrintOperation

Description [src]

class Gtk.PrintOperation : GObject.Object
  implements Gtk.PrintOperationPreview {
  /* No available fields */
}

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 GtkPrintOperation::draw-page, which you are supposed to handle 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_preview_render_page(), gtk_print_operation_preview_end_preview() and gtk_print_operation_preview_is_selected() are useful when implementing a print preview.

Hierarchy

Ancestors

GObject

Implements

GtkPrintOperationPreview

Constructors

gtk_print_operation_new

Creates a new GtkPrintOperation.

Instance methods

gtk_print_operation_cancel

Cancels a running print operation.

gtk_print_operation_draw_page_finish

Signal that drawing of particular page is complete.

gtk_print_operation_get_default_page_setup

Returns the default page setup.

gtk_print_operation_get_embed_page_setup

Gets whether page setup selection combos are embedded.

gtk_print_operation_get_error

Call this when the result of a print operation is GTK_PRINT_OPERATION_RESULT_ERROR.

gtk_print_operation_get_has_selection

Gets whether there is a selection.

gtk_print_operation_get_n_pages_to_print

Returns the number of pages that will be printed.

gtk_print_operation_get_print_settings

Returns the current print settings.

gtk_print_operation_get_status

Returns the status of the print operation.

gtk_print_operation_get_status_string

Returns a string representation of the status of the print operation.

gtk_print_operation_get_support_selection

Gets whether the application supports print of selection.

gtk_print_operation_is_finished

A convenience function to find out if the print operation is finished.

gtk_print_operation_run

Runs the print operation.

gtk_print_operation_set_allow_async

Sets whether gtk_print_operation_run() may return before the print operation is completed.

gtk_print_operation_set_current_page

Sets the current page.

gtk_print_operation_set_custom_tab_label

Sets the label for the tab holding custom widgets.

gtk_print_operation_set_default_page_setup

Makes default_page_setup the default page setup for op.

gtk_print_operation_set_defer_drawing

Sets up the GtkPrintOperation to wait for calling of [method@Gtk.PrintOperation.draw_page_finish from application.

gtk_print_operation_set_embed_page_setup

Embed page size combo box and orientation combo box into page setup page.

gtk_print_operation_set_export_filename

Sets up the GtkPrintOperation to generate a file instead of showing the print dialog.

gtk_print_operation_set_has_selection

Sets whether there is a selection to print.

gtk_print_operation_set_job_name

Sets the name of the print job.

gtk_print_operation_set_n_pages

Sets the number of pages in the document.

gtk_print_operation_set_print_settings

Sets the print settings for op.

gtk_print_operation_set_show_progress

If show_progress is TRUE, the print operation will show a progress dialog during the print operation.

gtk_print_operation_set_support_selection

Sets whether selection is supported by GtkPrintOperation.

gtk_print_operation_set_track_print_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.

gtk_print_operation_set_unit

Sets up the transformation for the cairo context obtained from GtkPrintContext in such a way that distances are measured in units of unit.

gtk_print_operation_set_use_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.

Methods inherited from GObject (43)

Please see GObject for a full list of methods.

Methods inherited from GtkPrintOperationPreview (3)

gtk_print_operation_preview_end_preview

Ends a preview.

gtk_print_operation_preview_is_selected

Returns whether the given page is included in the set of pages that have been selected for printing.

gtk_print_operation_preview_render_page

Renders a page to the preview.

Properties

Gtk.PrintOperation:allow-async

Determines whether the print operation may run asynchronously or not.

Gtk.PrintOperation:current-page

The current page in the document.

Gtk.PrintOperation:custom-tab-label

Used as the label of the tab containing custom widgets.

Gtk.PrintOperation:default-page-setup

The GtkPageSetup used by default.

Gtk.PrintOperation:embed-page-setup

If TRUE, page size combo box and orientation combo box are embedded into page setup page.

Gtk.PrintOperation:export-filename

The name of a file to generate instead of showing the print dialog.

Gtk.PrintOperation:has-selection

Determines whether there is a selection in your application.

Gtk.PrintOperation:job-name

A string used to identify the job (e.g. in monitoring applications like eggcups).

Gtk.PrintOperation:n-pages

The number of pages in the document.

Gtk.PrintOperation:n-pages-to-print

The number of pages that will be printed.

Gtk.PrintOperation:print-settings

The GtkPrintSettings used for initializing the dialog.

Gtk.PrintOperation:show-progress

Determines whether to show a progress dialog during the print operation.

Gtk.PrintOperation:status

The status of the print operation.

Gtk.PrintOperation:status-string

A string representation of the status of the print operation.

Gtk.PrintOperation:support-selection

If TRUE, the print operation will support print of selection.

Gtk.PrintOperation:track-print-status

If TRUE, the print operation will try to continue report on the status of the print job in the printer queues and printer.

Gtk.PrintOperation:unit

The transformation for the cairo context obtained from GtkPrintContext is set up in such a way that distances are measured in units of unit.

Gtk.PrintOperation:use-full-page

If TRUE, the transformation for the cairo context obtained from GtkPrintContext puts the origin at the top left corner of the page.

Signals

Gtk.PrintOperation::begin-print

Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts.

Gtk.PrintOperation::create-custom-widget

Emitted when displaying the print dialog.

Gtk.PrintOperation::custom-widget-apply

Emitted right before ::begin-print if you added a custom widget in the ::create-custom-widget handler.

Gtk.PrintOperation::done

Emitted when the print operation run has finished doing everything required for printing.

Gtk.PrintOperation::draw-page

Emitted for every page that is printed.

Gtk.PrintOperation::end-print

Emitted after all pages have been rendered.

Gtk.PrintOperation::paginate

Emitted after the ::begin-print signal, but before the actual rendering starts.

Gtk.PrintOperation::preview

Gets emitted when a preview is requested from the native dialog.

Gtk.PrintOperation::request-page-setup

Emitted once for every page that is printed.

Gtk.PrintOperation::status-changed

Emitted at between the various phases of the print operation.

Gtk.PrintOperation::update-custom-widget

Emitted after change of selected printer.

Signals inherited from GObject (1)

GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

Signals inherited from GtkPrintOperationPreview (2)

GtkPrintOperationPreview::got-page-size

Emitted once for each page that gets rendered to the preview.

GtkPrintOperationPreview::ready

The ::ready signal gets emitted once per preview operation, before the first page is rendered.

Class structure

struct GtkPrintOperationClass {
  GObjectClass parent_class;
  void (* done) (
    GtkPrintOperation* operation,
    GtkPrintOperationResult result
  );
  void (* begin_print) (
    GtkPrintOperation* operation,
    GtkPrintContext* context
  );
  gboolean (* paginate) (
    GtkPrintOperation* operation,
    GtkPrintContext* context
  );
  void (* request_page_setup) (
    GtkPrintOperation* operation,
    GtkPrintContext* context,
    int page_nr,
    GtkPageSetup* setup
  );
  void (* draw_page) (
    GtkPrintOperation* operation,
    GtkPrintContext* context,
    int page_nr
  );
  void (* end_print) (
    GtkPrintOperation* operation,
    GtkPrintContext* context
  );
  void (* status_changed) (
    GtkPrintOperation* operation
  );
  GtkWidget* (* create_custom_widget) (
    GtkPrintOperation* operation
  );
  void (* custom_widget_apply) (
    GtkPrintOperation* operation,
    GtkWidget* widget
  );
  gboolean (* preview) (
    GtkPrintOperation* operation,
    GtkPrintOperationPreview* preview,
    GtkPrintContext* context,
    GtkWindow* parent
  );
  void (* update_custom_widget) (
    GtkPrintOperation* operation,
    GtkWidget* widget,
    GtkPageSetup* setup,
    GtkPrintSettings* settings
  );
  
}

No description available.

Class members

parent_class: GObjectClass: The parent class.
done: void (* done) ( GtkPrintOperation* operation, GtkPrintOperationResult result ): Signal emitted when the print operation run has finished doing everything required for printing.
begin_print: void (* begin_print) ( GtkPrintOperation* operation, GtkPrintContext* context ): Signal emitted after the user has finished changing print settings in the dialog, before the actual rendering starts.
paginate: gboolean (* paginate) ( GtkPrintOperation* operation, GtkPrintContext* context ): Signal emitted after the “begin-print” signal, but before the actual rendering starts.
request_page_setup: void (* request_page_setup) ( GtkPrintOperation* operation, GtkPrintContext* context, int page_nr, GtkPageSetup* setup ): Emitted once for every page that is printed, to give the application a chance to modify the page setup.
draw_page: void (* draw_page) ( GtkPrintOperation* operation, GtkPrintContext* context, int page_nr ): Signal emitted for every page that is printed.
end_print: void (* end_print) ( GtkPrintOperation* operation, GtkPrintContext* context ): Signal emitted after all pages have been rendered.
status_changed: void (* status_changed) ( GtkPrintOperation* operation ): Emitted at between the various phases of the print operation.
create_custom_widget: GtkWidget* (* create_custom_widget) ( GtkPrintOperation* operation ): Signal emitted when displaying the print dialog.
custom_widget_apply: void (* custom_widget_apply) ( GtkPrintOperation* operation, GtkWidget* widget ): Signal emitted right before “begin-print” if you added a custom widget in the “create-custom-widget” handler.
preview: gboolean (* preview) ( GtkPrintOperation* operation, GtkPrintOperationPreview* preview, GtkPrintContext* context, GtkWindow* parent ): Signal emitted when a preview is requested from the native dialog.
update_custom_widget: void (* update_custom_widget) ( GtkPrintOperation* operation, GtkWidget* widget, GtkPageSetup* setup, GtkPrintSettings* settings ): Emitted after change of selected printer.