Class gtk-print-operation

Package: gtk

Superclasses

gtk-print-operation-preview, g-object, common-lisp:standard-object, common-lisp:t

Documented Subclasses

None

Direct Slots

allow-async

The allow-async property of type :boolean (Read / Write)
Determines whether the print operation may run asynchronously or not. Some systems do not support asynchronous printing, but those that do will return :in-progress as the status, and emit the "done" signal when the operation is actually done. The Windows port does not support asynchronous operation at all, this is unlikely to change. On other platforms, all actions except for :export support asynchronous operation.
Default value: false

current-page

The current-page property of type :int (Read / Write)
The current page in the document. If this is set before the function 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

custom-tab-label

The custom-tab-label property of type :string (Read / Write)
Used as the label of the tab containing custom widgets. Note that this property may be ignored on some platforms. If this is nil, GTK+ uses a default label.
Default value: nil

default-page-setup

The default-page-setup property of type gtk-page-setup (Read / Write)
The page setup used by default. This page setup will be used by the function gtk-print-operation-run, but it can be overridden on a per-page basis by connecting to the "request-page-setup" signal.

embed-page-setup

The embed-page-setup property of type :boolean (Read / Write)
If true, the page size combo box and the orientation combo box are embedded into the page setup page.
Default value: false

export-filename

The export-filename property of type :string (Read / Write)
The name of a file to generate instead of showing the print dialog. Currently, PDF is the only supported format. The intended 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: nil

has-selection

The has-selection property of type :boolean (Read / Write)
Determines whether there is a selection in your application. This can allow your application to print the selection. This is typically used to make a "Selection" button sensitive.
Default value: false

job-name

The job-name property of type :string (Read / Write)
A string used to identify the job, e.g. in monitoring applications like eggcups. If you do not set a job name, GTK+ picks a default one by numbering successive print jobs.
Default value: ""

n-pages

The n-pages property of type :int (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

n-pages-to-print

The n-pages-to-print property of type :int (Read)
The number of pages that will be printed. Note that this value is set during print preparation phase :preparing, so this value should never be get before the data generation phase :generating-data. You can connect to the "status-changed" signal and call the function gtk-print-operation-n-pages-to-print when print status is :generating-data. This is typically used to track the progress of print operation.
Allowed values: >= -1
Default value: -1

print-settings

The print-settings property of type gtk-print-settings (Read / Write)
The print settings used for initializing the dialog. Setting this property is typically used to re-establish print settings from a previous print operation, see the function gtk-print-operation-run.

show-progress

The show-progress property of type :boolean (Read / Write)
Determines whether to show a progress dialog during the print operation.
Default value: false

status

The status property of type gtk-print-status (Read)
The status of the print operation.
Default value: :initial

status-string

The status-string property of type :string (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 gtk-statusbar widget. See the status property for a status value that is suitable for programmatic use.
Default value: ""

support-selection

The support-selection property of type :boolean (Read / Write)
If true, the print operation will support print of selection. This allows the print dialog to show a "Selection" button.
Default value: false

track-print-status

The track-print-status property of type :boolean (Read / Write)
If true, the print operation will try to continue report on the status of the print job in the printer queues and printer. This can allow your application to show things like "out of paper" issues, and when the print job actually reaches the printer. However, this is often implemented using polling, and should not be enabled unless needed.
Default value: false

unit

The unit property of type gtk-unit (Read / Write)
The transformation for the Cairo context obtained from gtk-print-context is set up in such a way that distances are measured in units of a value of the gtk-unit enumeration.
Default value: :pixel

use-full-page

The use-full-page property of type :boolean (Read / Write)
If true, the transformation for the Cairo context obtained from gtk-print-context 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

Details

gtk-print-operation is the high-level, portable printing API. It looks a bit different than other GTK+ dialogs such as the gtk-file-chooser, since some platforms do not expose enough infrastructure to implement a good print dialog. On such platforms, gtk-print-operation uses the native print dialog. On platforms which do not provide a native print dialog, GTK+ uses its own, see gtk-print-unix-dialog.

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

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

By default gtk-print-operation 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.

Example

The high-level printing API.

(defvar *print-settings* nil)


(defun do-print-operation (window)
  (let ((response nil)
        (print (gtk-print-operation-new)))
    ;; Connect signal handlers for the print operation
    (g-signal-connect print "draw-page" #'draw-page)
    (g-signal-connect print "begin-print" #'begin-print)
    ;; Restore the print settings
    (when *print-settings*
      (setf (gtk-print-operation-print-settings print) *print-settings*))
    ;; Perform the print operation
    (setf response (gtk-print-operation-run print :print-dialog window))
    ;; Check the response and save the print settings
    (when (eq :apply response)
      (setf *print-settings* (gtk-print-operation-print-settings print)))))

Signal Details

The "begin-print" signal

 lambda (operation context)    : Run Last

Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts. A typical use for the "begin-print" signal is to use the parameters from the gtk-print-context and paginate the document accordingly, and then set the number of pages with the function gtk-print-operation-n-pages.

operation: The gtk-print-operation object on which the signal was emitted.
context: The gtk-print-context object for the current operation.

The "create-custom-widget" signal

 lambda (operation)    : Run Last

Emitted when displaying the print dialog. If you return a widget in a handler for this signal it will be added to a custom tab in the print dialog. You typically return a container widget with multiple widgets in it. The print dialog owns the returned widget, and its lifetime is not controlled by the application. However, the widget is guaranteed to stay around until the "custom-widget-apply" signal is emitted on the operation. Then you can read out any information you need from the widgets.

operation: The gtk-print-operation object on which the signal was emitted.
Returns: A custom widget that gets embedded in the print dialog, or nil.

The "custom-widget-apply" signal

 lambda (operation widget)    : Run Last

Emitted right before the "begin-print" signal if you added a custom widget in the "create-custom-widget" handler. When you get this signal you should read the information from the custom widgets, as the widgets are not guaraneed to be around at a later time.

operation: The gtk-print-operation object on which the signal was emitted.
widget: The custom widget added in a "create-custom-widget" handler.

The "done" signal

 lambda (operation result)    : Run Last

Emitted when the print operation run has finished doing everything required for printing. result gives you information about what happened during the run. If result is :error then you can call the function gtk_print_operation_get_error () for more information. If you enabled print status tracking then the function gtk-print-operation-is-finished may still return false after the "done" signal was emitted.

operation: The gtk-print-operation object on which the signal was emitted.
result: The result of type gtk-print-operation-result of the print operation.

The "draw-page" signal

 lambda (operation context page-nr)    : Run Last

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 the function gtk-print-context-cairo-context. Use the functions gtk-print-operation-use-full-page and gtk-print-operation-unit before starting the print operation to set up the transformation of the Cairo context according to your needs.

(defun draw-page (operation context page-nr)
  (declare (ignore operation page-nr))
  (let ((text-height 0)
        (cr (gtk-print-context-cairo-context context))
        (width (floor (gtk-print-context-get-width context)))
        (layout (gtk-print-context-create-pango-layout context)))
    ;; Print a grey colored header
    (cairo-rectangle cr 0 0 width *header-height*)
    (cairo-set-source-rgb cr 0.9 0.9 0.9)
    (cairo-fill cr)
    ;; Set the font and text to print
    (setf (pango-layout-font-description layout)
          (pango-font-description-from-string "sans 14"))
    (setf (pango-layout-text layout) "Title")
    (setf (pango-layout-width layout) (* width +pango-scale+))
    (setf (pango-layout-alignment layout) :center)
    ;; Get the height of the text
    (multiple-value-bind (width height)
        (pango-layout-size layout)
      (setf text-height (/ height +pango-scale+)))
    ;; Set color to black and center the text in header
    (cairo-set-source-rgb cr 0.0 0.0 0.0)
    (cairo-move-to cr 0 (floor (/ (- *header-height* text-height) 2)))
    (pango-cairo-show-layout cr layout)))

operation: The gtk-print-operation object on which the signal was emitted.
context: The gtk-print-context object for the current operation.
page-nr: The 0-based number of the currently printed page.

The "end-print" signal

 lambda (operation context)    : Run Last

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 gtk-print-operation object on which the signal was emitted.
context: The gtk-print-context object for the current operation.

The "paginate" signal

 lambda (operation context)    : Run Last

Emitted after the "begin-print" signal, but before the actual rendering starts. It keeps getting emitted until a connected signal handler returns true. The "paginate" signal is intended to be used for paginating a document in small chunks, to avoid blocking the user interface for a long time. The signal handler should update the number of pages using the function gtk-print-operation-n-pages, and return true if the document has been completely paginated. If you do not need to do pagination in chunks, you can simply do it all in the "begin-print" handler, and set the number of pages from there.

operation: The gtk-print-operation object on which the signal was emitted.
context: The gtk-print-context object for the current operation.
Returns: True if pagination is complete.

The "preview" signal

 lambda (operation preview context parent)    : Run Last

Gets emitted when a preview is requested from the native dialog. The default handler for this signal uses an external viewer application to preview. To implement a custom print preview, an application must return true from its handler for this signal. In order to use the provided context for the preview implementation, it must be given a suitable cairo context with the function gtk-print-context-set-cairo-context. The custom preview implementation can use the functions gtk-print-operation-preview-is-selected and gtk-print-operation-preview-render-page to find pages which are selected for print and render them. The preview must be finished by calling the function gtk-print-operation-preview-end-preview, typically in response to the user clicking a Close button.

operation: The gtk-print-operation object on which the signal was emitted.
preview: The gtk-print-preview-operation object for the current operation.
context: The gtk-print-context object that will be used.
parent: The gtk-window widget to use as window parent, or nil.
Returns: True if the listener wants to take over control of the preview.

The "request-page-setup" signal

 lambda (operation context page-nr setup)    : Run Last

Emitted once for every page that is printed, to give the application a chance to modify the page setup. Any changes done to the page setup will be in force only for printing this page.

operation: The gtk-print-operation object on which the signal was emitted.
context: The gtk-print-context object for the current operation.
page-nr: The 0-based number of the currently printed page.
setup: The gtk-page-setup object.

The "status-changed" signal

 lambda (operation)    : Run Last

Emitted at between the various phases of the print operation. See the gtk-print-status enumeration for the phases that are being discriminated. Use the function gtk-print-operation-status to find out the current status.

operation: The gtk-print-operation object on which the signal was emitted.

The "update-custom-widget" signal

 lambda (operation widget setup settings)    : Run Last

Emitted after change of the selected printer. The actual page setup and print settings are passed to the custom widget, which can actualize itself according to this change.

operation: The gtk-print-operation object on which the signal was emitted.
widget: The custom widget added in the "create-custom-widget" handler.
setup: Actual gtk-page-setup object.
settings: Actual gtk-print-settings object.

The "got-page-size" signal

 lambda (preview context page-setup)    : Run Last

The "got-page-size" signal is emitted once for each page that gets rendered to the preview. A handler for this signal should update the context according to the page-setup argument and set up a suitable Cairo context, using the function gtk-print-context-set-cairo-context.

preview: The gtk-print-operation-preview object on which the signal is emitted.
context: The current gtk-print-context object.
page-setup: The gtk-page-setup object for the current page.

The "ready" signal

 lambda (preview context)    : Run Last

The "ready" signal gets emitted once per preview operation, before the first page is rendered. A handler for this signal can be used for setup tasks.

preview: The gtk-print-operation-preview object on which the signal is emitted.
context: The current gtk-print-context object.