Crea  Modifica  FrontPage  Indici  Cerca  Ultime modifiche  History  RSS  Login

Gtk::PrintOperation

class Gtk::PrintOperation

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

Class Methods

Gtk::PrintOperation.new
Creates a new Gtk::PrintOperation. Since 2.10
Gtk::PrintOperation.run_page_setup_dialog(parent = nil, page_setup = nil, settings = nil){|page_setup| ...}
Runs a page setup dialog, letting the user modify the values from page_setup. If the user cancels the dialog, the returned Gtk::PageSetup 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. Use this method with a block if this is a problem. Since 2.10

Instance Methods

cancel
Cancels a running print operation. This function may be called from a begin-print, paginate or draw-page signal handler to stop the currently running print operation. Since 2.10
error
Call this when the result of a print operation is Gtk::PrintOperation::RESULT_ERROR, either as returned by Gtk::PrintOperation#run, or in the ::done signal handler. The returned Gtk::PrintError will contain more details on what went wrong. Since 2.10
finished?

A convenience function to find out if the print operation is finished, either successfully (Gtk::PrintOperation::STATUS_FINISHED) or unsuccessfully (Gtk::PrintOperation::STATUS_FINISHED_ABORTED).

Note: when you enable print status tracking the print operation can be in a non-finished state even after done has been called, as the operation status then tracks the print job status on the printer. Since 2.10

  • Return value: true, if the print operation is finished.
run(action, parent = nil){|result| ... }

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

Normally that this method does not return until the rendering of all pages is complete. You can connect to the ::status-changed signal on the operation to obtain some information about the progress of the print operation. Furthermore, it may use a recursive mainloop to show the print dialog.

If you set the allow-async property the operation will run asyncronously if this is supported on the platform. The ::done signal will be emitted with the operation results when the operation is done (i.e. when the dialog is canceled, or when the print succeeds or fails).

If the result is failure, it raises an Gtk::PrintError. Since 2.10

allow_async?
Gets the value whether print process may run asynchronous. Since 2.10
  • Returns: true if print process may run asynchronous.
allow_async=(allow_async)
Sets the value whether print process may run asynchronous. Since 2.10
  • allow_async: true if print process may run asynchronous.
  • Returns: allow_async
set_allow_async(allow_async)
Same as allow_async=.
  • allow_async: true if print process may run asynchronous.
  • Returns: self
current_page
Gets the current page in the document. Since 2.10
  • Returns: The current page in the document
current_page=(current_page)
Sets the current page in the document. Since 2.10
  • current_page: The current page in the document
  • Returns: current_page
set_current_page(current_page)
Same as current_page=. Since 2.10
  • current_page: The current page in the document
  • Returns: self
custom_tab_label
Gets the Label for the tab containing custom widgets. Since 2.10
  • Returns: Label for the tab containing custom widgets.
custom_tab_label=(custom_tab_label)
Sets the Label for the tab containing custom widgets. Since 2.10
  • custom_tab_label: Label for the tab containing custom widgets.
  • Returns: custom_tab_label
set_custom_tab_label(custom_tab_label)
Same as custom_tab_label=. Since 2.10
  • custom_tab_label: Label for the tab containing custom widgets.
  • Returns: self
default_page_setup
Gets the Gtk::PageSetup used by default. Since 2.10
default_page_setup=(default_page_setup)
Sets the Gtk::PageSetup used by default. Since 2.10
  • default_page_setup: The Gtk::PageSetup used by default
  • Returns: default_page_setup
set_default_page_setup(default_page_setup)
Same as default_page_setup=. Since 2.10
  • default_page_setup: The Gtk::PageSetup used by default
  • Returns: self
export_filename
Gets the Export filename. Since 2.10
  • Returns: Export filename
export_filename=(export_filename)
Sets the Export filename. Since 2.10
  • export_filename: Export filename
  • Returns: export_filename
set_export_filename(export_filename)
Same as export_filename=. Since 2.10
  • export_filename: Export filename
  • Returns: self
job_name
Gets the String used for identifying the print job. Since 2.10
  • Returns: A String used for identifying the print job.
job_name=(job_name)
Sets the String used for identifying the print job. Since 2.10
  • job_name: A String used for identifying the print job.
  • Returns: job_name
set_job_name(job_name)
Same as job_name=. Since 2.10
  • job_name: A String used for identifying the print job.
  • Returns: self
n_pages
Gets the number of pages in the document. Since 2.10
  • Returns: The number of pages in the document.
n_pages=(n_pages)
Sets the number of pages in the document. Since 2.10
  • n_pages: The number of pages in the document.
  • Returns: n_pages
set_n_pages(n_pages)
Same as n_pages=. Since 2.10
  • n_pages: The number of pages in the document.
  • Returns: self
print_settings
Gets the Gtk::PrintSettings used for initializing the dialog. Since 2.10
print_settings=(print_settings)
Sets the Gtk::PrintSettings used for initializing the dialog. Since 2.10
  • print_settings: The Gtk::PrintSettings used for initializing the dialog
  • Returns: print_settings
set_print_settings(print_settings)
Same as print_settings=. Since 2.10
show_progress?
Gets the true if a progress dialog is shown while printing. Since 2.10
  • Returns: true if a progress dialog is shown while printing.
show_progress=(show_progress)
Sets the true if a progress dialog is shown while printing. Since 2.10
  • show_progress: true if a progress dialog is shown while printing.
  • Returns: show_progress
set_show_progress(show_progress)
Same as show_progress=. Since 2.10
  • show_progress: true if a progress dialog is shown while printing.
  • Returns: self
status
Gets the status of the print operation. Since 2.10
  • Returns: The status of the print operation
status_string
Gets the human-readable description of the status. Since 2.10
  • Returns: The human-readable description of the status
track_print_status?
Gets the value whether the print operation will continue to report on the print job status after the print data has been sent to the printer or print server. Since 2.10
  • Returns: true if the print operation will continue to report on the print job status after the print data has been sent to the printer or print server.
track_print_status=(track_print_status)
Sets the value whether the print operation will continue to report on the print job status after the print data has been sent to the printer or print server. Since 2.10
  • track_print_status: true if the print operation will continue to report on the print job status after the print data has been sent to the printer or print server. Since 2.10
  • Returns: track_print_status
set_track_print_status(track_print_status)
Same as track_print_status=. Since 2.10
  • track_print_status: true if the print operation will continue to report on the print job status after the print data has been sent to the printer or print server.
  • Returns: self
unit
Gets the unit in which distances can be measured in the context. Since 2.10
  • Returns: The unit in which distances can be measured in the context
unit=(unit)
Sets the unit in which distances can be measured in the context. Since 2.10
  • unit: The unit in which distances can be measured in the context
  • Returns: unit
set_unit(unit)
Same as unit=. Since 2.10
  • unit: The unit in which distances can be measured in the context
  • Returns: self
use_full_page?
Gets the value whether the the origin of the context should be at the corner of the page and not the corner of the imageable area. Since 2.10
  • Returns: true if the the origin of the context should be at the corner of the page and not the corner of the imageable area
use_full_page=(use_full_page)
Sets the value whether the the origin of the context should be at the corner of the page and not the corner of the imageable area. Since 2.10
  • use_full_page: true if the the origin of the context should be at the corner of the page and not the corner of the imageable area
  • Returns: use_full_page
set_use_full_page(use_full_page)
Same as use_full_page=. Since 2.10
  • use_full_page: true if the the origin of the context should be at the corner of the page and not the corner of the imageable area
  • Returns: self

Constants

Action

The action parameter to Gtk::PrintOperation#run determines what action the print operation should perform. Since 2.10

ACTION_PRINT_DIALOG
Show the print dialog.
ACTION_PRINT
Start to print without showing the print dialog, based on the current print settings.
ACTION_PREVIEW
Show the print preview.
ACTION_EXPORT
Export to a file. This requires the export-filename property to be set.

Result

A value of this type is returned by Gtk::PrintOperation#run. Since 2.10

RESULT_ERROR
An error has occured. This is used in the block only, otherwise raise GLib::Error?.
RESULT_APPLY
The print settings should be stored.
RESULT_CANCEL
The print operation has been canceled, the print settings should not be stored.
RESULT_IN_PROGRESS
The print operation is complete yet. This value will only be returned when running asynchronously.

Status

The status gives a rough indication of the completion of a running print operation. Since 2.10

STATUS_INITIAL
The printing has not started yet; this status is set initially, and while the print dialog is shown.
STATUS_PREPARING
This status is set while the begin-print signal is emitted and during pagination.
STATUS_GENERATING_DATA
This status is set while the pages are being rendered.
STATUS_SENDING_DATA
The print job is being sent off to the printer.
STATUS_PENDING
The print job has been sent to the printer, but is not printed for some reason, e.g. the printer may be stopped.
STATUS_PENDING_ISSUE
Some problem has occurred during printing, e.g. a paper jam.
STATUS_PRINTING
The printer is processing the print job.
STATUS_FINISHED
The printing has been completed successfully.
STATUS_FINISHED_ABORTED
The printing has been aborted.

Properties

allow-async: true or false (Read/Write)
true if print process may run asynchronous. Since 2.10
current-page: Integer (Read/Write)
The current page in the document Since 2.10
custom-tab-label: String (Read/Write)
Label for the tab containing custom widgets. Since 2.10
default-page-setup: Gtk::PageSetup (Read/Write)
The Gtk::PageSetup used by default Since 2.10
export-filename: String (Read/Write)
Export filename Since 2.10
job-name: String (Read/Write)
A string used for identifying the print job. Since 2.10
n-pages: Integer (Read/Write)
The number of pages in the document. Since 2.10
print-settings: Gtk::PrintSettings (Read/Write)
The Gtk::PrintSettings used for initializing the dialog Since 2.10
show-progress: true or false (Read/Write)
true if a progress dialog is shown while printing. Since 2.10
status: Gtk::PrintStatus (Read)
The status of the print operation Since 2.10
status-string: String (Read)
A human-readable description of the status Since 2.10
track-print-status: true or false (Read/Write)
true if the print operation will continue to report on the print job status after the print data has been sent to the printer or print server. Since 2.10
unit: Gtk::Unit (Read/Write)
The unit in which distances can be measured in the context Since 2.10
use-full-page: true or false (Read/Write)
true if the the origin of the context should be at the corner of the page and not the corner of the imageable area Since 2.10

Signals

begin-print: self, context

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 Gtk::PrintContext and paginate the document accordingly, and then set the number of pages with Gtk::PrintOperation#set_n_pages. Since 2.10

create-custom-widget: self

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 isn't controlled by the app. 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. Since 2.10

  • self: the Gtk::PrintOperation on which the signal was emitted
  • Returns: A custom widget that gets embedded in the print dialog, or nil
custom-widget-apply: self, widget
Emitted right before begin-print 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. Since 2.10
  • self: the Gtk::PrintOperation on which the signal was emitted
  • widget: the custom widget added in create-custom-widget
done: self, result

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 Gtk::PrintOperation::RESULT_ERROR then you can call gtk_print_operation_get_error() for more information.

If you enabled print status tracking then Gtk::PrintOperation#finished? may still return false after this was emitted. Since 2.10

  • self: the Gtk::PrintOperation on which the signal was emitted
  • result: the result of the print operation
draw-page: self, context, page_number

Emitted for every page that is printed. The signal handler must render the page_number's page onto the cairo context obtained from context using Gtk::PrintContext#cairo_context.

def draw_page(operation, context, page_number)
  cr = context.cairo_context
  width = context.width

  cr.rectangle(0, 0, width, HEADER_HEIGHT)

  cr.set_source_rgb(0.8, 0.8, 0.8)
  cr.fill

  layout = context.create_pango_layout

  desc = Pango::FontDescription.new("sans 14")
  layout.set_font_description(desc)

  layout.set_text("some text")
  layout.set_width(width)
  layout.set_alignment(Pango::ALIGN_CENTER)

  layout_width, layout_height = layout.size
  text_height = layout_height / Pango::SCALE

  cr.move_to(width / 2,  (HEADER_HEIGHT - text_height) / 2)
  cr.show_layout(layout)
end

Use Gtk::PrintOperation#set_use_full_page and Gtk::PrintOperation#set_unit before starting the print operation to set up the transformation of the cairo context according to your needs. Since 2.10

end-print: self, context
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. Since 2.10
paginate: self, context

Emitted after the begin-print signal, but before the actual rendering starts. It keeps getting emitted until it returns false.

This signal is intended to be used for paginating the document in small chunks, to avoid blocking the user interface for a long time. The signal handler should update the number of pages using Gtk::PrintOperation#set_n_pages, and return true if the document has been completely paginated.

If you don't 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. Since 2.10

preview: self, preview, cointext, parent

Gets emitted when a preview is requested from the native dialog. If you handle this you must set the cairo context on the printing context.

If you don't override this a default implementation using an external viewer will be used. Since 2.10

  • self: the Gtk::PrintOperation on which the signal was emitted
  • preview: the Gtk::PrintPreviewOperation? for the current operation
  • context: the Gtk::PrintContext that will be used
  • parent: the Gtk::Window to use as window parent, or nil
  • Returns: true if the listener wants to take over control of the preview
request-page-setup: self, context, page_number, setup
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. Since 2.10
status-changed: self
Emitted at between the various phases of the print operation. See Gtk::PrintStatus for the phases that are being discriminated. Use Gtk::PrintOperation#status to find out the current status. Since 2.10

ChangeLog

  • 2006-11-03: Modified. - Masao
  • 2006-07-09: updated for 2.10. - kou?

- kou?