Chapter 20. Printing

Table of Contents

At the application development level, gtkmm's printing API provides dialogs that are consistent across applications and allows use of Cairo's common drawing API, with Pango-driven text rendering. In the implementation of this common API, platform-specific backends and printer-specific drivers are used.

PrintOperation

The primary object is Gtk::PrintOperation, allocated for each print operation. To handle page drawing connect to its signals, or inherit from it and override the default virtual signal handlers. PrintOperation automatically handles all the settings affecting the print loop.

Signals

The PrintOperation::run() method starts the print loop, during which various signals are emitted:

  • begin_print: You must handle this signal, because this is where you create and set up a Pango::Layout using the provided Gtk::PrintContext, and break up your printing output into pages.

  • paginate: Pagination is potentially slow so if you need to monitor it you can call the PrintOperation::set_show_progress() method and handle this signal.

  • For each page that needs to be rendered, the following signals are emitted:

    • request_page_setup: Provides a PrintContext, page number and Gtk::PageSetup. Handle this signal if you need to modify page setup on a per-page basis.

    • draw_page: You must handle this signal, which provides a PrintContext and a page number. The PrintContext should be used to create a Cairo::Context into which the provided page should be drawn. To render text, iterate over the Pango::Layout you created in the begin_print handler.

  • end_print: A handler for it is a safe place to free any resources related to a PrintOperation. If you have your custom class that inherits from PrintOperation, it is naturally simpler to do it in the destructor.

  • done: This signal is emitted when printing is finished, meaning when the print data is spooled. Note that the provided Gtk::PrintOperationResult may indicate that an error occurred. In any case you probably want to notify the user about the final status.

  • status_changed: Emitted whenever a print job's status changes, until it is finished. Call the PrintOperation::set_track_print_status() method to monitor the job status after spooling. To see the status, use get_status() or get_status_string().

Reference