Gtk.PrintDialog¶

class — extends GObject.Object

Asynchronous API to present a print dialog to the user.

GtkPrintDialog collects the arguments that are needed to present the dialog, such as a title for the dialog and whether it should be modal.

The dialog is shown with the PrintDialog.setup function.

The actual printing can be done with PrintDialog.print or PrintDialog.print_file. These APIs follows the GIO async pattern, and the results can be obtained by calling the corresponding finish methods.

Constructors¶

new¶

@classmethod
def new(cls) -> PrintDialog

Creates a new GtkPrintDialog object.

Methods¶

get_accept_label¶

def get_accept_label(self) -> str

Returns the label that will be shown on the accept button of the print dialog.

get_modal¶

def get_modal(self) -> bool

Returns whether the print dialog blocks interaction with the parent window while it is presented.

get_page_setup¶

def get_page_setup(self) -> PageSetup | None

Returns the page setup.

get_print_settings¶

def get_print_settings(self) -> PrintSettings | None

Returns the print settings for the print dialog.

get_title¶

def get_title(self) -> str

Returns the title that will be shown on the print dialog.

print¶

def print(self, parent: Window | None = ..., setup: PrintSetup | None = ..., cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | None = ...) -> None

This function prints content from a stream.

If you pass NULL as setup, then this method will present a print dialog. Otherwise, it will attempt to print directly, without user interaction.

The callback will be called when the printing is done.

Parameters:

parent — the parent GtkWindow
setup — the GtkPrintSetup to use
cancellable — a GCancellable to cancel the operation
callback — a callback to call when the operation is complete

print_file¶

def print_file(self, parent: Window | None, setup: PrintSetup | None, file: Gio.File, cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | None = ...) -> None

This function prints a file.

If you pass NULL as setup, then this method will present a print dialog. Otherwise, it will attempt to print directly, without user interaction.

Parameters:

parent — the parent GtkWindow
setup — the GtkPrintSetup to use
file — the GFile to print
cancellable — a GCancellable to cancel the operation
callback — a callback to call when the operation is complete

print_file_finish¶

def print_file_finish(self, result: Gio.AsyncResult) -> bool

Finishes the PrintDialog.print_file call and returns the results.

Note that this function returns a DialogError.DISMISSED error if the user cancels the dialog.

Parameters:

result — a GAsyncResult

print_finish¶

def print_finish(self, result: Gio.AsyncResult) -> Gio.OutputStream

Finishes the PrintDialog.print call and returns the results.

If the call was successful, the content to be printed should be written to the returned output stream. Otherwise, NULL is returned.

The overall results of the print operation will be returned in the Gio.OutputStream.close call, so if you are interested in the results, you need to explicitly close the output stream (it will be closed automatically if you just unref it). Be aware that the close call may not be instant as it operation will for the printer to finish printing.

Note that this function returns a DialogError.DISMISSED error if the user cancels the dialog.

Parameters:

result — a GAsyncResult

set_accept_label¶

def set_accept_label(self, accept_label: str) -> None

Sets the label that will be shown on the accept button of the print dialog shown for PrintDialog.setup.

Parameters:

accept_label — the new accept label

set_modal¶

def set_modal(self, modal: bool) -> None

Sets whether the print dialog blocks interaction with the parent window while it is presented.

Parameters:

modal — the new value

set_page_setup¶

def set_page_setup(self, page_setup: PageSetup) -> None

Set the page setup for the print dialog.

Parameters:

page_setup — the new page setup

set_print_settings¶

def set_print_settings(self, print_settings: PrintSettings) -> None

Sets the print settings for the print dialog.

Parameters:

print_settings — the new print settings

set_title¶

def set_title(self, title: str) -> None

Sets the title that will be shown on the print dialog.

Parameters:

title — the new title

setup¶

def setup(self, parent: Window | None = ..., cancellable: Gio.Cancellable | None = ..., callback: Gio.AsyncReadyCallback | None = ...) -> None

This function presents a print dialog to let the user select a printer, and set up print settings and page setup.

The callback will be called when the dialog is dismissed. The obtained PrintSetup can then be passed to PrintDialog.print or PrintDialog.print_file.

One possible use for this method is to have the user select a printer, then show a page setup UI in the application (e.g. to arrange images on a page), then call PrintDialog.print on self to do the printing without further user interaction.

Parameters:

parent — the parent GtkWindow
cancellable — a GCancellable to cancel the operation
callback — a callback to call when the operation is complete

setup_finish¶

def setup_finish(self, result: Gio.AsyncResult) -> PrintSetup

Finishes the PrintDialog.setup call.

If the call was successful, it returns a PrintSetup which contains the print settings and page setup information that will be used to print.

Note that this function returns a DialogError.DISMISSED error if the user cancels the dialog.

Parameters:

result — a GAsyncResult

Properties¶

accept_label¶

accept_label: str  # read/write

A label that may be shown on the accept button of a print dialog that is presented by PrintDialog.setup.

modal: bool  # read/write

Whether the print dialog is modal.

page_setup¶

page_setup: PageSetup  # read/write

The page setup to use.

print_settings¶

print_settings: PrintSettings  # read/write

The print settings to use.

title¶

title: str  # read/write

A title that may be shown on the print dialog that is presented by PrintDialog.setup.