class Gtk::PrintOperation

• Gtk::PrintOperation
• GObject::Object
• Reference
• Object

Overview

Gtk::PrintOperation is the high-level, portable printing API.

It looks a bit different than other GTK dialogs such as the Gtk::FileChooser, since some platforms don’t expose enough infrastructure to implement a good print dialog. On such platforms, Gtk::PrintOperation uses the native print dialog. On platforms which do not provide a native print dialog, GTK uses its own, see Gtk::PrintUnixDialog.

The typical way to use the high-level printing API is to create a Gtk::PrintOperation object with Gtk::PrintOperation.new when the user selects to print. Then you set some properties on it, e.g. the page size, any Gtk::PrintSettings from previous print operations, the number of pages, the current page, etc.

Then you start the print operation by calling Gtk::PrintOperation#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 Gtk::PrintOperation, the main one being [signal@Gtk.PrintOperation::draw-page], which you are supposed to handle and render the page on the provided Gtk::PrintContext using Cairo.

The high-level printing API

WARNING ⚠️ The following code is in c ⚠️

static Gtk::PrintSettings *settings = NULL;

static void
do_print (void)
{
  Gtk::PrintOperation *print;
  Gtk::PrintOperationResult 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 Gtk::PrintOperation 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::PrintOperationPreview#render_page, Gtk::PrintOperationPreview#end_preview and Gtk::PrintOperationPreview#is_selected? are useful when implementing a print preview.

Included Modules

• Gtk::PrintOperationPreview

Defined in:

Constructors

• .new : self

  Creates a new Gtk::PrintOperation.

• .new(*, allow_async : Bool | Nil = nil, current_page : Int32 | Nil = nil, custom_tab_label : String | Nil = nil, default_page_setup : Gtk::PageSetup | Nil = nil, embed_page_setup : Bool | Nil = nil, export_filename : String | Nil = nil, has_selection : Bool | Nil = nil, job_name : String | Nil = nil, n_pages : Int32 | Nil = nil, n_pages_to_print : Int32 | Nil = nil, print_settings : Gtk::PrintSettings | Nil = nil, show_progress : Bool | Nil = nil, status : Gtk::PrintStatus | Nil = nil, status_string : String | Nil = nil, support_selection : Bool | Nil = nil, track_print_status : Bool | Nil = nil, unit : Gtk::Unit | Nil = nil, use_full_page : Bool | Nil = nil)

Class Method Summary

• .g_type : UInt64

  Returns the type id (GType) registered in GLib type system.

Instance Method Summary

• #==(other : self)

  Returns true if this reference is the same as other.

• #allow_async=(allow_async : Bool) : Nil

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

• #allow_async? : Bool
• #begin_print_signal
• #cancel : Nil

  Cancels a running print operation.

• #create_custom_widget_signal
• #current_page : Int32
• #current_page=(current_page : Int32) : Nil

  Sets the current page.

• #custom_tab_label : String
• #custom_tab_label=(value : String) : String
• #custom_tab_label=(value : Nil) : Nil

  Set #custom_tab_label property to nil.

• #custom_tab_label=(label : String | Nil) : Nil

  Sets the label for the tab holding custom widgets.

• #custom_tab_label? : String | Nil

  Same as #custom_tab_label, but can return nil.

• #custom_widget_apply_signal
• #default_page_setup : Gtk::PageSetup

  Returns the default page setup.

• #default_page_setup=(default_page_setup : Gtk::PageSetup | Nil) : Nil

  Makes default_page_setup the default page setup for op.

• #done_signal
• #draw_page_finish : Nil

  Signal that drawing of particular page is complete.

• #draw_page_signal
• #embed_page_setup : Bool

  Gets whether page setup selection combos are embedded

• #embed_page_setup=(embed : Bool) : Nil

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

• #embed_page_setup? : Bool
• #end_print_signal
• #error : Nil

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

• #export_filename : String
• #export_filename=(filename : String) : Nil

  Sets up the Gtk::PrintOperation to generate a file instead of showing the print dialog.

• #export_filename=(value : Nil) : Nil

  Set #export_filename property to nil.

• #export_filename? : String | Nil

  Same as #export_filename, but can return nil.

• #has_selection : Bool

  Gets whether there is a selection.

• #has_selection=(has_selection : Bool) : Nil

  Sets whether there is a selection to print.

• #has_selection? : Bool
• #hash(hasher)

  See Object#hash(hasher)

• #is_finished : Bool

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

• #job_name : String
• #job_name=(job_name : String) : Nil

  Sets the name of the print job.

• #job_name=(value : Nil) : Nil

  Set #job_name property to nil.

• #job_name? : String | Nil

  Same as #job_name, but can return nil.

• #n_pages : Int32
• #n_pages=(n_pages : Int32) : Nil

  Sets the number of pages in the document.

• #n_pages_to_print : Int32

  Returns the number of pages that will be printed.

• #paginate_signal
• #preview_signal
• #print_settings : Gtk::PrintSettings | Nil

  Returns the current print settings.

• #print_settings=(print_settings : Gtk::PrintSettings | Nil) : Nil

  Sets the print settings for op.

• #request_page_setup_signal
• #run(action : Gtk::PrintOperationAction, parent : Gtk::Window | Nil) : Gtk::PrintOperationResult

  Runs the print operation.

• #set_defer_drawing : Nil

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

• #show_progress=(show_progress : Bool) : Nil

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

• #show_progress? : Bool
• #status : Gtk::PrintStatus

  Returns the status of the print operation.

• #status_changed_signal
• #status_string : String

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

• #status_string? : String | Nil

  Same as #status_string, but can return nil.

• #support_selection : Bool

  Gets whether the application supports print of selection

• #support_selection=(support_selection : Bool) : Nil

  Sets whether selection is supported by Gtk::PrintOperation.

• #support_selection? : Bool
• #track_print_status=(track_status : Bool) : Nil

  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.

• #track_print_status? : Bool
• #unit : Gtk::Unit
• #unit=(unit : Gtk::Unit) : Nil

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

• #update_custom_widget_signal
• #use_full_page=(full_page : Bool) : Nil

  If full_page is true, the transformation for the cairo context obtained from Gtk::PrintContext puts the origin at the top left corner of the page.

• #use_full_page? : Bool

Constructor Detail

Class Method Detail

Instance Method Detail

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_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));
 }