GtkPrintOperation

GtkPrintOperation — High-level Printing API

Synopsis


#include <gtk/gtk.h>


            GtkPrintOperation;
enum        GtkPrintStatus;
enum        GtkPrintOperationResult;
enum        GtkPrintError;
#define     GTK_PRINT_ERROR
GtkPrintOperation* gtk_print_operation_new  (void);
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_nr_of_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_show_dialog
                                            (GtkPrintOperation *op,
                                             gboolean show_dialog);
void        gtk_print_operation_set_pdf_target
                                            (GtkPrintOperation *op,
                                             const gchar *filename);
GtkPrintOperationResult gtk_print_operation_run
                                            (GtkPrintOperation *op,
                                             GtkWindow *parent,
                                             GError **error);
void        gtk_print_operation_run_async   (GtkPrintOperation *op,
                                             GtkWindow *parent);
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);


Object Hierarchy


  GObject
   +----GtkPrintOperation

Properties


  "current-page"         gint                  : Read / Write
  "default-page-setup"   GtkPageSetup          : Read / Write
  "job-name"             gchararray            : Read / Write
  "number-of-pages"      gint                  : Read / Write
  "pdf-target"           gchararray            : Read / Write
  "print-settings"       GtkPrintSettings      : Read / Write
  "show-dialog"          gboolean              : Read / Write
  "status"               GtkPrintStatus        : Read
  "status-string"        gchararray            : Read
  "unit"                 GtkUnit               : Read / Write
  "use-full-page"        gboolean              : Read / Write

Signals


"begin-print"
            void        user_function      (GtkPrintOperation *operation,
                                            GtkPrintContext   *context,
                                            gpointer           user_data)      : Run last
"draw-page" void        user_function      (GtkPrintOperation *operation,
                                            GtkPrintContext   *context,
                                            gint               page_nr,
                                            gpointer           user_data)      : Run last
"end-print" void        user_function      (GtkPrintOperation *operation,
                                            GtkPrintContext   *context,
                                            gpointer           user_data)      : Run last
"request-page-setup"
            void        user_function      (GtkPrintOperation *operation,
                                            GtkPrintContext   *context,
                                            gint               page_nr,
                                            GtkPageSetup      *setup,
                                            gpointer           user_data)      : Run last
"status-changed"
            void        user_function      (GtkPrintOperation *operation,
                                            gpointer           user_data)      : Run last

Description

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 ::draw-page, which you are supposed to catch and render the page on the provided GtkPrintContext using Cairo.

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

Printing support was added in GTK+ 2.10.

Details

GtkPrintOperation

typedef struct _GtkPrintOperation GtkPrintOperation;


enum GtkPrintStatus

typedef 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;


enum GtkPrintOperationResult

typedef enum {
  GTK_PRINT_OPERATION_RESULT_ERROR,
  GTK_PRINT_OPERATION_RESULT_APPLY,
  GTK_PRINT_OPERATION_RESULT_CANCEL
} GtkPrintOperationResult;


enum GtkPrintError

typedef enum
{
  GTK_PRINT_ERROR_GENERAL,
  GTK_PRINT_ERROR_INTERNAL_ERROR,
  GTK_PRINT_ERROR_NOMEM
} 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.

Returns : a new GtkPrintOperation

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 default_page_setup the default page setup for op.

This page setup will be used by gtk_print_operation_run(), but it can be overridden on a per-page basis by connecting to the ::request-page-setup signal.

op : a GtkPrintOperation
default_page_setup : a GtkPageSetup, or NULL

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 gtk_print_operation_set_default_page_setup().

op : a GtkPrintOperation
Returns : the default page setup

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 op. This is typically used to re-establish print settings from a previous print operation, see gtk_print_operation_run().

op : a GtkPrintOperation
print_settings : GtkPrintSettings, or NULL

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 NULL until either gtk_print_operation_set_print_settings() or gtk_print_operation_run() have been called.

op : a GtkPrintOperation
Returns : the current print settings of op.

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.

op : a GtkPrintOperation
job_name : a string that identifies the print job

Since 2.10


gtk_print_operation_set_nr_of_pages ()

void        gtk_print_operation_set_nr_of_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 n_pages - 1.

op : a GtkPrintOperation
n_pages : the number of pages

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 gtk_print_operation_run(), the user will be able to select to print only the current page.

Note that this only makes sense for pre-paginated documents.

op : a GtkPrintOperation
current_page : the current page, 0-based

Since 2.10


gtk_print_operation_set_use_full_page ()

void        gtk_print_operation_set_use_full_page
                                            (GtkPrintOperation *op,
                                             gboolean 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 (which 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).

op : a GtkPrintOperation
full_page : TRUE to set up the GtkPrintContext for the full page

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

op : a GtkPrintOperation
unit : the unit to use

Since 2.10


gtk_print_operation_set_show_dialog ()

void        gtk_print_operation_set_show_dialog
                                            (GtkPrintOperation *op,
                                             gboolean show_dialog);

Sets whether calling gtk_print_operation_run() will present a print dialog to the user, or just print to the default printer.

op : a GtkPrintOperation
show_dialog : TRUE to show the print dialog

Since 2.10


gtk_print_operation_set_pdf_target ()

void        gtk_print_operation_set_pdf_target
                                            (GtkPrintOperation *op,
                                             const gchar *filename);

Sets up the GtkPrintOperation to generate a PDF file instead of showing the print dialog. The indended use of this function 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.

op : a GtkPrintOperation
filename : the filename for the PDF file

Since 2.10


gtk_print_operation_run ()

GtkPrintOperationResult gtk_print_operation_run
                                            (GtkPrintOperation *op,
                                             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.

Note that this function does not return until the rendering of all pages is complete. You can connect to the ::status-changed signal on op to obtain some information about the progress of the print operation. Furthermore, it may use a recursive mainloop to show the print dialog. See gtk_print_operation_run_async() if this is a problem.

 FIXME: need an example here

op : a GtkPrintOperation
parent : Transient parent of the dialog, or NULL
error : Return location for errors, or NULL
Returns : the result of the print operation. A return value of GTK_PRINT_OPERATION_RESULT_APPLY indicates that the printing was completed successfully. In this case, it is a good idea to obtain the used print settings with gtk_print_operation_get_print_settings() and store them for reuse with the next print operation.

Since 2.10


gtk_print_operation_run_async ()

void        gtk_print_operation_run_async   (GtkPrintOperation *op,
                                             GtkWindow *parent);

Runs the print operation, by first letting the user modify print settings in the print dialog, and then print the document.

In contrast to gtk_print_operation_run(), this function returns after showing the print dialog on platforms that support this, and handles the printing by connecting a signal handler to the ::response signal of the dialog.

If you use this function, it is recommended that you store the modified GtkPrintSettings in a ::begin-print or ::end-print signal handler.

op : a GtkPrintOperation
parent : Transient parent of the dialog, or NULL

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 gtk_print_operation_get_status_string().

op : a GtkPrintOperation
Returns : the status of the print operation

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 gtk_print_operation_get_status() to obtain a status value that is suitable for programmatic use.

op : a GtkPrintOperation
Returns : a string representation of the status of the print operation

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 (GTK_PRINT_STATUS_FINISHED) or unsuccessfully (GTK_PRINT_STATUS_FINISHED_ABORTED).

op : a GtkPrintOperation
Returns : TRUE, if the print operation is finished.

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 page_setup. If the user cancels the dialog, the returned GtkPageSetup is identical to the passed in page_setup, otherwise it contains the modifications done in the dialog.

Note that this function may use a recursive mainloop to show the page setup dialog. See gtk_print_run_page_setup_dialog_async() if this is a problem.

parent : transient parent, or NULL
page_setup : an existing GtkPageSetup, or NULL
settings : a GtkPrintSettings
Returns : a new GtkPageSetup

Since 2.10


GtkPageSetupDoneFunc ()

void        (*GtkPageSetupDoneFunc)         (GtkPageSetup *page_setup,
                                             gpointer data);

page_setup :
data :

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

In contrast to gtk_print_run_page_setup_dialog(), this function returns after showing the page setup dialog on platforms that support this, and calls done_cb from a signal handler for the ::response signal of the dialog.

parent : transient parent, or NULL
page_setup : an existing GtkPageSetup, or NULL
settings : a GtkPrintSettings
done_cb : a function to call when the user saves the modified page setup
data : user data to pass to done_cb

Since 2.10

Property Details

The "current-page" property

  "current-page"         gint                  : Read / Write

The current page in the document.

If this is set before gtk_print_operation_run(), the user will be able to select to print only the current page.

Note that this only makes sense for pre-paginated documents.

Allowed values: >= -1

Default value: -1

Since 2.10


The "default-page-setup" property

  "default-page-setup"   GtkPageSetup          : Read / Write

The GtkPageSetup used by default.

This page setup will be used by gtk_print_operation_run(), but it can be overridden on a per-page basis by connecting to the ::request-page-setup signal.

Since 2.10


The "job-name" property

  "job-name"             gchararray            : Read / Write

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.

Default value: ""

Since 2.10


The "number-of-pages" property

  "number-of-pages"      gint                  : Read / Write

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 n_pages - 1.

Allowed values: >= -1

Default value: -1

Since 2.10


The "pdf-target" property

  "pdf-target"           gchararray            : Read / Write

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

The indended 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.

Default value: NULL

Since 2.10


The "print-settings" property

  "print-settings"       GtkPrintSettings      : Read / Write

The GtkPrintSettings used for initializing the dialog.

Setting this property is typically used to re-establish print settings from a previous print operation, see gtk_print_operation_run().

Since 2.10


The "show-dialog" property

  "show-dialog"          gboolean              : Read / Write

Determines whether calling gtk_print_operation_run() will present a print dialog to the user, or just print to the default printer.

Default value: TRUE

Since 2.10


The "status" property

  "status"               GtkPrintStatus        : Read

The status of the print operation.

Default value: GTK_PRINT_STATUS_INITIAL

Since 2.10


The "status-string" property

  "status-string"        gchararray            : Read

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.

Default value: ""

Since 2.10


The "unit" property

  "unit"                 GtkUnit               : Read / Write

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

Default value: GTK_UNIT_PIXEL

Since 2.10


The "use-full-page" property

  "use-full-page"        gboolean              : Read / Write

If TRUE, the transformation for the cairo context obtained from GtkPrintContext puts the origin at the top left corner of the page (which 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).

Default value: FALSE

Since 2.10

Signal Details

The "begin-print" signal

void        user_function                  (GtkPrintOperation *operation,
                                            GtkPrintContext   *context,
                                            gpointer           user_data)      : Run last

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

A typical use for this signal is to use the parameters from the GtkPrintContext and paginate the document accordingly, and then set the number of pages with gtk_print_operation_set_nr_of_pages().

operation : the GtkPrintOperation on which the signal was emitted
context : the GtkPrintContext for the current operation
user_data : user data set when the signal handler was connected.

Since 2.10


The "draw-page" signal

void        user_function                  (GtkPrintOperation *operation,
                                            GtkPrintContext   *context,
                                            gint               page_nr,
                                            gpointer           user_data)      : Run last

Gets 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().

 FIXME: need an example here

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.

operation : the GtkPrintOperation on which the signal was emitted
context : the GtkPrintContext for the current operation
page_nr : the number of the currently printed page
user_data : user data set when the signal handler was connected.

Since 2.10


The "end-print" signal

void        user_function                  (GtkPrintOperation *operation,
                                            GtkPrintContext   *context,
                                            gpointer           user_data)      : Run last

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

operation : the GtkPrintOperation on which the signal was emitted
context : the GtkPrintContext for the current operation
user_data : user data set when the signal handler was connected.

Since 2.10


The "request-page-setup" signal

void        user_function                  (GtkPrintOperation *operation,
                                            GtkPrintContext   *context,
                                            gint               page_nr,
                                            GtkPageSetup      *setup,
                                            gpointer           user_data)      : Run last

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

operation : the GtkPrintOperation on which the signal was emitted
context : the GtkPrintContext for the current operation
page_nr : the number of the currently printed page
setup : the GtkPageSetup
user_data : user data set when the signal handler was connected.

Since 2.10


The "status-changed" signal

void        user_function                  (GtkPrintOperation *operation,
                                            gpointer           user_data)      : Run last

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

operation : the GtkPrintOperation on which the signal was emitted
user_data : user data set when the signal handler was connected.

Since 2.10

See Also

GtkPrintContext, GtkPrintUnixDialog