gtkmm: Gtk::PrintDialog Class Reference

gtkmm 4.14.0

Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Gtk::PrintDialog Class Reference
Dialogs | Printing

A Gtk::PrintDialog object collects the arguments that are needed to present a print dialog to the user, such as a title for the dialog and whether it should be modal. More...

`#include <gtkmm/printdialog.h>`

Inheritance diagram for Gtk::PrintDialog:
[legend]

## Public Member Functions
| PrintDialog (PrintDialog && src) noexcept
PrintDialog & | operator= (PrintDialog && src) noexcept
| ~PrintDialog () noexcept override
GtkPrintDialog * | gobj ()
| Provides access to the underlying C GObject. More...
const GtkPrintDialog * | gobj () const
| Provides access to the underlying C GObject. More...
GtkPrintDialog * | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
Glib::ustring | get_title () const
| Returns the title that will be shown on the print dialog. More...
void | set_title (const Glib::ustring & title)
| Sets the title that will be shown on the print dialog. More...
Glib::ustring | get_accept_label () const
| Returns the label that will be shown on the accept button of the print dialog. More...
void | set_accept_label (const Glib::ustring & accept_label)
| Sets the label that will be shown on the accept button of the print dialog shown for setup(). More...
bool | get_modal () const
| Returns whether the print dialog blocks interaction with the parent window while it is presented. More...
void | set_modal (bool modal=true)
| Sets whether the print dialog blocks interaction with the parent window while it is presented. More...
Glib::RefPtr< PageSetup > | get_page_setup ()
| Returns the page setup. More...
Glib::RefPtr< const PageSetup > | get_page_setup () const
| Returns the page setup. More...
void | set_page_setup (const Glib::RefPtr< PageSetup > & page_setup)
| Set the page setup for the print dialog. More...
Glib::RefPtr< PrintSettings > | get_print_settings ()
| Returns the print settings for the print dialog. More...
Glib::RefPtr< const PrintSettings > | get_print_settings () const
| Returns the print settings for the print dialog. More...
void | set_print_settings (const Glib::RefPtr< PrintSettings > & print_settings)
| Sets the print settings for the print dialog. More...
void | setup (Window & parent, const Gio::SlotAsyncReady & slot, const Glib::RefPtr< Gio::Cancellable > & cancellable={})
| This function presents a print dialog to let the user select a printer, and set up print settings and page setup. More...
void | setup (const Gio::SlotAsyncReady & slot, const Glib::RefPtr< Gio::Cancellable > & cancellable={})
| A setup() convenience overload. More...
Glib::RefPtr< PrintSetup > | setup_finish (const Glib::RefPtr< Gio::AsyncResult > & result)
| Finishes the setup() call. More...
void | print (Window & parent, const Gio::SlotAsyncReady & slot, const Glib::RefPtr< PrintSetup > &setup={}, const Glib::RefPtr< Gio::Cancellable > & cancellable={})
| This function prints content from a stream. More...
void | print (const Gio::SlotAsyncReady & slot, const Glib::RefPtr< PrintSetup > &setup={}, const Glib::RefPtr< Gio::Cancellable > & cancellable={})
| A print() convenience overload. More...
Glib::RefPtr< Gio::OutputStream > | print_finish (const Glib::RefPtr< Gio::AsyncResult > & result)
| Finishes the print() call and returns the results. More...
void | print_file (Window & parent, const Gio::SlotAsyncReady & slot, const Glib::RefPtr< Gio::File > & file, const Glib::RefPtr< PrintSetup > &setup={}, const Glib::RefPtr< Gio::Cancellable > & cancellable={})
| This function prints a file. More...
void | print_file (const Gio::SlotAsyncReady & slot, const Glib::RefPtr< Gio::File > & file, const Glib::RefPtr< PrintSetup > &setup={}, const Glib::RefPtr< Gio::Cancellable > & cancellable={})
| A print_file() convenience overload. More...
bool | print_file_finish (const Glib::RefPtr< Gio::AsyncResult > & result)
| Finishes the print_file() call and returns the results. More...
Glib::PropertyProxy< Glib::ustring > | property_title ()
| A title that may be shown on the print dialog that is presented by Gtk::PrintDialog::setup(). More...
Glib::PropertyProxy_ReadOnly< Glib::ustring > | property_title () const
| A title that may be shown on the print dialog that is presented by Gtk::PrintDialog::setup(). More...
Glib::PropertyProxy< Glib::ustring > | property_accept_label ()
| A label that may be shown on the accept button of a print dialog that is presented by Gtk::PrintDialog::setup(). More...
Glib::PropertyProxy_ReadOnly< Glib::ustring > | property_accept_label () const
| A label that may be shown on the accept button of a print dialog that is presented by Gtk::PrintDialog::setup(). More...
Glib::PropertyProxy< bool > | property_modal ()
| Whether the print dialog is modal. More...
Glib::PropertyProxy_ReadOnly< bool > | property_modal () const
| Whether the print dialog is modal. More...
Glib::PropertyProxy< Glib::RefPtr< PageSetup > > | property_page_setup ()
| The page setup to use. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< PageSetup > > | property_page_setup () const
| The page setup to use. More...
Glib::PropertyProxy< Glib::RefPtr< PrintSettings > > | property_print_settings ()
| The print settings to use. More...
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< PrintSettings > > | property_print_settings () const
| The print settings to use. More...
Public Member Functions inherited from Glib::Object
| Object (const Object &)=delete
Object & | operator= (const Object &)=delete
| Object (Object &&src) noexcept
Object & | operator= (Object &&src) noexcept
void * | get_data (const QueryQuark &key)
void | set_data (const Quark &key, void *data)
void | set_data_with_c_callback (const Quark &key, void *data, GDestroyNotify notify)
void | set_data (const Quark &key, void *data, DestroyNotify notify)
void | remove_data (const QueryQuark &quark)
void * | steal_data (const QueryQuark &quark)
Glib::RefPtr< Glib::Object > | wrap (GObject *object, bool take_copy=false)
Public Member Functions inherited from Glib::ObjectBase
| ObjectBase (const ObjectBase &)=delete
ObjectBase & | operator= (const ObjectBase &)=delete
void | set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
void | get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
void | set_property (const Glib::ustring &property_name, const PropertyType &value)
void | get_property (const Glib::ustring &property_name, PropertyType &value) const
PropertyType | get_property (const Glib::ustring &property_name) const
sigc::connection | connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void()> &slot)
sigc::connection | connect_property_changed (const Glib::ustring &property_name, sigc::slot< void()> &&slot)
void | freeze_notify ()
void | thaw_notify ()
virtual void | reference () const
virtual void | unreference () const
GObject * | gobj ()
const GObject * | gobj () const
GObject * | gobj_copy () const
Public Member Functions inherited from sigc::trackable
| trackable () noexcept
| trackable (const trackable &src) noexcept
| trackable (trackable &&src) noexcept
| ~trackable ()
void | add_destroy_notify_callback (notifiable *data, func_destroy_notify func) const
void | notify_callbacks ()
trackable & | operator= (const trackable &src)
trackable & | operator= (trackable &&src) noexcept
void | remove_destroy_notify_callback (notifiable *data) const

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
static Glib::RefPtr< PrintDialog > | create ()

## Protected Member Functions
| PrintDialog ()
Protected Member Functions inherited from Glib::Object
| Object ()
| Object (const Glib::ConstructParams &construct_params)
| Object (GObject *castitem)
| ~Object () noexcept override
Protected Member Functions inherited from Glib::ObjectBase
| ObjectBase ()
| ObjectBase (const char *custom_type_name)
| ObjectBase (const std::type_info &custom_type_info)
| ObjectBase (ObjectBase &&src) noexcept
ObjectBase & | operator= (ObjectBase &&src) noexcept
virtual | ~ObjectBase () noexcept=0
void | initialize (GObject *castitem)
void | initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gtk::PrintDialog > | wrap (GtkPrintDialog * object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Additional Inherited Members
Public Types inherited from Glib::Object
typedef void(*)(gpointer data | DestroyNotify)
Public Types inherited from sigc::trackable
typedef internal::func_destroy_notify | func_destroy_notify
Public Types inherited from sigc::notifiable
typedef internal::func_destroy_notify | func_destroy_notify

## Detailed Description

A Gtk::PrintDialog object collects the arguments that are needed to present a print dialog to the user, such as a title for the dialog and whether it should be modal.

The dialog is shown with the setup() function. The actual printing can be done with print() or print_file(). These APIs follow the GIO async pattern, and the results can be obtained by calling the corresponding finish methods.

Since gtkmm 4.14:

## Constructor & Destructor Documentation

## ◆ PrintDialog() [1/2]

Gtk::PrintDialog::PrintDialog | ( | PrintDialog && | src | ) |
| noexcept

## ◆ ~PrintDialog()

Gtk::PrintDialog::~PrintDialog | ( |  | ) |
| overridenoexcept

## ◆ PrintDialog() [2/2]

Gtk::PrintDialog::PrintDialog | ( |  | ) |
| protected

## Member Function Documentation

## ◆ create()

static Glib::RefPtr< PrintDialog > Gtk::PrintDialog::create | ( |  | ) |
| static

## ◆ get_accept_label()

Glib::ustring Gtk::PrintDialog::get_accept_label | ( |  | ) | const

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

Since gtkmm 4.14:

Returns
  The accept label.

## ◆ get_modal()

bool Gtk::PrintDialog::get_modal | ( |  | ) | const

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

Since gtkmm 4.14:

Returns
  Whether the print dialog is modal.

## ◆ get_page_setup() [1/2]

Glib::RefPtr< PageSetup > Gtk::PrintDialog::get_page_setup | ( |  | ) |

Returns the page setup.

Since gtkmm 4.14:

Returns
  The page setup.

## ◆ get_page_setup() [2/2]

Glib::RefPtr< const PageSetup > Gtk::PrintDialog::get_page_setup | ( |  | ) | const

Returns the page setup.

Since gtkmm 4.14:

Returns
  The page setup.

## ◆ get_print_settings() [1/2]

Glib::RefPtr< PrintSettings > Gtk::PrintDialog::get_print_settings | ( |  | ) |

Returns the print settings for the print dialog.

Since gtkmm 4.14:

Returns
  The settings.

## ◆ get_print_settings() [2/2]

Glib::RefPtr< const PrintSettings > Gtk::PrintDialog::get_print_settings | ( |  | ) | const

Returns the print settings for the print dialog.

Since gtkmm 4.14:

Returns
  The settings.

## ◆ get_title()

Glib::ustring Gtk::PrintDialog::get_title | ( |  | ) | const

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

Since gtkmm 4.14:

Returns
  The title.

## ◆ get_type()

static GType Gtk::PrintDialog::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ gobj() [1/2]

GtkPrintDialog * Gtk::PrintDialog::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

## ◆ gobj() [2/2]

const GtkPrintDialog * Gtk::PrintDialog::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

## ◆ gobj_copy()

GtkPrintDialog * Gtk::PrintDialog::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

## ◆ operator=()

PrintDialog & Gtk::PrintDialog::operator= | ( | PrintDialog && | src | ) |
| noexcept

## ◆ print() [1/2]

void Gtk::PrintDialog::print | ( | const Gio::SlotAsyncReady & | slot,
|  | const Glib::RefPtr< PrintSetup > & | setup = `{}`,
|  | const Glib::RefPtr< Gio::Cancellable > & | cancellable = `{}`
| ) |  |

A print() convenience overload.

## ◆ print() [2/2]

void Gtk::PrintDialog::print | ( | Window & | parent,
|  | const Gio::SlotAsyncReady & | slot,
|  | const Glib::RefPtr< PrintSetup > & | setup = `{}`,
|  | const Glib::RefPtr< Gio::Cancellable > & | cancellable = `{}`
| ) |  |

This function prints content from a stream.

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

The slot will be called when the printing is done. It should call print_finish() to obtain the results.

Since gtkmm 4.14:

Parameters

  parent | The parent `Gtk::Window`.
  setup | The `Gtk::PrintSetup` to use.
  cancellable | A `Cancellable` to cancel the operation.
  slot | A callback to call when the operation is complete.

## ◆ print_file() [1/2]

void Gtk::PrintDialog::print_file | ( | const Gio::SlotAsyncReady & | slot,
|  | const Glib::RefPtr< Gio::File > & | file,
|  | const Glib::RefPtr< PrintSetup > & | setup = `{}`,
|  | const Glib::RefPtr< Gio::Cancellable > & | cancellable = `{}`
| ) |  |

A print_file() convenience overload.

## ◆ print_file() [2/2]

void Gtk::PrintDialog::print_file | ( | Window & | parent,
|  | const Gio::SlotAsyncReady & | slot,
|  | const Glib::RefPtr< Gio::File > & | file,
|  | const Glib::RefPtr< PrintSetup > & | setup = `{}`,
|  | const Glib::RefPtr< Gio::Cancellable > & | cancellable = `{}`
| ) |  |

This function prints a file.

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

The slot will be called when the printing is done. It should call print_file_finish() to obtain the results.

Since gtkmm 4.14:

Parameters

  parent | The parent `Gtk::Window`.
  setup | The `Gtk::PrintSetup` to use.
  file | The `Gio::File` to print.
  cancellable | A `Cancellable` to cancel the operation.
  slot | A callback to call when the operation is complete.

## ◆ print_file_finish()

bool Gtk::PrintDialog::print_file_finish | ( | const Glib::RefPtr< Gio::AsyncResult > & | result | ) |

Finishes the print_file() call and returns the results.

Since gtkmm 4.14:

Parameters

  result | A `Gio::AsyncResult`.

Returns
  Whether the call was successful.

Exceptions

  Gtk::DialogError |

## ◆ print_finish()

Glib::RefPtr< Gio::OutputStream > Gtk::PrintDialog::print_finish | ( | const Glib::RefPtr< Gio::AsyncResult > & | result | ) |

Finishes the 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, `nullptr` 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.

Since gtkmm 4.14:

Parameters

  result | A `Gio::AsyncResult`.

Returns
  A Gio::OutputStream.

Exceptions

  Gtk::DialogError |

## ◆ property_accept_label() [1/2]

Glib::PropertyProxy< Glib::ustring > Gtk::PrintDialog::property_accept_label | ( |  | ) |

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

Since gtkmm 4.14:

Default value: ""

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## ◆ property_accept_label() [2/2]

Glib::PropertyProxy_ReadOnly< Glib::ustring > Gtk::PrintDialog::property_accept_label | ( |  | ) | const

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

Since gtkmm 4.14:

Default value: ""

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_modal() [1/2]

Glib::PropertyProxy< bool > Gtk::PrintDialog::property_modal | ( |  | ) |

Whether the print dialog is modal.

Since gtkmm 4.14:

Default value: `true`

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## ◆ property_modal() [2/2]

Glib::PropertyProxy_ReadOnly< bool > Gtk::PrintDialog::property_modal | ( |  | ) | const

Whether the print dialog is modal.

Since gtkmm 4.14:

Default value: `true`

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_page_setup() [1/2]

Glib::PropertyProxy< Glib::RefPtr< PageSetup > > Gtk::PrintDialog::property_page_setup | ( |  | ) |

The page setup to use.

Since gtkmm 4.14:

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## ◆ property_page_setup() [2/2]

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< PageSetup > > Gtk::PrintDialog::property_page_setup | ( |  | ) | const

The page setup to use.

Since gtkmm 4.14:

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_print_settings() [1/2]

Glib::PropertyProxy< Glib::RefPtr< PrintSettings > > Gtk::PrintDialog::property_print_settings | ( |  | ) |

The print settings to use.

Since gtkmm 4.14:

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## ◆ property_print_settings() [2/2]

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< PrintSettings > > Gtk::PrintDialog::property_print_settings | ( |  | ) | const

The print settings to use.

Since gtkmm 4.14:

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_title() [1/2]

Glib::PropertyProxy< Glib::ustring > Gtk::PrintDialog::property_title | ( |  | ) |

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

Since gtkmm 4.14:

Default value: ""

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## ◆ property_title() [2/2]

Glib::PropertyProxy_ReadOnly< Glib::ustring > Gtk::PrintDialog::property_title | ( |  | ) | const

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

Since gtkmm 4.14:

Default value: ""

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ set_accept_label()

void Gtk::PrintDialog::set_accept_label | ( | const Glib::ustring & | accept_label | ) |

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

Since gtkmm 4.14:

Parameters

  accept_label | The new accept label.

## ◆ set_modal()

void Gtk::PrintDialog::set_modal | ( | bool | modal = `true` | ) |

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

Since gtkmm 4.14:

Parameters

  modal | The new value.

## ◆ set_page_setup()

void Gtk::PrintDialog::set_page_setup | ( | const Glib::RefPtr< PageSetup > & | page_setup | ) |

Set the page setup for the print dialog.

Since gtkmm 4.14:

Parameters

  page_setup | The new page setup.

## ◆ set_print_settings()

void Gtk::PrintDialog::set_print_settings | ( | const Glib::RefPtr< PrintSettings > & | print_settings | ) |

Sets the print settings for the print dialog.

Since gtkmm 4.14:

Parameters

  print_settings | The new print settings.

## ◆ set_title()

void Gtk::PrintDialog::set_title | ( | const Glib::ustring & | title | ) |

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

Since gtkmm 4.14:

Parameters

  title | The new title.

## ◆ setup() [1/2]

void Gtk::PrintDialog::setup | ( | const Gio::SlotAsyncReady & | slot,
|  | const Glib::RefPtr< Gio::Cancellable > & | cancellable = `{}`
| ) |  |

A setup() convenience overload.

## ◆ setup() [2/2]

void Gtk::PrintDialog::setup | ( | Window & | parent,
|  | const Gio::SlotAsyncReady & | slot,
|  | const Glib::RefPtr< Gio::Cancellable > & | cancellable = `{}`
| ) |  |

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

The slot will be called when the dialog is dismissed. It should call setup_finish() to obtain the results in the form of a Gtk::PrintSetup, that can then be passed to print() or 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 print() on self to do the printing without further user interaction.

Since gtkmm 4.14:

Parameters

  parent | The parent `Gtk::Window`.
  cancellable | A `Cancellable` to cancel the operation.
  slot | A callback to call when the operation is complete.

## ◆ setup_finish()

Glib::RefPtr< PrintSetup > Gtk::PrintDialog::setup_finish | ( | const Glib::RefPtr< Gio::AsyncResult > & | result | ) |

Finishes the setup() call.

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

Since gtkmm 4.14:

Parameters

  result | A `Gio::AsyncResult`.

Returns
  The `Gtk::PrintSetup` object that resulted from the call, or `nullptr` if the call was not successful.

Exceptions

  Gtk::DialogError |

## Friends And Related Function Documentation

## ◆ wrap()

Glib::RefPtr< Gtk::PrintDialog > wrap | ( | GtkPrintDialog * | object,
|  | bool | take_copy = `false`
| ) |  |
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.