Some more printing docs

ChangeLog

@@ -1,5 +1,9 @@
 2006-08-15  Matthias Clasen  <mclasen@redhat.com>
 
+	* gtk/gtkprintoperationpreview.c: 
+	* gtk/gtkprintoperation.c (gtk_print_operation_class_init): Add
+	more docs.
+
 	* gtk/gtkaboutdialog.c (gtk_about_dialog_init): Set CAN_DEFAULT
 	on all buttons.  (#168737, fix proposed by Benjamin Berg)
 

ChangeLog.pre-2-10

@@ -1,5 +1,9 @@
 2006-08-15  Matthias Clasen  <mclasen@redhat.com>
 
+	* gtk/gtkprintoperationpreview.c: 
+	* gtk/gtkprintoperation.c (gtk_print_operation_class_init): Add
+	more docs.
+
 	* gtk/gtkaboutdialog.c (gtk_about_dialog_init): Set CAN_DEFAULT
 	on all buttons.  (#168737, fix proposed by Benjamin Berg)
 

docs/reference/gtk/tmpl/gtkprintoperation.sgml

@@ -64,6 +64,16 @@ do_print (void)
 </programlisting>
 </example>
 
+<para>
+By default GtkPrintOperation uses an external application to do
+print preview. To implement a custom print preview, an application 
+must connect to the preview signal. The functions 
+gtk_print_operation_print_preview_render_page(), 
+gtk_print_operation_preview_end_preview() and 
+gtk_print_operation_preview_is_selected() are useful 
+when implementing a print preview.
+</para>
+
 <para>
 Printing support was added in GTK+ 2.10.
 </para>

gtk/gtkprintoperation.c

@@ -807,10 +807,21 @@ gtk_print_operation_class_init (GtkPrintOperationClass *class)
    * @parent: the #GtkWindow to use as window parent, or %NULL
    *
    * Gets emitted when a preview is requested from the native dialog.
-   * If you handle this you must set the cairo context on the printing context.
    *
-   * If you don't override this a default implementation using an external
+   * The default handler for this signal uses an external viewer 
-   * viewer will be used.
+   * 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 gtk_print_context_set_cairo_context().
+   * 
+   * The custom preview implementation can use 
+   * gtk_print_operation_preview_is_selected() and 
+   * gtk_print_operation_preview_render_page() to find pages which
+   * are selected for print and render them. The preview must be
+   * finished by calling gtk_print_operation_preview_end_preview()
+   * (typically in response to the user clicking a close button).
    *
    * Returns: %TRUE if the listener wants to take over control of the preview
    * 

gtk/gtkprintoperationpreview.c

@@ -93,7 +93,12 @@ gtk_print_operation_preview_base_init (gpointer g_iface)
  * @preview: a #GtkPrintOperationPreview
  * @page_nr: the page to render
  *
- * Renders a page to the preview.
+ * Renders a page to the preview, using the print context that
+ * was passed to the GtkPrintOperation::preview handler together
+ * with @preview.
+ *
+ * Note that this function requires a suitable cairo context to 
+ * be associated with the print context. 
  *
  * Since: 2.10 
  */
@@ -113,6 +118,8 @@ gtk_print_operation_preview_render_page (GtkPrintOperationPreview *preview,
  *
  * Ends a preview. 
  *
+ * This function must be called to finish a custom print preview.
+ *
  * Since: 2.10
  */
 void