
@c %start of fragment

@node GtkPrintOperation
@chapter GtkPrintOperation
High-level Printing API

@section Overview
GtkPrintOperation is the high-level, portable printing API. It looks a bit
different than other GTK+ dialogs such as the @code{<gtk-file-chooser>}, 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
@code{<gtk-print-unix-dialog>}.

The typical way to use the high-level printing API is to create a
@code{<gtk-print-operation>} object with @code{gtk-print-operation-new} when the
user selects to print. Then you set some properties on it, e.g. the page size,
any @code{<gtk-print-settings>} from previous print operations, the number of
pages, the current page, etc.

Then you start the print operation by calling @code{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
@code{<gtk-print-operation>}, the main one being ::draw-page, which you are
supposed to catch and render the page on the provided @code{<gtk-print-context>}
using Cairo.

@example 

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

@end example

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 @code{gtk-print-operation-print-preview-render-page},
@code{gtk-print-operation-preview-end-preview} and
@code{gtk-print-operation-preview-is-selected} are useful when implementing a
print preview.

Printing support was added in GTK+ 2.10.

@section Usage
@include defuns-gtkprintoperation.xml.texi

@c %end of fragment
