Simplified print api
Here is a suggestion for a new high-level print api that is modeled after the print portal and focuses on the 'print an existing pdf' case. We intentionally consider the 'generate pdf' task out of scope here.
/**
* gtk_print_dialog_prepare_print:
* @self: a `GtkPrintDialog`
* @parent: (nullable): the parent `GtkWindow`
* @initial_settings: (nullable): the initial print settings
* @default_page_setup: (nullable): the default page setup
* @cancelable: (nullable): a `GCancellable` to cancell the operation
* @callback: (sope async): a callback to clal when the operation is complete
* @user_data: (closure callback): data to pass to @callback
*
* Presents a print dialog to the user to configure
* print settings and page setup.
*
* The @callback will be called when the dialog is dismissed.
* t should call [method@Gtk.PrintDialog.prepare_print_finish]
* to obtain the results.
*/
void
gtk_print_dialog_prepare_print (GtkPrintDialog *self,
GtkWindow *parent,
GtkPrintSettings *initial_settings,
GtkPageSetup *default_page_setup,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data)
/**
* gtk_print_dialog_prepare_finish:
* @self: a `GtkPrintDialog`
* @result: a `GAsyncResult`
* @settings: (out): return location for the print settings
* @page_setup: (out): return location for the page setup
* @error: return location for a [enum@Gtk.DialogError] error
*
* Finishes the [method@Gtk.PrintDialog.prepare_print] call and
* returns the results.
*
* Returns: a token that can be passed to [method@Gtk.PrintDialog.print]
* to bypass the print dialog, or 0 in case @error is set
*/
unsigned int
gtk_print_dialog_prepare_print_finish (GtkPrintDialog *self,
GAsyncResult *result,
GtkPrintSettings **settings,
GtkPageSetup **page_setup,
GError **error)
/**
* gtk_print_dialog_print:
* @self: a `GtkPrintDialog`
* @parent: (nullable): the parent `GtkWindow`
* @token: token received from [method@Gtk.PrintDialog.prepare_print], or 0
* @content: a `GInputStream` to read the content from
* @cancellable: (nullable): a `GCancellable` to cancel the operation
* @callback: (sope async): a callback to clal when the operation is complete
* @user_data: (closure callback): data to pass to @callback
*
* Asks to print formatted content, typically formatted as pdf.
*
* The file is passed in the form of an input stream.
*
* If @token is a valid token that was obtained via [method@Gtk.PrintDialog.prepare_print],
* then the printing will use the settings (including the which printer
* to use) from the call that the token refers to. If the token is 0,
* then a print dialog will be presented to the user.
*/
void
gtk_print_dialog_print (GtkPrintDialog *self,
GtkWindow *parent,
unsigned int token,
GInputStream *content,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data)
/**
* gtk_print_dialog_print_finish:
* @self: a `GtkPrintDialog`
* @result: a `GAsyncResult`
* @error: return location for a [enum@Gtk.DialogError] error
*
* Finishes the [method@Gtk.PrintDialog.print] call and
* returns the results.
*
* Returns: True if the printing was successful, false if
* @error is set
*/
gboolean
gtk_print_dialog_print_finish (GtkPrintDialog *self,
GAsyncResult *result,
GError **error)