Package org.gnome.gtk

Class PrintOperation.Builder<B extends PrintOperation.Builder<B>>

java.lang.Object

io.github.jwharm.javagi.gobject.Builder<B>

org.gnome.gobject.GObject.Builder<B>

org.gnome.gtk.PrintOperation.Builder<B>

Type Parameters:

B - the type of the Builder that is returned

All Implemented Interfaces:

BuilderInterface

Enclosing class:

PrintOperation

public static class PrintOperation.Builder<B extends PrintOperation.Builder<B>>
extends GObject.Builder<B>

Inner class implementing a builder pattern to construct a GObject with properties.

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	Builder()	Default constructor for a Builder object.

Method Summary

Modifier and Type	Method	Description
PrintOperation	build()	Finish building the PrintOperation object.
B	onBeginPrint(PrintOperation.BeginPrintCallback handler)	Emitted after the user has finished changing print settings in the dialog, before the actual rendering starts.
B	onCreateCustomWidget(PrintOperation.CreateCustomWidgetCallback handler)	Emitted when displaying the print dialog.
B	onCustomWidgetApply(PrintOperation.CustomWidgetApplyCallback handler)	Emitted right before ::begin-print if you added a custom widget in the ::create-custom-widget handler.
B	onDone(PrintOperation.DoneCallback handler)	Emitted when the print operation run has finished doing everything required for printing.
B	onDrawPage(PrintOperation.DrawPageCallback handler)	Emitted for every page that is printed.
B	onEndPrint(PrintOperation.EndPrintCallback handler)	Emitted after all pages have been rendered.
B	onPaginate(PrintOperation.PaginateCallback handler)	Emitted after the ::begin-print signal, but before the actual rendering starts.
B	onPreview(PrintOperation.PreviewCallback handler)	Gets emitted when a preview is requested from the native dialog.
B	onRequestPageSetup(PrintOperation.RequestPageSetupCallback handler)	Emitted once for every page that is printed.
B	onStatusChanged(PrintOperation.StatusChangedCallback handler)	Emitted at between the various phases of the print operation.
B	onUpdateCustomWidget(PrintOperation.UpdateCustomWidgetCallback handler)	Emitted after change of selected printer.
B	setAllowAsync(boolean allowAsync)	Determines whether the print operation may run asynchronously or not.
B	setCurrentPage(int currentPage)	The current page in the document.
B	setCustomTabLabel(String customTabLabel)	Used as the label of the tab containing custom widgets.
B	setDefaultPageSetup(PageSetup defaultPageSetup)	The GtkPageSetup used by default.
B	setEmbedPageSetup(boolean embedPageSetup)	If true, page size combo box and orientation combo box are embedded into page setup page.
B	setExportFilename(String exportFilename)	The name of a file to generate instead of showing the print dialog.
B	setHasSelection(boolean hasSelection)	Determines whether there is a selection in your application.
B	setJobName(String jobName)	A string used to identify the job (e.g.
B	setNPages(int nPages)	The number of pages in the document.
B	setPrintSettings(PrintSettings printSettings)	The GtkPrintSettings used for initializing the dialog.
B	setShowProgress(boolean showProgress)	Determines whether to show a progress dialog during the print operation.
B	setSupportSelection(boolean supportSelection)	If true, the print operation will support print of selection.
B	setTrackPrintStatus(boolean trackPrintStatus)	If true, the print operation will try to continue report on the status of the print job in the printer queues and printer.
B	setUnit(Unit unit)	The transformation for the cairo context obtained from GtkPrintContext is set up in such a way that distances are measured in units of unit.
B	setUseFullPage(boolean useFullPage)	If true, the transformation for the cairo context obtained from GtkPrintContext puts the origin at the top left corner of the page.

Methods inherited from class org.gnome.gobject.GObject.Builder

onNotify

Methods inherited from class io.github.jwharm.javagi.gobject.Builder

addBuilderProperty, connect, connect, connectSignals, getArena, getNames, getValues

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Builder

protected Builder()

Default constructor for a Builder object.

Method Details

build

public PrintOperation build()

Finish building the PrintOperation object. This will call GObject.withProperties(org.gnome.glib.Type, java.lang.String[], org.gnome.gobject.Value[]) to create a new GObject instance, which is then cast to PrintOperation.

Overrides:

build in class GObject.Builder<B extends PrintOperation.Builder<B>>

Returns:

a new instance of PrintOperation with the properties that were set in the Builder object.

setAllowAsync

public B setAllowAsync(boolean allowAsync)

Determines whether the print operation may run asynchronously or not.

Some systems don't support asynchronous printing, but those that do will return PrintOperationResult.IN_PROGRESS as the status, and emit the Gtk.PrintOperation::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 PrintOperationAction.EXPORT support asynchronous operation.

Parameters:

allowAsync - the value for the allow-async property

Returns:

the Builder instance is returned, to allow method chaining

setCurrentPage

public B setCurrentPage(int currentPage)

The current page in the document.

If this is set before PrintOperation.run(org.gnome.gtk.PrintOperationAction, org.gnome.gtk.Window), the user will be able to select to print only the current page.

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

Parameters:

currentPage - the value for the current-page property

Returns:

the Builder instance is returned, to allow method chaining

setCustomTabLabel

public B setCustomTabLabel(String customTabLabel)

Used as the label of the tab containing custom widgets.

Note that this property may be ignored on some platforms.

If this is null, GTK uses a default label.

Parameters:

customTabLabel - the value for the custom-tab-label property

Returns:

the Builder instance is returned, to allow method chaining

setDefaultPageSetup

public B setDefaultPageSetup(PageSetup defaultPageSetup)

The GtkPageSetup used by default.

This page setup will be used by PrintOperation.run(org.gnome.gtk.PrintOperationAction, org.gnome.gtk.Window), but it can be overridden on a per-page basis by connecting to the Gtk.PrintOperation::request-page-setup signal.

Parameters:

defaultPageSetup - the value for the default-page-setup property

Returns:

the Builder instance is returned, to allow method chaining

setEmbedPageSetup

public B setEmbedPageSetup(boolean embedPageSetup)

If true, page size combo box and orientation combo box are embedded into page setup page.

Parameters:

embedPageSetup - the value for the embed-page-setup property

Returns:

the Builder instance is returned, to allow method chaining

setExportFilename

public B setExportFilename(String exportFilename)

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.

Parameters:

exportFilename - the value for the export-filename property

Returns:

the Builder instance is returned, to allow method chaining

setHasSelection

public B setHasSelection(boolean hasSelection)

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.

Parameters:

hasSelection - the value for the has-selection property

Returns:

the Builder instance is returned, to allow method chaining

setJobName

public B setJobName(String jobName)

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.

Parameters:

jobName - the value for the job-name property

Returns:

the Builder instance is returned, to allow method chaining

setNPages

public B setNPages(int nPages)

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 Gtk.PrintOperation::begin-print signal handler.

Note that the page numbers passed to the Gtk.PrintOperation::request-page-setup and Gtk.PrintOperation::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 nPages - 1.

Parameters:

nPages - the value for the n-pages property

Returns:

the Builder instance is returned, to allow method chaining

setPrintSettings

public B setPrintSettings(PrintSettings printSettings)

The GtkPrintSettings used for initializing the dialog.

Setting this property is typically used to re-establish print settings from a previous print operation, see PrintOperation.run(org.gnome.gtk.PrintOperationAction, org.gnome.gtk.Window).

Parameters:

printSettings - the value for the print-settings property

Returns:

the Builder instance is returned, to allow method chaining

setShowProgress

public B setShowProgress(boolean showProgress)

Determines whether to show a progress dialog during the print operation.

Parameters:

showProgress - the value for the show-progress property

Returns:

the Builder instance is returned, to allow method chaining

setSupportSelection

public B setSupportSelection(boolean supportSelection)

If true, the print operation will support print of selection.

This allows the print dialog to show a "Selection" button.

Parameters:

supportSelection - the value for the support-selection property

Returns:

the Builder instance is returned, to allow method chaining

setTrackPrintStatus

public B setTrackPrintStatus(boolean trackPrintStatus)

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.

Parameters:

trackPrintStatus - the value for the track-print-status property

Returns:

the Builder instance is returned, to allow method chaining

setUnit

public B setUnit(Unit unit)

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

Parameters:

unit - the value for the unit property

Returns:

the Builder instance is returned, to allow method chaining

setUseFullPage

public B setUseFullPage(boolean useFullPage)

If true, the transformation for the cairo context obtained from GtkPrintContext puts the origin at the top left corner of the page.

This 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).

Parameters:

useFullPage - the value for the use-full-page property

Returns:

the Builder instance is returned, to allow method chaining

onBeginPrint

public B onBeginPrint(PrintOperation.BeginPrintCallback handler)

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

A typical use for ::begin-print is to use the parameters from the PrintContext and paginate the document accordingly, and then set the number of pages with PrintOperation.setNPages(int).

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.BeginPrintCallback.run(org.gnome.gtk.PrintContext)

onCreateCustomWidget

public B onCreateCustomWidget(PrintOperation.CreateCustomWidgetCallback handler)

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 Gtk.PrintOperation::custom-widget-apply signal is emitted on the operation. Then you can read out any information you need from the widgets.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.CreateCustomWidgetCallback.run()

onCustomWidgetApply

public B onCustomWidgetApply(PrintOperation.CustomWidgetApplyCallback handler)

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 guaranteed to be around at a later time.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.CustomWidgetApplyCallback.run(org.gnome.gtk.Widget)

onDone

public B onDone(PrintOperation.DoneCallback handler)

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 PrintOperationResult.ERROR then you can call PrintOperation.getError() for more information.

If you enabled print status tracking then PrintOperation.isFinished() may still return false after the ::done signal was emitted.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.DoneCallback.run(org.gnome.gtk.PrintOperationResult)

onDrawPage

public B onDrawPage(PrintOperation.DrawPageCallback handler)

Emitted for every page that is printed.

The signal handler must render the pageNr's page onto the cairo context obtained from context using PrintContext.getCairoContext().

static void
 draw_page (GtkPrintOperation *operation,
            GtkPrintContext   *context,
            int                page_nr,
            gpointer           user_data)
 {
   cairo_t *cr;
   PangoLayout *layout;
   double width, text_height;
   int layout_height;
   PangoFontDescription *desc;
   
   cr = gtk_print_context_get_cairo_context (context);
   width = gtk_print_context_get_width (context);
   
   cairo_rectangle (cr, 0, 0, width, HEADER_HEIGHT);
   
   cairo_set_source_rgb (cr, 0.8, 0.8, 0.8);
   cairo_fill (cr);
   
   layout = gtk_print_context_create_pango_layout (context);
   
   desc = pango_font_description_from_string ("sans 14");
   pango_layout_set_font_description (layout, desc);
   pango_font_description_free (desc);
   
   pango_layout_set_text (layout, "some text", -1);
   pango_layout_set_width (layout, width * PANGO_SCALE);
   pango_layout_set_alignment (layout, PANGO_ALIGN_CENTER);
      		      
   pango_layout_get_size (layout, NULL, &layout_height);
   text_height = (double)layout_height / PANGO_SCALE;
   
   cairo_move_to (cr, width / 2,  (HEADER_HEIGHT - text_height) / 2);
   pango_cairo_show_layout (cr, layout);
   
   g_object_unref (layout);
 }
 

Use PrintOperation.setUseFullPage(boolean) and PrintOperation.setUnit(org.gnome.gtk.Unit) before starting the print operation to set up the transformation of the cairo context according to your needs.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.DrawPageCallback.run(org.gnome.gtk.PrintContext, int)

onEndPrint

public B onEndPrint(PrintOperation.EndPrintCallback handler)

Emitted after all pages have been rendered.

A handler for this signal can clean up any resources that have been allocated in the Gtk.PrintOperation::begin-print handler.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.EndPrintCallback.run(org.gnome.gtk.PrintContext)

onPaginate

public B onPaginate(PrintOperation.PaginateCallback handler)

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 PrintOperation.setNPages(int), 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.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.PaginateCallback.run(org.gnome.gtk.PrintContext)

onPreview

public B onPreview(PrintOperation.PreviewCallback handler)

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 PrintContext.setCairoContext(org.freedesktop.cairo.Context, double, double).

The custom preview implementation can use PrintOperationPreview.isSelected(int) and PrintOperationPreview.renderPage(int) to find pages which are selected for print and render them. The preview must be finished by calling PrintOperationPreview.endPreview() (typically in response to the user clicking a close button).

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.PreviewCallback.run(org.gnome.gtk.PrintOperationPreview, org.gnome.gtk.PrintContext, org.gnome.gtk.Window)

onRequestPageSetup

public B onRequestPageSetup(PrintOperation.RequestPageSetupCallback handler)

Emitted once for every page that is printed.

This gives the application a chance to modify the page setup. Any changes done to setup will be in force only for printing this page.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.RequestPageSetupCallback.run(org.gnome.gtk.PrintContext, int, org.gnome.gtk.PageSetup)

onStatusChanged

public B onStatusChanged(PrintOperation.StatusChangedCallback handler)

Emitted at between the various phases of the print operation.

See Gtk.PrintStatus for the phases that are being discriminated. Use PrintOperation.getStatus() to find out the current status.

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.StatusChangedCallback.run()

onUpdateCustomWidget

public B onUpdateCustomWidget(PrintOperation.UpdateCustomWidgetCallback handler)

Emitted after change of selected printer.

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

Parameters:

handler - the signal handler

Returns:

the Builder instance is returned, to allow method chaining

See Also:

• PrintOperation.UpdateCustomWidgetCallback.run(org.gnome.gtk.Widget, org.gnome.gtk.PageSetup, org.gnome.gtk.PrintSettings)