[gtk+] Move GtkPrintOperation docs inline

[Matthias Clasen <matthiasc src gnome org>]

commit 837c504a118eeab9c820ce629ee9a128d49f08a5
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun Jan 30 02:34:59 2011 -0500

    Move GtkPrintOperation docs inline

 docs/reference/gtk/tmpl/.gitignore             |    1 +
 docs/reference/gtk/tmpl/gtkprintoperation.sgml |  701 ------------------------
 gtk/gtkprintoperation.c                        |   72 +++-
 gtk/gtkprintoperation.h                        |   60 ++
 4 files changed, 132 insertions(+), 702 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index e7c14a5..9dfd716 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -49,6 +49,7 @@ gtkpaned.sgml
 gtkpapersize.sgml
 gtkprinter.sgml
 gtkprintjob.sgml
+gtkprintoperation.sgml
 gtkprogressbar.sgml
 gtkradioaction.sgml
 gtkradiobutton.sgml
diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c
index 15eadf1..ff95003 100644
--- a/gtk/gtkprintoperation.c
+++ b/gtk/gtkprintoperation.c
@@ -35,10 +35,80 @@
 #include "gtkmessagedialog.h"
 #include "gtktypebuiltins.h"
 
+/**
+ * SECTION:gtkprintoperation
+ * @Title: GtkPrintOperation
+ * @Short_description: High-level Printing API
+ * @See_also: #GtkPrintContext, #GtkPrintUnixDialog
+ *
+ * GtkPrintOperation is the high-level, portable printing API.
+ * It looks a bit different than other GTK+ dialogs such as the
+ * #GtkFileChooser, since some platforms don't expose enough
+ * infrastructure to implement a good print dialog. On such
+ * platforms, GtkPrintOperation uses the native print dialog.
+ * On platforms which do not provide a native print dialog, GTK+
+ * uses its own, see #GtkPrintUnixDialog.
+ *
+ * The typical way to use the high-level printing API is to create
+ * a GtkPrintOperation object with gtk_print_operation_new() when
+ * the user selects to print. Then you set some properties on it,
+ * e.g. the page size, any #GtkPrintSettings from previous print
+ * operations, the number of pages, the current page, etc.
+ *
+ * Then you start the print operation by calling gtk_print_operation_run().
+ * It will then show a dialog, let the user select a printer and
+ * options. When the user finished the dialog various signals will
+ * be emitted on the #GtkPrintOperation, the main one being
+ * #GtkPrintOperation::draw-page, which you are supposed to catch
+ * and render the page on the provided #GtkPrintContext using Cairo.
+ *
+ * <example>
+ * <title>The high-level printing API</title>
+ * <programlisting>
+ * static GtkPrintSettings *settings = NULL;
+ *
+ * static void
+ * do_print (void)
+ * {
+ *   GtkPrintOperation *print;
+ *   GtkPrintOperationResult res;
+ *
+ *   print = gtk_print_operation_new ();
+ *
+ *   if (settings != NULL)
+ *     gtk_print_operation_set_print_settings (print, settings);
+ *
+ *   g_signal_connect (print, "begin_print", G_CALLBACK (begin_print), NULL);
+ *   g_signal_connect (print, "draw_page", G_CALLBACK (draw_page), NULL);
+ *
+ *   res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
+ *                                  GTK_WINDOW (main_window), NULL);
+ *
+ *   if (res == GTK_PRINT_OPERATION_RESULT_APPLY)
+ *     {
+ *       if (settings != NULL)
+ *         g_object_unref (settings);
+ *       settings = g_object_ref (gtk_print_operation_get_print_settings (print));
+ *     }
+ *
+ *   g_object_unref (print);
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * 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.
+ */
+
 #define SHOW_PROGRESS_TIME 1200
 
 
-enum 
+enum
 {
   DONE,
   BEGIN_PRINT,
diff --git a/gtk/gtkprintoperation.h b/gtk/gtkprintoperation.h
index 5c2b216..01e3850 100644
--- a/gtk/gtkprintoperation.h
+++ b/gtk/gtkprintoperation.h
@@ -48,6 +48,27 @@ typedef struct _GtkPrintOperationClass   GtkPrintOperationClass;
 typedef struct _GtkPrintOperationPrivate GtkPrintOperationPrivate;
 typedef struct _GtkPrintOperation        GtkPrintOperation;
 
+/**
+ * GtkPrintStatus:
+ * @GTK_PRINT_STATUS_INITIAL: The printing has not started yet; this
+ *     status is set initially, and while the print dialog is shown.
+ * @GTK_PRINT_STATUS_PREPARING: This status is set while the begin-print
+ *     signal is emitted and during pagination.
+ * @GTK_PRINT_STATUS_GENERATING_DATA: This status is set while the
+ *     pages are being rendered.
+ * @GTK_PRINT_STATUS_SENDING_DATA: The print job is being sent off to the
+ *     printer.
+ * @GTK_PRINT_STATUS_PENDING: The print job has been sent to the printer,
+ *     but is not printed for some reason, e.g. the printer may be stopped.
+ * @GTK_PRINT_STATUS_PENDING_ISSUE: Some problem has occurred during
+ *     printing, e.g. a paper jam.
+ * @GTK_PRINT_STATUS_PRINTING: The printer is processing the print job.
+ * @GTK_PRINT_STATUS_FINISHED: The printing has been completed successfully.
+ * @GTK_PRINT_STATUS_FINISHED_ABORTED: The printing has been aborted.
+ *
+ * The status gives a rough indication of the completion of a running
+ * print operation.
+ */
 typedef enum {
   GTK_PRINT_STATUS_INITIAL,
   GTK_PRINT_STATUS_PREPARING,
@@ -60,6 +81,17 @@ typedef enum {
   GTK_PRINT_STATUS_FINISHED_ABORTED
 } GtkPrintStatus;
 
+/**
+ * GtkPrintOperationResult:
+ * @GTK_PRINT_OPERATION_RESULT_ERROR: An error has occured.
+ * @GTK_PRINT_OPERATION_RESULT_APPLY: The print settings should be stored.
+ * @GTK_PRINT_OPERATION_RESULT_CANCEL: The print operation has been canceled,
+ *     the print settings should not be stored.
+ * @GTK_PRINT_OPERATION_RESULT_IN_PROGRESS: The print operation is not complete
+ *     yet. This value will only be returned when running asynchronously.
+ *
+ * A value of this type is returned by gtk_print_operation_run().
+ */
 typedef enum {
   GTK_PRINT_OPERATION_RESULT_ERROR,
   GTK_PRINT_OPERATION_RESULT_APPLY,
@@ -67,6 +99,18 @@ typedef enum {
   GTK_PRINT_OPERATION_RESULT_IN_PROGRESS
 } GtkPrintOperationResult;
 
+/**
+ * GtkPrintOperationAction:
+ * @GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG: Show the print dialog.
+ * @GTK_PRINT_OPERATION_ACTION_PRINT: Start to print without showing
+ *     the print dialog, based on the current print settings.
+ * @GTK_PRINT_OPERATION_ACTION_PREVIEW: Show the print preview.
+ * @GTK_PRINT_OPERATION_ACTION_EXPORT: Export to a file. This requires
+ *     the export-filename property to be set.
+ *
+ * The @action parameter to gtk_print_operation_run()
+ * determines what action the print operation should perform.
+ */
 typedef enum {
   GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
   GTK_PRINT_OPERATION_ACTION_PRINT,
@@ -129,8 +173,24 @@ struct _GtkPrintOperationClass
   void (*_gtk_reserved8) (void);
 };
 
+/**
+ * GTK_PRINT_ERROR:
+ *
+ * The error domain for #GtkPrintError errors.
+ */
 #define GTK_PRINT_ERROR gtk_print_error_quark ()
 
+/**
+ * GtkPrintError:
+ * @GTK_PRINT_ERROR_GENERAL: An unspecified error occurred.
+ * @GTK_PRINT_ERROR_INTERNAL_ERROR: An internal error occurred.
+ * @GTK_PRINT_ERROR_NOMEM: A memory allocation failed.
+ * @GTK_PRINT_ERROR_INVALID_FILE: An error occurred while loading a page setup
+ *     or paper size from a key file.
+ *
+ * Error codes that identify various errors that can occur while
+ * using the GTK+ printing support.
+ */
 typedef enum
 {
   GTK_PRINT_ERROR_GENERAL,