AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2025-01-14 14:20:21 +00:00
Code Issues Projects Releases Wiki Activity

Move GtkPrintOperation docs inline

Browse Source
This commit is contained in:
Matthias Clasen 2011-01-30 02:34:59 -05:00
parent 701075b2c8
commit 837c504a11
4 changed files with 132 additions and 702 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/reference/gtk/tmpl/.gitignore vendored
View File

@ -49,6 +49,7 @@ gtkpaned.sgml
gtkpapersize.sgml
gtkprinter.sgml
gtkprintjob.sgml
gtkprintoperation.sgml
gtkprogressbar.sgml
gtkradioaction.sgml
gtkradiobutton.sgml

701
docs/reference/gtk/tmpl/gtkprintoperation.sgml
View File

@ -1,701 +0,0 @@
<!-- ##### SECTION Title ##### -->
GtkPrintOperation
<!-- ##### SECTION Short_Description ##### -->
High-level Printing API
<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<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>
<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>
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkPrintContext, #GtkPrintUnixDialog
</para>
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### SECTION Image ##### -->
<!-- ##### STRUCT GtkPrintOperation ##### -->
<para>
</para>
<!-- ##### SIGNAL GtkPrintOperation::begin-print ##### -->
<para>
</para>
@printoperation:
@context:
<!-- ##### SIGNAL GtkPrintOperation::create-custom-widget ##### -->
<para>
</para>
@printoperation:
@Returns:
<!-- ##### SIGNAL GtkPrintOperation::custom-widget-apply ##### -->
<para>
</para>
@printoperation:
@widget:
<!-- ##### SIGNAL GtkPrintOperation::done ##### -->
<para>
</para>
@printoperation: the object which received the signal.
@arg1:
<!-- ##### SIGNAL GtkPrintOperation::draw-page ##### -->
<para>
</para>
@printoperation: the object which received the signal.
@arg1:
@arg2:
<!-- ##### SIGNAL GtkPrintOperation::end-print ##### -->
<para>
</para>
@printoperation: the object which received the signal.
@arg1:
<!-- ##### SIGNAL GtkPrintOperation::paginate ##### -->
<para>
</para>
@printoperation: the object which received the signal.
@arg1:
@Returns:
<!-- ##### SIGNAL GtkPrintOperation::preview ##### -->
<para>
</para>
@printoperation: the object which received the signal.
@arg1:
@arg2:
@arg3:
@Returns:
<!-- ##### SIGNAL GtkPrintOperation::request-page-setup ##### -->
<para>
</para>
@printoperation: the object which received the signal.
@arg1:
@arg2:
@arg3:
<!-- ##### SIGNAL GtkPrintOperation::status-changed ##### -->
<para>
</para>
@printoperation: the object which received the signal.
<!-- ##### SIGNAL GtkPrintOperation::update-custom-widget ##### -->
<para>
</para>
@printoperation: the object which received the signal.
@widget:
@arg1:
@arg2:
<!-- ##### ARG GtkPrintOperation:allow-async ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:current-page ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:custom-tab-label ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:default-page-setup ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:embed-page-setup ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:export-filename ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:has-selection ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:job-name ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:n-pages ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:n-pages-to-print ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:print-settings ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:show-progress ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:status ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:status-string ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:support-selection ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:track-print-status ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:unit ##### -->
<para>
</para>
<!-- ##### ARG GtkPrintOperation:use-full-page ##### -->
<para>
</para>
<!-- ##### ENUM GtkPrintStatus ##### -->
<para>
The status gives a rough indication of the completion
of a running print operation.
</para>
@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.
<!-- ##### ENUM GtkPrintOperationAction ##### -->
<para>
The @action parameter to gtk_print_operation_run()
determines what action the print operation should perform.
</para>
@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.
<!-- ##### ENUM GtkPrintOperationResult ##### -->
<para>
A value of this type is returned by gtk_print_operation_run().
</para>
@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.
<!-- ##### ENUM GtkPrintError ##### -->
<para>
Error codes that identify various errors that can occur while
using the GTK+ printing support.
</para>
@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.
<!-- ##### MACRO GTK_PRINT_ERROR ##### -->
<para>
The #GQuark used for #GtkPrintError errors.
</para>
<!-- ##### FUNCTION gtk_print_operation_new ##### -->
<para>
</para>
@void:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_set_allow_async ##### -->
<para>
</para>
@op:
@allow_async:
<!-- ##### FUNCTION gtk_print_operation_get_error ##### -->
<para>
</para>
@op:
@error:
<!-- ##### FUNCTION gtk_print_operation_set_default_page_setup ##### -->
<para>
</para>
@op:
@default_page_setup:
<!-- ##### FUNCTION gtk_print_operation_get_default_page_setup ##### -->
<para>
</para>
@op:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_set_print_settings ##### -->
<para>
</para>
@op:
@print_settings:
<!-- ##### FUNCTION gtk_print_operation_get_print_settings ##### -->
<para>
</para>
@op:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_set_job_name ##### -->
<para>
</para>
@op:
@job_name:
<!-- ##### FUNCTION gtk_print_operation_set_n_pages ##### -->
<para>
</para>
@op:
@n_pages:
<!-- ##### FUNCTION gtk_print_operation_get_n_pages_to_print ##### -->
<para>
</para>
@op:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_set_current_page ##### -->
<para>
</para>
@op:
@current_page:
<!-- ##### FUNCTION gtk_print_operation_set_use_full_page ##### -->
<para>
</para>
@op:
@full_page:
<!-- ##### FUNCTION gtk_print_operation_set_unit ##### -->
<para>
</para>
@op:
@unit:
<!-- ##### FUNCTION gtk_print_operation_set_export_filename ##### -->
<para>
</para>
@op:
@filename:
<!-- ##### FUNCTION gtk_print_operation_set_show_progress ##### -->
<para>
</para>
@op:
@show_progress:
<!-- ##### FUNCTION gtk_print_operation_set_track_print_status ##### -->
<para>
</para>
@op:
@track_status:
<!-- ##### FUNCTION gtk_print_operation_set_custom_tab_label ##### -->
<para>
</para>
@op:
@label:
<!-- ##### FUNCTION gtk_print_operation_run ##### -->
<para>
</para>
@op:
@action:
@parent:
@error:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_cancel ##### -->
<para>
</para>
@op:
<!-- ##### FUNCTION gtk_print_operation_draw_page_finish ##### -->
<para>
</para>
@op:
<!-- ##### FUNCTION gtk_print_operation_set_defer_drawing ##### -->
<para>
</para>
@op:
<!-- ##### FUNCTION gtk_print_operation_get_status ##### -->
<para>
</para>
@op:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_get_status_string ##### -->
<para>
</para>
@op:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_is_finished ##### -->
<para>
</para>
@op:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_set_support_selection ##### -->
<para>
</para>
@op:
@support_selection:
<!-- ##### FUNCTION gtk_print_operation_get_support_selection ##### -->
<para>
</para>
@op:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_set_has_selection ##### -->
<para>
</para>
@op:
@has_selection:
<!-- ##### FUNCTION gtk_print_operation_get_has_selection ##### -->
<para>
</para>
@op:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_set_embed_page_setup ##### -->
<para>
</para>
@op:
@embed:
<!-- ##### FUNCTION gtk_print_operation_get_embed_page_setup ##### -->
<para>
</para>
@op:
@Returns:
<!-- ##### FUNCTION gtk_print_run_page_setup_dialog ##### -->
<para>
</para>
@parent:
@page_setup:
@settings:
@Returns:
<!-- ##### USER_FUNCTION GtkPageSetupDoneFunc ##### -->
<para>
</para>
@page_setup:
@data:
<!-- ##### FUNCTION gtk_print_run_page_setup_dialog_async ##### -->
<para>
</para>
@parent:
@page_setup:
@settings:
@done_cb:
@data:
<!-- ##### STRUCT GtkPrintOperationPreview ##### -->
<para>
</para>
<!-- ##### SIGNAL GtkPrintOperationPreview::got-page-size ##### -->
<para>
</para>
@printoperationpreview: the object which received the signal.
@arg1:
@arg2:
<!-- ##### SIGNAL GtkPrintOperationPreview::ready ##### -->
<para>
</para>
@printoperationpreview: the object which received the signal.
@arg1:
<!-- ##### FUNCTION gtk_print_operation_preview_end_preview ##### -->
<para>
</para>
@preview:
<!-- ##### FUNCTION gtk_print_operation_preview_is_selected ##### -->
<para>
</para>
@preview:
@page_nr:
@Returns:
<!-- ##### FUNCTION gtk_print_operation_preview_render_page ##### -->
<para>
</para>
@preview:
@page_nr:

72
gtk/gtkprintoperation.c
View File

@ -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,

60
gtk/gtkprintoperation.h
View File

@ -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,