Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkprintoperation.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkPrintOperation
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 High-level Printing API
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GtkPrintOperation is the high-level, portable printing API. It looks
  10 a bit different than other GTK+ dialogs such as the #GtkFileChooser,
  11 since some platforms don't expose enough infrastructure to implement
  12 a good print dialog. On such platforms, GtkPrintOperation uses the
  13 native print dialog. On platforms which do not provide a native
  14 print dialog, GTK+ uses its own, see #GtkPrintUnixDialog.
  15 </para>
  16
  17 <para>
  18 The typical way to use the high-level printing API is to create a
  19 #GtkPrintOperation object with gtk_print_operation_new() when the user
  20 selects to print. Then you set some properties on it, e.g. the page size,
  21 any #GtkPrintSettings from previous print operations, the number of pages,
  22 the current page, etc.
  23 </para>
  24 <para>
  25 Then you start the print operation by calling gtk_print_operation_run().
  26 It will then show a dialog, let the user select a printer and options.
  27 When the user finished the dialog various signals will be emitted on the
  28 #GtkPrintOperation, the main one being ::draw-page, which you are supposed
  29 to catch and render the page on the provided #GtkPrintContext using Cairo.
  30 </para>
  31
  32 <example>
  33 <title>The high-level printing API</title>
  34 <programlisting>
  35 static GtkPrintSettings *settings = NULL;
  36
  37 static void
  38 do_print (void)
  39 {
  40   GtkPrintOperation *print;
  41   GtkPrintOperationResult res;
  42
  43   print = gtk_print_operation_new (<!-- -->);
  44
  45   if (settings != NULL)
  46     gtk_print_operation_set_print_settings (print, settings);
  47
  48   g_signal_connect (print, "begin_print", G_CALLBACK (begin_print), NULL);
  49   g_signal_connect (print, "draw_page", G_CALLBACK (draw_page), NULL);
  50
  51   res = gtk_print_operation_run (print, GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG,
  52                                  GTK_WINDOW (main_window), NULL);
  53
  54   if (res == GTK_PRINT_OPERATION_RESULT_APPLY)
  55     {
  56       if (settings != NULL)
  57         g_object_unref (settings);
  58       settings = g_object_ref (gtk_print_operation_get_print_settings (print));
  59     }
  60
  61   g_object_unref (print);
  62 }
  63
  64 </programlisting>
  65 </example>
  66
  67 <para>
  68 By default GtkPrintOperation uses an external application to do
  69 print preview. To implement a custom print preview, an application
  70 must connect to the preview signal. The functions
  71 gtk_print_operation_print_preview_render_page(),
  72 gtk_print_operation_preview_end_preview() and
  73 gtk_print_operation_preview_is_selected() are useful
  74 when implementing a print preview.
  75 </para>
  76
  77 <para>
  78 Printing support was added in GTK+ 2.10.
  79 </para>
  80
  81 <!-- ##### SECTION See_Also ##### -->
  82 <para>
  83 #GtkPrintContext, #GtkPrintUnixDialog
  84 </para>
  85
  86 <!-- ##### SECTION Stability_Level ##### -->
  87
  88
  89 <!-- ##### STRUCT GtkPrintOperation ##### -->
  90 <para>
  91
  92 </para>
  93
  94
  95 <!-- ##### SIGNAL GtkPrintOperation::begin-print ##### -->
  96 <para>
  97
  98 </para>
  99
 100 @printoperation:
 101 @context:
 102
 103 <!-- ##### SIGNAL GtkPrintOperation::create-custom-widget ##### -->
 104 <para>
 105
 106 </para>
 107
 108 @printoperation:
 109 @Returns:
 110
 111 <!-- ##### SIGNAL GtkPrintOperation::custom-widget-apply ##### -->
 112 <para>
 113
 114 </para>
 115
 116 @printoperation:
 117 @widget:
 118
 119 <!-- ##### SIGNAL GtkPrintOperation::done ##### -->
 120 <para>
 121
 122 </para>
 123
 124 @printoperation: the object which received the signal.
 125 @arg1:
 126
 127 <!-- ##### SIGNAL GtkPrintOperation::draw-page ##### -->
 128 <para>
 129
 130 </para>
 131
 132 @printoperation: the object which received the signal.
 133 @arg1:
 134 @arg2:
 135
 136 <!-- ##### SIGNAL GtkPrintOperation::end-print ##### -->
 137 <para>
 138
 139 </para>
 140
 141 @printoperation: the object which received the signal.
 142 @arg1:
 143
 144 <!-- ##### SIGNAL GtkPrintOperation::paginate ##### -->
 145 <para>
 146
 147 </para>
 148
 149 @printoperation: the object which received the signal.
 150 @arg1:
 151 @Returns:
 152
 153 <!-- ##### SIGNAL GtkPrintOperation::preview ##### -->
 154 <para>
 155
 156 </para>
 157
 158 @printoperation: the object which received the signal.
 159 @arg1:
 160 @arg2:
 161 @arg3:
 162 @Returns:
 163
 164 <!-- ##### SIGNAL GtkPrintOperation::request-page-setup ##### -->
 165 <para>
 166
 167 </para>
 168
 169 @printoperation: the object which received the signal.
 170 @arg1:
 171 @arg2:
 172 @arg3:
 173
 174 <!-- ##### SIGNAL GtkPrintOperation::status-changed ##### -->
 175 <para>
 176
 177 </para>
 178
 179 @printoperation: the object which received the signal.
 180
 181 <!-- ##### ARG GtkPrintOperation:allow-async ##### -->
 182 <para>
 183
 184 </para>
 185
 186 <!-- ##### ARG GtkPrintOperation:current-page ##### -->
 187 <para>
 188
 189 </para>
 190
 191 <!-- ##### ARG GtkPrintOperation:custom-tab-label ##### -->
 192 <para>
 193
 194 </para>
 195
 196 <!-- ##### ARG GtkPrintOperation:default-page-setup ##### -->
 197 <para>
 198
 199 </para>
 200
 201 <!-- ##### ARG GtkPrintOperation:export-filename ##### -->
 202 <para>
 203
 204 </para>
 205
 206 <!-- ##### ARG GtkPrintOperation:job-name ##### -->
 207 <para>
 208
 209 </para>
 210
 211 <!-- ##### ARG GtkPrintOperation:n-pages ##### -->
 212 <para>
 213
 214 </para>
 215
 216 <!-- ##### ARG GtkPrintOperation:print-settings ##### -->
 217 <para>
 218
 219 </para>
 220
 221 <!-- ##### ARG GtkPrintOperation:show-progress ##### -->
 222 <para>
 223
 224 </para>
 225
 226 <!-- ##### ARG GtkPrintOperation:status ##### -->
 227 <para>
 228
 229 </para>
 230
 231 <!-- ##### ARG GtkPrintOperation:status-string ##### -->
 232 <para>
 233
 234 </para>
 235
 236 <!-- ##### ARG GtkPrintOperation:track-print-status ##### -->
 237 <para>
 238
 239 </para>
 240
 241 <!-- ##### ARG GtkPrintOperation:unit ##### -->
 242 <para>
 243
 244 </para>
 245
 246 <!-- ##### ARG GtkPrintOperation:use-full-page ##### -->
 247 <para>
 248
 249 </para>
 250
 251 <!-- ##### ENUM GtkPrintStatus ##### -->
 252 <para>
 253 The status gives a rough indication of the completion
 254 of a running print operation.
 255 </para>
 256
 257 @GTK_PRINT_STATUS_INITIAL: The printing has not started yet; this
 258   status is set initially, and while the print dialog is shown.
 259 @GTK_PRINT_STATUS_PREPARING: This status is set while the begin-print
 260   signal is emitted and during pagination.
 261 @GTK_PRINT_STATUS_GENERATING_DATA: This status is set while the
 262   pages are being rendered.
 263 @GTK_PRINT_STATUS_SENDING_DATA: The print job is being sent off to the
 264   printer.
 265 @GTK_PRINT_STATUS_PENDING: The print job has been sent to the printer,
 266   but is not printed for some reason, e.g. the printer may be stopped.
 267 @GTK_PRINT_STATUS_PENDING_ISSUE: Some problem has occurred during
 268   printing, e.g. a paper jam.
 269 @GTK_PRINT_STATUS_PRINTING: The printer is processing the print job.
 270 @GTK_PRINT_STATUS_FINISHED: The printing has been completed successfully.
 271 @GTK_PRINT_STATUS_FINISHED_ABORTED: The printing has been aborted.
 272
 273 <!-- ##### ENUM GtkPrintOperationAction ##### -->
 274 <para>
 275 The @action parameter to gtk_print_operation_run()
 276 determines what action the print operation should perform.
 277 </para>
 278
 279 @GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG: Show the print dialog.
 280 @GTK_PRINT_OPERATION_ACTION_PRINT: Start to print without showing
 281    the print dialog, based on the current print settings.
 282 @GTK_PRINT_OPERATION_ACTION_PREVIEW: Show the print preview.
 283 @GTK_PRINT_OPERATION_ACTION_EXPORT: Export to a file. This requires
 284   the export-filename property to be set.
 285
 286 <!-- ##### ENUM GtkPrintOperationResult ##### -->
 287 <para>
 288 A value of this type is returned by gtk_print_operation_run().
 289 </para>
 290
 291 @GTK_PRINT_OPERATION_RESULT_ERROR: An error has occured.
 292 @GTK_PRINT_OPERATION_RESULT_APPLY: The print settings should be stored.
 293 @GTK_PRINT_OPERATION_RESULT_CANCEL: The print operation has been canceled,
 294   the print settings should not be stored.
 295 @GTK_PRINT_OPERATION_RESULT_IN_PROGRESS: The print operation is complete
 296   yet. This value will only be returned when running asynchronously.
 297
 298 <!-- ##### ENUM GtkPrintError ##### -->
 299 <para>
 300
 301 </para>
 302
 303 @GTK_PRINT_ERROR_GENERAL:
 304 @GTK_PRINT_ERROR_INTERNAL_ERROR:
 305 @GTK_PRINT_ERROR_NOMEM:
 306 @GTK_PRINT_ERROR_INVALID_FILE:
 307
 308 <!-- ##### MACRO GTK_PRINT_ERROR ##### -->
 309 <para>
 310 The #GQuark used for #GtkPrintError errors.
 311 </para>
 312
 313
 314
 315 <!-- ##### FUNCTION gtk_print_operation_new ##### -->
 316 <para>
 317
 318 </para>
 319
 320 @Returns:
 321
 322
 323 <!-- ##### FUNCTION gtk_print_operation_set_allow_async ##### -->
 324 <para>
 325
 326 </para>
 327
 328 @op:
 329 @allow_async:
 330
 331
 332 <!-- ##### FUNCTION gtk_print_operation_get_error ##### -->
 333 <para>
 334
 335 </para>
 336
 337 @op:
 338 @error:
 339
 340
 341 <!-- ##### FUNCTION gtk_print_operation_set_default_page_setup ##### -->
 342 <para>
 343
 344 </para>
 345
 346 @op:
 347 @default_page_setup:
 348
 349
 350 <!-- ##### FUNCTION gtk_print_operation_get_default_page_setup ##### -->
 351 <para>
 352
 353 </para>
 354
 355 @op:
 356 @Returns:
 357
 358
 359 <!-- ##### FUNCTION gtk_print_operation_set_print_settings ##### -->
 360 <para>
 361
 362 </para>
 363
 364 @op:
 365 @print_settings:
 366
 367
 368 <!-- ##### FUNCTION gtk_print_operation_get_print_settings ##### -->
 369 <para>
 370
 371 </para>
 372
 373 @op:
 374 @Returns:
 375
 376
 377 <!-- ##### FUNCTION gtk_print_operation_set_job_name ##### -->
 378 <para>
 379
 380 </para>
 381
 382 @op:
 383 @job_name:
 384
 385
 386 <!-- ##### FUNCTION gtk_print_operation_set_n_pages ##### -->
 387 <para>
 388
 389 </para>
 390
 391 @op:
 392 @n_pages:
 393
 394
 395 <!-- ##### FUNCTION gtk_print_operation_set_current_page ##### -->
 396 <para>
 397
 398 </para>
 399
 400 @op:
 401 @current_page:
 402
 403
 404 <!-- ##### FUNCTION gtk_print_operation_set_use_full_page ##### -->
 405 <para>
 406
 407 </para>
 408
 409 @op:
 410 @full_page:
 411
 412
 413 <!-- ##### FUNCTION gtk_print_operation_set_unit ##### -->
 414 <para>
 415
 416 </para>
 417
 418 @op:
 419 @unit:
 420
 421
 422 <!-- ##### FUNCTION gtk_print_operation_set_export_filename ##### -->
 423 <para>
 424
 425 </para>
 426
 427 @op:
 428 @filename:
 429
 430
 431 <!-- ##### FUNCTION gtk_print_operation_set_show_progress ##### -->
 432 <para>
 433
 434 </para>
 435
 436 @op:
 437 @show_progress:
 438
 439
 440 <!-- ##### FUNCTION gtk_print_operation_set_track_print_status ##### -->
 441 <para>
 442
 443 </para>
 444
 445 @op:
 446 @track_status:
 447
 448
 449 <!-- ##### FUNCTION gtk_print_operation_set_custom_tab_label ##### -->
 450 <para>
 451
 452 </para>
 453
 454 @op:
 455 @label:
 456
 457
 458 <!-- ##### FUNCTION gtk_print_operation_run ##### -->
 459 <para>
 460
 461 </para>
 462
 463 @op:
 464 @action:
 465 @parent:
 466 @error:
 467 @Returns:
 468
 469
 470 <!-- ##### FUNCTION gtk_print_operation_cancel ##### -->
 471 <para>
 472
 473 </para>
 474
 475 @op:
 476
 477
 478 <!-- ##### FUNCTION gtk_print_operation_get_status ##### -->
 479 <para>
 480
 481 </para>
 482
 483 @op:
 484 @Returns:
 485
 486
 487 <!-- ##### FUNCTION gtk_print_operation_get_status_string ##### -->
 488 <para>
 489
 490 </para>
 491
 492 @op:
 493 @Returns:
 494
 495
 496 <!-- ##### FUNCTION gtk_print_operation_is_finished ##### -->
 497 <para>
 498
 499 </para>
 500
 501 @op:
 502 @Returns:
 503
 504
 505 <!-- ##### FUNCTION gtk_print_run_page_setup_dialog ##### -->
 506 <para>
 507
 508 </para>
 509
 510 @parent:
 511 @page_setup:
 512 @settings:
 513 @Returns:
 514
 515
 516 <!-- ##### USER_FUNCTION GtkPageSetupDoneFunc ##### -->
 517 <para>
 518 The type of function that is passed to gtk_print_run_page_setup_dialog_async().
 519 This function will be called when the page setup dialog is dismissed, and
 520 also serves as destroy notify for @data.
 521 </para>
 522
 523 @page_setup: the #GtkPageSetup that has been
 524 @data: user data that has been passed to
 525        gtk_print_run_page_setup_dialog_async().
 526
 527
 528 <!-- ##### FUNCTION gtk_print_run_page_setup_dialog_async ##### -->
 529 <para>
 530
 531 </para>
 532
 533 @parent:
 534 @page_setup:
 535 @settings:
 536 @done_cb:
 537 @data:
 538
 539
 540 <!-- ##### STRUCT GtkPrintOperationPreview ##### -->
 541 <para>
 542
 543 </para>
 544
 545
 546 <!-- ##### FUNCTION gtk_print_operation_preview_end_preview ##### -->
 547 <para>
 548
 549 </para>
 550
 551 @preview:
 552
 553
 554 <!-- ##### FUNCTION gtk_print_operation_preview_is_selected ##### -->
 555 <para>
 556
 557 </para>
 558
 559 @preview:
 560 @page_nr:
 561 @Returns:
 562
 563
 564 <!-- ##### FUNCTION gtk_print_operation_preview_render_page ##### -->
 565 <para>
 566
 567 </para>
 568
 569 @preview:
 570 @page_nr:
 571
 572