diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore index e7c14a5afa..9dfd716329 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/docs/reference/gtk/tmpl/gtkprintoperation.sgml b/docs/reference/gtk/tmpl/gtkprintoperation.sgml deleted file mode 100644 index 0b0446026e..0000000000 --- a/docs/reference/gtk/tmpl/gtkprintoperation.sgml +++ /dev/null @@ -1,701 +0,0 @@ - -GtkPrintOperation - - -High-level Printing API - - - -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 ::draw-page, which you are supposed -to catch and render the page on the provided #GtkPrintContext using Cairo. - - - -The high-level printing API - -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); -} - - - - - -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. - - - -Printing support was added in GTK+ 2.10. - - - - -#GtkPrintContext, #GtkPrintUnixDialog - - - - - - - - - - - - - - - - - - - -@printoperation: -@context: - - - - - - -@printoperation: -@Returns: - - - - - - -@printoperation: -@widget: - - - - - - -@printoperation: the object which received the signal. -@arg1: - - - - - - -@printoperation: the object which received the signal. -@arg1: -@arg2: - - - - - - -@printoperation: the object which received the signal. -@arg1: - - - - - - -@printoperation: the object which received the signal. -@arg1: -@Returns: - - - - - - -@printoperation: the object which received the signal. -@arg1: -@arg2: -@arg3: -@Returns: - - - - - - -@printoperation: the object which received the signal. -@arg1: -@arg2: -@arg3: - - - - - - -@printoperation: the object which received the signal. - - - - - - -@printoperation: the object which received the signal. -@widget: -@arg1: -@arg2: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -The status gives a rough indication of the completion -of a running print operation. - - -@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 @action parameter to gtk_print_operation_run() -determines what action the print operation should perform. - - -@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. - - - -A value of this type is returned by gtk_print_operation_run(). - - -@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. - - - -Error codes that identify various errors that can occur while -using the GTK+ printing support. - - -@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. - - - -The #GQuark used for #GtkPrintError errors. - - - - - - - - - -@void: -@Returns: - - - - - - - -@op: -@allow_async: - - - - - - - -@op: -@error: - - - - - - - -@op: -@default_page_setup: - - - - - - - -@op: -@Returns: - - - - - - - -@op: -@print_settings: - - - - - - - -@op: -@Returns: - - - - - - - -@op: -@job_name: - - - - - - - -@op: -@n_pages: - - - - - - - -@op: -@Returns: - - - - - - - -@op: -@current_page: - - - - - - - -@op: -@full_page: - - - - - - - -@op: -@unit: - - - - - - - -@op: -@filename: - - - - - - - -@op: -@show_progress: - - - - - - - -@op: -@track_status: - - - - - - - -@op: -@label: - - - - - - - -@op: -@action: -@parent: -@error: -@Returns: - - - - - - - -@op: - - - - - - - -@op: - - - - - - - -@op: - - - - - - - -@op: -@Returns: - - - - - - - -@op: -@Returns: - - - - - - - -@op: -@Returns: - - - - - - - -@op: -@support_selection: - - - - - - - -@op: -@Returns: - - - - - - - -@op: -@has_selection: - - - - - - - -@op: -@Returns: - - - - - - - -@op: -@embed: - - - - - - - -@op: -@Returns: - - - - - - - -@parent: -@page_setup: -@settings: -@Returns: - - - - - - - -@page_setup: -@data: - - - - - - - -@parent: -@page_setup: -@settings: -@done_cb: -@data: - - - - - - - - - - - - - -@printoperationpreview: the object which received the signal. -@arg1: -@arg2: - - - - - - -@printoperationpreview: the object which received the signal. -@arg1: - - - - - - -@preview: - - - - - - - -@preview: -@page_nr: -@Returns: - - - - - - - -@preview: -@page_nr: - - diff --git a/gtk/gtkprintoperation.c b/gtk/gtkprintoperation.c index 15eadf1c38..ff95003570 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. + * + * + * The high-level printing API + * + * 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); + * } + * + * + * + * 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 5c2b2167e8..01e385007f 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,