Clean up APIs: Make async a setting instead of separate calls. Combine

2006-06-07  Alexander Larsson  <alexl@redhat.com>

	* gtk/gtk.symbols:
	* gtk/gtkprintoperation-private.h:
	* gtk/gtkprintoperation-unix.c:
	* gtk/gtkprintoperation.[ch]:
	Clean up APIs:
	Make async a setting instead of separate calls.
	Combine settings like show_dialog, show_preview and pdf_target into
	an action enum that you pass to gtk_print_dialog_run().

	* tests/print-editor.c:
	* tests/testnouiprint.c:
	* tests/testprint.c:
	* demos/gtk-demo/printing.c:
	Update to new APIs

5 files changed, 226 insertions, 218 deletions

diff --git a/gtk/gtk.symbols b/gtk/gtk.symbols
index 3c4a82478e..0af6aad0cb 100644
--- a/gtk/gtk.symbols
+++ b/gtk/gtk.symbols
@@ -2697,14 +2697,12 @@ gtk_print_operation_set_n_pages
 gtk_print_operation_set_current_page
 gtk_print_operation_set_use_full_page
 gtk_print_operation_set_unit
-gtk_print_operation_set_show_dialog
 gtk_print_operation_set_pdf_target
 gtk_print_operation_set_track_print_status
 gtk_print_operation_set_show_progress
-gtk_print_operation_set_show_preview
 gtk_print_operation_set_custom_tab_label
+gtk_print_operation_get_error
 gtk_print_operation_run
-gtk_print_operation_run_async
 gtk_print_operation_get_status
 gtk_print_operation_get_status_string
 gtk_print_operation_is_finished
diff --git a/gtk/gtkprintoperation-private.h b/gtk/gtkprintoperation-private.h
index dbc25bfa56..bc7117ed23 100644
--- a/gtk/gtkprintoperation-private.h
+++ b/gtk/gtkprintoperation-private.h
@@ -27,7 +27,9 @@ G_BEGIN_DECLS
 
 struct _GtkPrintOperationPrivate
 {
+  GtkPrintOperationAction action;
   GtkPrintStatus status;
+  GError *error;
   gchar *status_string;
   GtkPageSetup *default_page_setup;
   GtkPrintSettings *print_settings;
@@ -37,11 +39,10 @@ struct _GtkPrintOperationPrivate
   GtkUnit unit;
   gchar *pdf_target;
   guint use_full_page      : 1;
-  guint show_dialog        : 1;
-  guint show_preview       : 1;
   guint track_print_status : 1;
   guint show_progress      : 1;
   guint cancelled          : 1;
+  guint allow_async        : 1;
   guint is_sync            : 1;
 
   guint print_pages_idle_id;
@@ -84,13 +85,15 @@ struct _GtkPrintOperationPrivate
 
 typedef void (* GtkPrintOperationPrintFunc) (GtkPrintOperation *op,
 					     GtkWindow         *parent,
-					     gboolean           is_preview);
+					     gboolean           do_print,
+					     GtkPrintOperationResult result);
 
 GtkPrintOperationResult _gtk_print_operation_platform_backend_run_dialog             (GtkPrintOperation           *operation,
+										      gboolean                     show_dialog,
 										      GtkWindow                   *parent,
-										      gboolean                    *do_print,
-										      GError                     **error);
+										      gboolean                    *do_print);
 void                    _gtk_print_operation_platform_backend_run_dialog_async       (GtkPrintOperation           *op,
+										      gboolean                     show_dialog,
 										      GtkWindow                   *parent,
 										      GtkPrintOperationPrintFunc   print_cb);
 void                    _gtk_print_operation_platform_backend_launch_preview         (GtkPrintOperation           *op,
diff --git a/gtk/gtkprintoperation-unix.c b/gtk/gtkprintoperation-unix.c
index 2f66fa1ca8..d5389f92c7 100644
--- a/gtk/gtkprintoperation-unix.c
+++ b/gtk/gtkprintoperation-unix.c
@@ -350,7 +350,6 @@ typedef struct
 {
   GtkPrintOperation           *op;
   gboolean                     do_print;
-  GError                     **error;
   GtkPrintOperationResult      result;
   GtkPrintOperationPrintFunc   print_cb;
   GDestroyNotify               destroy;
@@ -391,7 +390,7 @@ finish_print (PrintResponseData *rdata,
 	  GtkPrintOperationUnix *op_unix;
 	  cairo_t *cr;
 	  
-	  op_unix = g_new0 (GtkPrintOperationUnix, 1);     
+	  op_unix = g_new0 (GtkPrintOperationUnix, 1);
 	  priv->platform_data = op_unix;
 	  priv->free_platform_data = (GDestroyNotify) op_unix_free;
 	  op_unix->parent = rdata->parent;
@@ -404,9 +403,10 @@ finish_print (PrintResponseData *rdata,
           op_unix->job = job;
           gtk_print_job_set_track_print_status (job, priv->track_print_status);
 	  
-	  op_unix->surface = gtk_print_job_get_surface (job, rdata->error);
+	  op_unix->surface = gtk_print_job_get_surface (job, &priv->error);
 	  if (op_unix->surface == NULL) 
             {
+	      rdata->result = GTK_PRINT_OPERATION_RESULT_ERROR;
 	      rdata->do_print = FALSE;
 	      goto out;
             }
@@ -435,12 +435,7 @@ finish_print (PrintResponseData *rdata,
     } 
  out:
   if (rdata->print_cb)
-    {
-      if (rdata->do_print)
-        rdata->print_cb (op, rdata->parent, is_preview); 
-      else
-       _gtk_print_operation_set_status (op, GTK_PRINT_STATUS_FINISHED_ABORTED, NULL); 
-    }
+    rdata->print_cb (op, rdata->do_print, rdata->parent, rdata->result); 
 
   if (rdata->destroy)
     rdata->destroy (rdata);
@@ -504,10 +499,7 @@ found_printer (GtkPrinter        *printer,
 
   if (printer != NULL) 
     {
-      if (priv->show_preview)
-        rdata->result = GTK_PRINT_OPERATION_RESULT_PREVIEW;
-      else
-        rdata->result = GTK_PRINT_OPERATION_RESULT_APPLY;
+      rdata->result = GTK_PRINT_OPERATION_RESULT_APPLY;
 
       rdata->do_print = TRUE;
 
@@ -536,6 +528,7 @@ found_printer (GtkPrinter        *printer,
 
 void
 _gtk_print_operation_platform_backend_run_dialog_async (GtkPrintOperation          *op,
+							gboolean                    show_dialog,
                                                         GtkWindow                  *parent,
 							GtkPrintOperationPrintFunc  print_cb)
 {
@@ -547,13 +540,12 @@ _gtk_print_operation_platform_backend_run_dialog_async (GtkPrintOperation
   rdata->op = g_object_ref (op);
   rdata->do_print = FALSE;
   rdata->result = GTK_PRINT_OPERATION_RESULT_CANCEL;
-  rdata->error = NULL;
   rdata->print_cb = print_cb;
   rdata->parent = parent;
   rdata->loop = NULL;
   rdata->destroy = print_response_data_free;
   
-  if (op->priv->show_dialog)
+  if (show_dialog)
     {
       pd = get_print_dialog (op, parent);
       gtk_window_set_modal (GTK_WINDOW (pd), TRUE);
@@ -608,9 +600,9 @@ _gtk_print_operation_platform_backend_resize_preview_surface (GtkPrintOperation
 
 GtkPrintOperationResult
 _gtk_print_operation_platform_backend_run_dialog (GtkPrintOperation *op,
+						  gboolean           show_dialog,
 						  GtkWindow         *parent,
-						  gboolean          *do_print,
-						  GError           **error)
+						  gboolean          *do_print)
  {
   GtkWidget *pd;
   PrintResponseData rdata;
@@ -620,13 +612,12 @@ _gtk_print_operation_platform_backend_run_dialog (GtkPrintOperation *op,
   rdata.op = op;
   rdata.do_print = FALSE;
   rdata.result = GTK_PRINT_OPERATION_RESULT_CANCEL;
-  rdata.error = error;
   rdata.print_cb = NULL;
   rdata.destroy = NULL;
   rdata.parent = parent;
   rdata.loop = NULL;
 
-  if (op->priv->show_dialog)
+  if (show_dialog)
     {
       pd = get_print_dialog (op, parent);
 
diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c
index 425faeaf0a..861d482acd 100644
--- a/gtk/gtkprintoperation.c
+++ b/gtk/gtkprintoperation.c
@@ -37,6 +37,7 @@
 #define GTK_PRINT_OPERATION_GET_PRIVATE(obj)(G_TYPE_INSTANCE_GET_PRIVATE ((obj), GTK_TYPE_PRINT_OPERATION, GtkPrintOperationPrivate))
 
 enum {
+  DONE,
   BEGIN_PRINT,
   PAGINATE,
   REQUEST_PAGE_SETUP,
@@ -59,9 +60,8 @@ enum {
   PROP_USE_FULL_PAGE,
   PROP_TRACK_PRINT_STATUS,
   PROP_UNIT,
-  PROP_SHOW_DIALOG,
-  PROP_SHOW_PREVIEW,
   PROP_SHOW_PROGRESS,
+  PROP_ALLOW_ASYNC,
   PROP_PDF_TARGET,
   PROP_STATUS,
   PROP_STATUS_STRING,
@@ -128,6 +128,9 @@ gtk_print_operation_finalize (GObject *object)
   if (priv->show_progress_timeout_id > 0)
     g_source_remove (priv->show_progress_timeout_id);
 
+  if (priv->error)
+    g_error_free (priv->error);
+  
   G_OBJECT_CLASS (gtk_print_operation_parent_class)->finalize (object);
 }
 
@@ -146,8 +149,6 @@ gtk_print_operation_init (GtkPrintOperation *operation)
   priv->nr_of_pages = -1;
   priv->current_page = -1;
   priv->use_full_page = FALSE;
-  priv->show_dialog = TRUE;
-  priv->show_preview = FALSE;
   priv->show_progress = FALSE;
   priv->pdf_target = NULL;
   priv->track_print_status = FALSE;
@@ -183,6 +184,9 @@ preview_iface_end_preview (GtkPrintOperationPreview *preview)
     g_main_loop_quit (op->priv->rloop);
 
   op->priv->end_run (op, op->priv->is_sync, TRUE);
+  
+  g_signal_emit (op, signals[DONE], 0,
+		 GTK_PRINT_OPERATION_RESULT_APPLY);
 }
 
 static gboolean
@@ -282,11 +286,8 @@ gtk_print_operation_set_property (GObject      *object,
     case PROP_UNIT:
       gtk_print_operation_set_unit (op, g_value_get_enum (value));
       break;
-    case PROP_SHOW_DIALOG:
-      gtk_print_operation_set_show_dialog (op, g_value_get_boolean (value));
-      break;
-    case PROP_SHOW_PREVIEW:
-      gtk_print_operation_set_show_preview (op, g_value_get_boolean (value));
+    case PROP_ALLOW_ASYNC:
+      gtk_print_operation_set_allow_async (op, g_value_get_boolean (value));
       break;
     case PROP_SHOW_PROGRESS:
       gtk_print_operation_set_show_progress (op, g_value_get_boolean (value));
@@ -338,11 +339,8 @@ gtk_print_operation_get_property (GObject    *object,
     case PROP_UNIT:
       g_value_set_enum (value, priv->unit);
       break;
-    case PROP_SHOW_DIALOG:
-      g_value_set_boolean (value, priv->show_dialog);
-      break;
-    case PROP_SHOW_PREVIEW:
-      g_value_set_boolean (value, priv->show_preview);
+    case PROP_ALLOW_ASYNC:
+      g_value_set_boolean (value, priv->allow_async);
       break;
     case PROP_SHOW_PROGRESS:
       g_value_set_boolean (value, priv->show_progress);
@@ -548,6 +546,31 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class)
   g_type_class_add_private (gobject_class, sizeof (GtkPrintOperationPrivate));
 
   /**
+   * GtkPrintOperation::done:
+   * @operation: the #GtkPrintOperation on which the signal was emitted
+   * @result: the result of the print operation
+   *
+   * Gets 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_PRINT_OPERATION_RESULT_ERROR then you can call
+   * gtk_print_operation_get_error() for more information.
+   *
+   * If you enabled print status tracking then gtk_print_operation_is_finished()
+   * may still return false after this was emitted.
+   *
+   * Since: 2.10
+   */
+  signals[DONE] =
+    g_signal_new (I_("done"),
+		  G_TYPE_FROM_CLASS (gobject_class),
+		  G_SIGNAL_RUN_LAST,
+		  G_STRUCT_OFFSET (GtkPrintOperationClass, done),
+		  NULL, NULL,
+		  g_cclosure_marshal_VOID__INT,
+		  G_TYPE_NONE, 1, G_TYPE_INT);
+
+  /**
    * GtkPrintOperation::begin-print:
    * @operation: the #GtkPrintOperation on which the signal was emitted
    * @context: the #GtkPrintContext for the current operation
@@ -980,56 +1003,41 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class)
 						      GTK_UNIT_PIXEL,
 						      GTK_PARAM_READWRITE));
   
-
+  
   /**
-   * GtkPrintOperation:show-dialog:
+   * GtkPrintOperation:show-progress:
    *
-   * Determines whether calling gtk_print_operation_run() will present
-   * a print dialog to the user, or just print to the default printer.
+   * Determines whether to show a progress dialog during the 
+   * print operation.
    *
    * Since: 2.10
    */
   g_object_class_install_property (gobject_class,
-				   PROP_SHOW_DIALOG,
-				   g_param_spec_boolean ("show-dialog",
+				   PROP_SHOW_PROGRESS,
+				   g_param_spec_boolean ("show-progress",
 							 P_("Show Dialog"),
-							 P_("TRUE if gtk_print_operation_run() should show the print dialog."),
-							 TRUE,
+							 P_("TRUE if a progress dialog is shown while printing."),
+							 FALSE,
 							 GTK_PARAM_READWRITE));
 
   /**
-   * GtkPrintOperation:show-preview:
-   *
-   * Determines whether calling gtk_print_operation_run() will present
-   * the print preview to the user.
-   *
-   * Since: 2.10
-   */
-  g_object_class_install_property (gobject_class,
-				   PROP_SHOW_PREVIEW,
-				   g_param_spec_boolean ("show-preview",
-							 P_("Show Preview"),
-							 P_("TRUE if gtk_print_operation_run() should show the print preview."),
-							 TRUE,
-							 GTK_PARAM_READWRITE));
-  
-  /**
-   * GtkPrintOperation:show-progress:
+   * GtkPrintOperation:allow-async:
    *
-   * Determines whether to show a progress dialog during the 
-   * print operation.
+   * Determines whether the print operation may run asynchronous or not.
+   * Some systems don't support asynchronous printing, but those that do
+   * will return GTK_PRINT_OPERATION_RESULT_IN_PROGRESS as the status, and
+   * emit the done signal when the operation is actually done.
    *
    * Since: 2.10
    */
   g_object_class_install_property (gobject_class,
-				   PROP_SHOW_PROGRESS,
-				   g_param_spec_boolean ("show-progress",
-							 P_("Show Dialog"),
-							 P_("TRUE if a progress dialog is shown while printing."),
+				   PROP_ALLOW_ASYNC,
+				   g_param_spec_boolean ("allow-async",
+							 P_("Allow Async"),
+							 P_("TRUE if print process may run asynchronous."),
 							 FALSE,
 							 GTK_PARAM_READWRITE));
   
-  
   /**
    * GtkPrintOperation:pdf-target:
    *
@@ -1548,6 +1556,10 @@ gtk_print_operation_get_status_string (GtkPrintOperation *op)
  * is finished, either successfully (%GTK_PRINT_STATUS_FINISHED)
  * or unsuccessfully (%GTK_PRINT_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.
+ * 
  * Return value: %TRUE, if the print operation is finished.
  *
  * Since: 2.10
@@ -1565,50 +1577,19 @@ gtk_print_operation_is_finished (GtkPrintOperation *op)
     priv->status == GTK_PRINT_STATUS_FINISHED;
 }
 
-
 /**
- * gtk_print_operation_set_show_dialog:
+ * gtk_print_operation_set_show_progress:
  * @op: a #GtkPrintOperation
- * @show_dialog: %TRUE to show the print dialog
+ * @show_progress: %TRUE to show a progress dialog
  * 
- * Sets whether calling gtk_print_operation_run() will present
- * a print dialog to the user, or just print to the default printer.
- *
- * Since: 2.10
- */
-void
-gtk_print_operation_set_show_dialog (GtkPrintOperation *op,
-				     gboolean           show_dialog)
-{
-  GtkPrintOperationPrivate *priv;
-
-  g_return_if_fail (GTK_IS_PRINT_OPERATION (op));
-
-  priv = op->priv;
-
-  show_dialog = show_dialog != FALSE;
-
-  if (priv->show_dialog != show_dialog)
-    {
-      priv->show_dialog = show_dialog;
-
-      g_object_notify (G_OBJECT (op), "show-dialog");
-    }
-}
-
-/**
- * gtk_print_operation_set_show_preview:
- * @op: a #GtkPrintOperation
- * @show_preview: %TRUE to show the print preview
+ * If @show_progress is %TRUE, the print operation will show a 
+ * progress dialog during the print operation.
  * 
- * Sets whether calling gtk_print_operation_run() will present
- * the print preview to the user.
- *
  * Since: 2.10
  */
 void
-gtk_print_operation_set_show_preview (GtkPrintOperation *op,
-				      gboolean           show_preview)
+gtk_print_operation_set_show_progress (GtkPrintOperation  *op,
+				       gboolean            show_progress)
 {
   GtkPrintOperationPrivate *priv;
 
@@ -1616,29 +1597,19 @@ gtk_print_operation_set_show_preview (GtkPrintOperation *op,
 
   priv = op->priv;
 
-  show_preview = show_preview != FALSE;
+  show_progress = show_progress != FALSE;
 
-  if (priv->show_preview != show_preview)
+  if (priv->show_progress != show_progress)
     {
-      priv->show_preview = show_preview;
+      priv->show_progress = show_progress;
 
-      g_object_notify (G_OBJECT (op), "show-preview");
+      g_object_notify (G_OBJECT (op), "show-progress");
     }
 }
 
-/**
- * gtk_print_operation_set_show_progress:
- * @op: a #GtkPrintOperation
- * @show_progress: %TRUE to show a progress dialog
- * 
- * If @show_progress is %TRUE, the print operation will show a 
- * progress dialog during the print operation.
- * 
- * Since: 2.10
- */
 void
-gtk_print_operation_set_show_progress (GtkPrintOperation  *op,
-				       gboolean            show_progress)
+gtk_print_operation_set_allow_async (GtkPrintOperation  *op,
+				     gboolean            allow_async)
 {
   GtkPrintOperationPrivate *priv;
 
@@ -1646,16 +1617,17 @@ gtk_print_operation_set_show_progress (GtkPrintOperation  *op,
 
   priv = op->priv;
 
-  show_progress = show_progress != FALSE;
+  allow_async = allow_async != FALSE;
 
-  if (priv->show_progress != show_progress)
+  if (priv->allow_async != allow_async)
     {
-      priv->show_progress = show_progress;
+      priv->allow_async = allow_async;
 
-      g_object_notify (G_OBJECT (op), "show-progress");
+      g_object_notify (G_OBJECT (op), "allow-async");
     }
 }
 
+
 /**
  * gtk_print_operation_set_custom_tag_label:
  * @op: a #GtkPrintOperation
@@ -1801,18 +1773,21 @@ pdf_end_run (GtkPrintOperation *op,
 static GtkPrintOperationResult
 run_pdf (GtkPrintOperation  *op,
 	 GtkWindow          *parent,
-	 gboolean           *do_print,
-	 GError            **error)
+	 gboolean           *do_print)
 {
   GtkPrintOperationPrivate *priv = op->priv;
   GtkPageSetup *page_setup;
   cairo_surface_t *surface;
   cairo_t *cr;
   double width, height;
-  /* This will be overwritten later by the non-default size, but
-     we need to pass some size: */
+  
+  priv->print_context = _gtk_print_context_new (op);
   
   page_setup = create_page_setup (op);
+  _gtk_print_context_set_page_setup (priv->print_context, page_setup);
+
+  /* This will be overwritten later by the non-default size, but
+     we need to pass some size: */
   width = gtk_page_setup_get_paper_width (page_setup, GTK_UNIT_POINTS);
   height = gtk_page_setup_get_paper_height (page_setup, GTK_UNIT_POINTS);
   g_object_unref (page_setup);
@@ -1939,11 +1914,17 @@ print_pages_idle_done (gpointer user_data)
   if (data->progress)
     gtk_widget_destroy (data->progress);
 
-  g_object_unref (data->op);
-
-  if (priv->rloop && !data->is_preview)
+  if (priv->rloop && !data->is_preview) 
     g_main_loop_quit (priv->rloop);
 
+  if (!data->is_preview)
+    g_signal_emit (data->op, signals[DONE], 0,
+		   priv->cancelled ?
+		   GTK_PRINT_OPERATION_RESULT_CANCEL :
+		   GTK_PRINT_OPERATION_RESULT_APPLY);
+  
+  g_object_unref (data->op);
+
   g_free (data);
 
   GDK_THREADS_LEAVE ();
@@ -2194,16 +2175,23 @@ show_progress_timeout (PrintPagesData *data)
 static void
 print_pages (GtkPrintOperation *op,
 	     GtkWindow         *parent,
-	     gboolean		is_preview)
+	     gboolean           do_print,
+	     GtkPrintOperationResult result)
 {
   GtkPrintOperationPrivate *priv = op->priv;
   PrintPagesData *data;
 
+  if (!do_print) {
+    _gtk_print_operation_set_status (op, GTK_PRINT_STATUS_FINISHED_ABORTED, NULL);
+    g_signal_emit (op, signals[DONE], 0, result);
+    return;
+  }
+  
   _gtk_print_operation_set_status (op, GTK_PRINT_STATUS_PREPARING, NULL);  
 
   data = g_new0 (PrintPagesData, 1);
   data->op = g_object_ref (op);
-  data->is_preview = is_preview;
+  data->is_preview = (result == GTK_PRINT_OPERATION_RESULT_PREVIEW);
 
   if (priv->show_progress)
     {
@@ -2224,7 +2212,7 @@ print_pages (GtkPrintOperation *op,
       data->progress = progress;
     }
 
-  if (is_preview)
+  if (data->is_preview)
     {
       gboolean handled;
       
@@ -2259,10 +2247,8 @@ print_pages (GtkPrintOperation *op,
 					       print_pages_idle, 
 					       data, 
 					       print_pages_idle_done);
-
-  /* Recursive main loop to make sure we don't exit 
-   * on sync operations 
-   */
+  
+  /* Recursive main loop to make sure we don't exit  on sync operations  */
   if (priv->is_sync)
     {
       priv->rloop = g_main_loop_new (NULL, FALSE);
@@ -2277,8 +2263,31 @@ print_pages (GtkPrintOperation *op,
 }
 
 /**
+ * gtk_print_operation_get_error:
+ * @op: a #GtkPrintOperation
+ * 
+ * Call this when the result of a print operation is
+ * GTK_PRINT_OPERATION_RESULT_ERROR, either as returned by gtk_print_operation_run (),
+ * or in the ::done signal handler. The returned #GError will contain more details
+ * on what went wrong.
+ *
+ * Return value: a GError representing the error, or NULL
+ *
+ * Since: 2.10
+ **/
+GError *
+gtk_print_operation_get_error (GtkPrintOperation  *op)
+{
+  g_return_val_if_fail (GTK_IS_PRINT_OPERATION (op), NULL);
+  
+  return op->priv->error;
+}
+
+
+/**
  * gtk_print_operation_run:
  * @op: a #GtkPrintOperation
+ * @action: the action to start
  * @parent: Transient parent of the dialog, or %NULL
  * @error: Return location for errors, or %NULL
  * 
@@ -2286,11 +2295,16 @@ print_pages (GtkPrintOperation *op,
  * print settings in the print dialog, and then print the
  * document.
  *
- * Note that this function does not return until the rendering of all 
+ * Normally that this function does not return until the rendering of all 
  * pages is complete. You can connect to the ::status-changed signal on
  * @op to obtain some information about the progress of the print operation. 
  * Furthermore, it may use a recursive mainloop to show the print dialog.
- * See gtk_print_operation_run_async() if this is a problem.
+ *
+ * If you call gtk_print_operation_set_allow_async () or 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).
  *
  * <informalexample><programlisting>
  * if (settings != NULL)
@@ -2304,7 +2318,7 @@ print_pages (GtkPrintOperation *op,
  * g_signal_connect (print, "draw-page", 
  *                   G_CALLBACK (draw_page), &amp;data);
  *  
- * res = gtk_print_operation_run (print, parent, &amp;error);
+ * res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG, parent, &amp;error);
  *  
  * if (res == GTK_PRINT_OPERATION_RESULT_ERROR)
  *  {
@@ -2331,85 +2345,78 @@ print_pages (GtkPrintOperation *op,
  *   %GTK_PRINT_OPERATION_RESULT_APPLY indicates that the printing was
  *   completed successfully. In this case, it is a good idea to obtain 
  *   the used print settings with gtk_print_operation_get_print_settings() 
- *   and store them for reuse with the next print operation.
+ *   and store them for reuse with the next print operation. A value of
+ *   %GTK_PRINT_OPERATION_RESULT_IN_PROGRESS means the operation is running
+ *   asynchronously, and will emit the ::done signal when done.
  *
  * Since: 2.10
  **/
 GtkPrintOperationResult
 gtk_print_operation_run (GtkPrintOperation  *op,
+			 GtkPrintOperationAction action,
 			 GtkWindow          *parent,
-			 GError            **error)
+			 GError            **opt_error)
 {
   GtkPrintOperationPrivate *priv;
   GtkPrintOperationResult result;
+  GtkPageSetup *page_setup;
   gboolean do_print;
   
   g_return_val_if_fail (GTK_IS_PRINT_OPERATION (op), 
                         GTK_PRINT_OPERATION_RESULT_ERROR);
 
   priv = op->priv;
-  priv->is_sync = TRUE;
-
-  if (priv->pdf_target != NULL)
-    result = run_pdf (op, parent, &do_print, error);
-  else
-    result = _gtk_print_operation_platform_backend_run_dialog (op, 
-							       parent,
-							       &do_print,
-							       error);
-  if (do_print)
-    print_pages (op, parent, result == GTK_PRINT_OPERATION_RESULT_PREVIEW);
-  else 
-    _gtk_print_operation_set_status (op, GTK_PRINT_STATUS_FINISHED_ABORTED, NULL);
-
-  return result;
-}
-
-/**
- * gtk_print_operation_run_async:
- * @op: a #GtkPrintOperation
- * @parent: Transient parent of the dialog, or %NULL
- * 
- * Runs the print operation, by first letting the user modify
- * print settings in the print dialog, and then print the
- * document.
- *
- * In contrast to gtk_print_operation_run(), this function returns after 
- * showing the print dialog on platforms that support this, and handles 
- * the printing by connecting a signal handler to the ::response signal 
- * of the dialog. 
- * 
- * If you use this function, it is recommended that you store the modified
- * #GtkPrintSettings in a ::begin-print or ::end-print signal handler.
- * 
- * Since: 2.10
- **/
-void
-gtk_print_operation_run_async (GtkPrintOperation *op,
-			       GtkWindow         *parent)
-{
-  GtkPrintOperationPrivate *priv;
-  gboolean do_print;
 
-  g_return_if_fail (GTK_IS_PRINT_OPERATION (op)); 
+  do_print = FALSE;
+  priv->error = NULL;
+  priv->action = action;
 
-  priv = op->priv;
-  priv->is_sync = FALSE;
-
-  if (priv->pdf_target != NULL)
+  if (priv->print_settings == NULL)
+    priv->print_settings = gtk_print_settings_new ();
+  
+  if (action == GTK_PRINT_OPERATION_ACTION_EXPORT)
+    {
+      priv->is_sync = TRUE;
+      g_return_val_if_fail (priv->pdf_target != NULL, GTK_PRINT_OPERATION_RESULT_ERROR);
+      result = run_pdf (op, parent, &do_print);
+    }
+  else if (action == GTK_PRINT_OPERATION_ACTION_PREVIEW)
+    {
+      priv->print_context = _gtk_print_context_new (op);
+      page_setup = create_page_setup (op);
+      _gtk_print_context_set_page_setup (priv->print_context, page_setup);
+      g_object_unref (page_setup);
+      do_print = TRUE;
+      result = GTK_PRINT_OPERATION_RESULT_PREVIEW;
+
+      priv->is_sync = !priv->allow_async;
+    }
+  else if (priv->allow_async)
     {
-      run_pdf (op, parent, &do_print, NULL);
-      if (do_print)
-	print_pages (op, parent, FALSE);
-      else 
-	_gtk_print_operation_set_status (op, GTK_PRINT_STATUS_FINISHED_ABORTED, NULL);
+      priv->is_sync = FALSE;
+      _gtk_print_operation_platform_backend_run_dialog_async (op,
+							      action == GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
+							      parent,
+							      print_pages);
+      result = GTK_PRINT_OPERATION_RESULT_IN_PROGRESS;
     }
   else
-    _gtk_print_operation_platform_backend_run_dialog_async (op, 
-							    parent,
-							    print_pages);
-}
+    {
+      priv->is_sync = TRUE;
+      result = _gtk_print_operation_platform_backend_run_dialog (op, 
+								 action == GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
+								 parent,
+								 &do_print);
+    }
+
+  if (result != GTK_PRINT_OPERATION_RESULT_IN_PROGRESS)
+    print_pages (op, parent, do_print, result);
 
+  if (priv->error && opt_error)
+    *opt_error = g_error_copy (priv->error);
+  
+  return result;
+}
 
 /**
  * gtk_print_operation_cancel:
diff --git a/gtk/gtkprintoperation.h b/gtk/gtkprintoperation.h
index 09ae769cb4..ac144f4ff3 100644
--- a/gtk/gtkprintoperation.h
+++ b/gtk/gtkprintoperation.h
@@ -56,6 +56,22 @@ typedef enum {
   GTK_PRINT_STATUS_FINISHED_ABORTED
 } GtkPrintStatus;
 
+typedef enum {
+  GTK_PRINT_OPERATION_RESULT_ERROR,
+  GTK_PRINT_OPERATION_RESULT_APPLY,
+  GTK_PRINT_OPERATION_RESULT_CANCEL,
+  GTK_PRINT_OPERATION_RESULT_PREVIEW,
+  GTK_PRINT_OPERATION_RESULT_IN_PROGRESS
+} GtkPrintOperationResult;
+
+typedef enum {
+  GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
+  GTK_PRINT_OPERATION_ACTION_PRINT,
+  GTK_PRINT_OPERATION_ACTION_PREVIEW,
+  GTK_PRINT_OPERATION_ACTION_EXPORT,
+} GtkPrintOperationAction;
+
+
 struct _GtkPrintOperation
 {
   GObject parent_instance;
@@ -67,6 +83,8 @@ struct _GtkPrintOperationClass
 {
   GObjectClass parent_class;
   
+  void     (*done)               (GtkPrintOperation *operation,
+				  GtkPrintOperationResult result);
   void     (*begin_print)        (GtkPrintOperation *operation, 
 				  GtkPrintContext   *context);
   gboolean (*paginate)           (GtkPrintOperation *operation, 
@@ -102,13 +120,6 @@ struct _GtkPrintOperationClass
   void (*_gtk_reserved7) (void);
 };
 
-typedef enum {
-  GTK_PRINT_OPERATION_RESULT_ERROR,
-  GTK_PRINT_OPERATION_RESULT_APPLY,
-  GTK_PRINT_OPERATION_RESULT_CANCEL,
-  GTK_PRINT_OPERATION_RESULT_PREVIEW
-} GtkPrintOperationResult;
-
 #define GTK_PRINT_ERROR gtk_print_error_quark ()
 
 typedef enum
@@ -138,23 +149,21 @@ void                    gtk_print_operation_set_use_full_page      (GtkPrintOper
 								    gboolean            full_page);
 void                    gtk_print_operation_set_unit               (GtkPrintOperation  *op,
 								    GtkUnit             unit);
-void                    gtk_print_operation_set_show_dialog        (GtkPrintOperation  *op,
-								    gboolean            show_dialog);
-void                    gtk_print_operation_set_show_preview       (GtkPrintOperation  *op,
-								    gboolean            show_preview);
 void                    gtk_print_operation_set_pdf_target         (GtkPrintOperation  *op,
 								    const gchar        *filename);
 void                    gtk_print_operation_set_track_print_status (GtkPrintOperation  *op,
 								    gboolean            track_status);
 void                    gtk_print_operation_set_show_progress      (GtkPrintOperation  *op,
 								    gboolean            show_progress);
+void                    gtk_print_operation_set_allow_async        (GtkPrintOperation  *op,
+								    gboolean            allow_async);
 void                    gtk_print_operation_set_custom_tab_label   (GtkPrintOperation  *op,
 								    const gchar        *label);
 GtkPrintOperationResult gtk_print_operation_run                    (GtkPrintOperation  *op,
+								    GtkPrintOperationAction action,
 								    GtkWindow          *parent,
 								    GError            **error);
-void                    gtk_print_operation_run_preview            (GtkPrintOperation  *op,
-                                                                    GtkWindow          *parent);
+GError *                gtk_print_operation_get_error              (GtkPrintOperation  *op);
 GtkPrintStatus          gtk_print_operation_get_status             (GtkPrintOperation  *op);
 G_CONST_RETURN gchar *  gtk_print_operation_get_status_string      (GtkPrintOperation  *op);
 gboolean                gtk_print_operation_is_finished            (GtkPrintOperation  *op);