Some more printing docs

diff --git a/ChangeLog b/ChangeLog
index 1cd0fda482be0cf9d513efdae4ba04bb49ca19ef..917fa8fffc1229f1e266ab9ef42c20fd1c21a621 100644 (file)
--- a/ChangeLog
+++ b/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)
 

diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index 1cd0fda482be0cf9d513efdae4ba04bb49ca19ef..917fa8fffc1229f1e266ab9ef42c20fd1c21a621 100644 (file)
--- a/ChangeLog.pre-2-10
+++ b/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)
 

diff --git a/docs/reference/gtk/tmpl/gtkprintoperation.sgml b/docs/reference/gtk/tmpl/gtkprintoperation.sgml
index e9772425f2a77b2c14cdc0ff302bdd2dfc67cfd1..3884eaeafa08957e0c05cf8df03ca8915f031b5e 100644 (file)
--- a/docs/reference/gtk/tmpl/gtkprintoperation.sgml
+++ b/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>

diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c
index 1b403d0d92bf0a51976ef4773f31a72148247272..c12d3aa46a5681b3408b50eb8e2dfe19b7cfc406 100644 (file)
--- a/gtk/gtkprintoperation.c
+++ b/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
-   * viewer will be used.
+   * The default handler for this signal uses an external viewer 
+   * 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
    * 

diff --git a/gtk/gtkprintoperationpreview.c b/gtk/gtkprintoperationpreview.c
index a3357cfaf62b2b2a13fbf84fc5a225855f1c8d30..1861d81ddf3c34c081da3d045c040365d24bf618 100644 (file)
--- a/gtk/gtkprintoperationpreview.c
+++ b/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