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 <!-- ##### SIGNAL GtkPrintOperation::update-custom-widget ##### -->
 182 <para>
 183
 184 </para>
 185
 186 @printoperation: the object which received the signal.
 187 @widget:
 188 @arg1:
 189 @arg2:
 190
 191 <!-- ##### ARG GtkPrintOperation:allow-async ##### -->
 192 <para>
 193
 194 </para>
 195
 196 <!-- ##### ARG GtkPrintOperation:current-page ##### -->
 197 <para>
 198
 199 </para>
 200
 201 <!-- ##### ARG GtkPrintOperation:custom-tab-label ##### -->
 202 <para>
 203
 204 </para>
 205
 206 <!-- ##### ARG GtkPrintOperation:default-page-setup ##### -->
 207 <para>
 208
 209 </para>
 210
 211 <!-- ##### ARG GtkPrintOperation:embed-page-setup ##### -->
 212 <para>
 213
 214 </para>
 215
 216 <!-- ##### ARG GtkPrintOperation:export-filename ##### -->
 217 <para>
 218
 219 </para>
 220
 221 <!-- ##### ARG GtkPrintOperation:has-selection ##### -->
 222 <para>
 223
 224 </para>
 225
 226 <!-- ##### ARG GtkPrintOperation:job-name ##### -->
 227 <para>
 228
 229 </para>
 230
 231 <!-- ##### ARG GtkPrintOperation:n-pages ##### -->
 232 <para>
 233
 234 </para>
 235
 236 <!-- ##### ARG GtkPrintOperation:n-pages-to-print ##### -->
 237 <para>
 238
 239 </para>
 240
 241 <!-- ##### ARG GtkPrintOperation:print-settings ##### -->
 242 <para>
 243
 244 </para>
 245
 246 <!-- ##### ARG GtkPrintOperation:show-progress ##### -->
 247 <para>
 248
 249 </para>
 250
 251 <!-- ##### ARG GtkPrintOperation:status ##### -->
 252 <para>
 253
 254 </para>
 255
 256 <!-- ##### ARG GtkPrintOperation:status-string ##### -->
 257 <para>
 258
 259 </para>
 260
 261 <!-- ##### ARG GtkPrintOperation:support-selection ##### -->
 262 <para>
 263
 264 </para>
 265
 266 <!-- ##### ARG GtkPrintOperation:track-print-status ##### -->
 267 <para>
 268
 269 </para>
 270
 271 <!-- ##### ARG GtkPrintOperation:unit ##### -->
 272 <para>
 273
 274 </para>
 275
 276 <!-- ##### ARG GtkPrintOperation:use-full-page ##### -->
 277 <para>
 278
 279 </para>
 280
 281 <!-- ##### ENUM GtkPrintStatus ##### -->
 282 <para>
 283 The status gives a rough indication of the completion
 284 of a running print operation.
 285 </para>
 286
 287 @GTK_PRINT_STATUS_INITIAL: The printing has not started yet; this
 288   status is set initially, and while the print dialog is shown.
 289 @GTK_PRINT_STATUS_PREPARING: This status is set while the begin-print
 290   signal is emitted and during pagination.
 291 @GTK_PRINT_STATUS_GENERATING_DATA: This status is set while the
 292   pages are being rendered.
 293 @GTK_PRINT_STATUS_SENDING_DATA: The print job is being sent off to the
 294   printer.
 295 @GTK_PRINT_STATUS_PENDING: The print job has been sent to the printer,
 296   but is not printed for some reason, e.g. the printer may be stopped.
 297 @GTK_PRINT_STATUS_PENDING_ISSUE: Some problem has occurred during
 298   printing, e.g. a paper jam.
 299 @GTK_PRINT_STATUS_PRINTING: The printer is processing the print job.
 300 @GTK_PRINT_STATUS_FINISHED: The printing has been completed successfully.
 301 @GTK_PRINT_STATUS_FINISHED_ABORTED: The printing has been aborted.
 302
 303 <!-- ##### ENUM GtkPrintOperationAction ##### -->
 304 <para>
 305 The @action parameter to gtk_print_operation_run()
 306 determines what action the print operation should perform.
 307 </para>
 308
 309 @GTK_PRINT_OPERATION_ACTION_PRINT_DIALOG: Show the print dialog.
 310 @GTK_PRINT_OPERATION_ACTION_PRINT: Start to print without showing
 311    the print dialog, based on the current print settings.
 312 @GTK_PRINT_OPERATION_ACTION_PREVIEW: Show the print preview.
 313 @GTK_PRINT_OPERATION_ACTION_EXPORT: Export to a file. This requires
 314   the export-filename property to be set.
 315
 316 <!-- ##### ENUM GtkPrintOperationResult ##### -->
 317 <para>
 318 A value of this type is returned by gtk_print_operation_run().
 319 </para>
 320
 321 @GTK_PRINT_OPERATION_RESULT_ERROR: An error has occured.
 322 @GTK_PRINT_OPERATION_RESULT_APPLY: The print settings should be stored.
 323 @GTK_PRINT_OPERATION_RESULT_CANCEL: The print operation has been canceled,
 324   the print settings should not be stored.
 325 @GTK_PRINT_OPERATION_RESULT_IN_PROGRESS: The print operation is not complete
 326   yet. This value will only be returned when running asynchronously.
 327
 328 <!-- ##### ENUM GtkPrintError ##### -->
 329 <para>
 330 Error codes that identify various errors that can occur while
 331 using the GTK+ printing support.
 332 </para>
 333
 334 @GTK_PRINT_ERROR_GENERAL: An unspecified error occurred.
 335 @GTK_PRINT_ERROR_INTERNAL_ERROR: An internal error occurred.
 336 @GTK_PRINT_ERROR_NOMEM: A memory allocation failed.
 337 @GTK_PRINT_ERROR_INVALID_FILE: An error occurred while loading a page setup
 338     or paper size from a key file.
 339
 340 <!-- ##### MACRO GTK_PRINT_ERROR ##### -->
 341 <para>
 342 The #GQuark used for #GtkPrintError errors.
 343 </para>
 344
 345
 346
 347 <!-- ##### FUNCTION gtk_print_operation_new ##### -->
 348 <para>
 349
 350 </para>
 351
 352 @Returns:
 353
 354
 355 <!-- ##### FUNCTION gtk_print_operation_set_allow_async ##### -->
 356 <para>
 357
 358 </para>
 359
 360 @op:
 361 @allow_async:
 362
 363
 364 <!-- ##### FUNCTION gtk_print_operation_get_error ##### -->
 365 <para>
 366
 367 </para>
 368
 369 @op:
 370 @error:
 371
 372
 373 <!-- ##### FUNCTION gtk_print_operation_set_default_page_setup ##### -->
 374 <para>
 375
 376 </para>
 377
 378 @op:
 379 @default_page_setup:
 380
 381
 382 <!-- ##### FUNCTION gtk_print_operation_get_default_page_setup ##### -->
 383 <para>
 384
 385 </para>
 386
 387 @op:
 388 @Returns:
 389
 390
 391 <!-- ##### FUNCTION gtk_print_operation_set_print_settings ##### -->
 392 <para>
 393
 394 </para>
 395
 396 @op:
 397 @print_settings:
 398
 399
 400 <!-- ##### FUNCTION gtk_print_operation_get_print_settings ##### -->
 401 <para>
 402
 403 </para>
 404
 405 @op:
 406 @Returns:
 407
 408
 409 <!-- ##### FUNCTION gtk_print_operation_set_job_name ##### -->
 410 <para>
 411
 412 </para>
 413
 414 @op:
 415 @job_name:
 416
 417
 418 <!-- ##### FUNCTION gtk_print_operation_set_n_pages ##### -->
 419 <para>
 420
 421 </para>
 422
 423 @op:
 424 @n_pages:
 425
 426
 427 <!-- ##### FUNCTION gtk_print_operation_get_n_pages_to_print ##### -->
 428 <para>
 429
 430 </para>
 431
 432 @op:
 433 @Returns:
 434
 435
 436 <!-- ##### FUNCTION gtk_print_operation_set_current_page ##### -->
 437 <para>
 438
 439 </para>
 440
 441 @op:
 442 @current_page:
 443
 444
 445 <!-- ##### FUNCTION gtk_print_operation_set_use_full_page ##### -->
 446 <para>
 447
 448 </para>
 449
 450 @op:
 451 @full_page:
 452
 453
 454 <!-- ##### FUNCTION gtk_print_operation_set_unit ##### -->
 455 <para>
 456
 457 </para>
 458
 459 @op:
 460 @unit:
 461
 462
 463 <!-- ##### FUNCTION gtk_print_operation_set_export_filename ##### -->
 464 <para>
 465
 466 </para>
 467
 468 @op:
 469 @filename:
 470
 471
 472 <!-- ##### FUNCTION gtk_print_operation_set_show_progress ##### -->
 473 <para>
 474
 475 </para>
 476
 477 @op:
 478 @show_progress:
 479
 480
 481 <!-- ##### FUNCTION gtk_print_operation_set_track_print_status ##### -->
 482 <para>
 483
 484 </para>
 485
 486 @op:
 487 @track_status:
 488
 489
 490 <!-- ##### FUNCTION gtk_print_operation_set_custom_tab_label ##### -->
 491 <para>
 492
 493 </para>
 494
 495 @op:
 496 @label:
 497
 498
 499 <!-- ##### FUNCTION gtk_print_operation_run ##### -->
 500 <para>
 501
 502 </para>
 503
 504 @op:
 505 @action:
 506 @parent:
 507 @error:
 508 @Returns:
 509
 510
 511 <!-- ##### FUNCTION gtk_print_operation_cancel ##### -->
 512 <para>
 513
 514 </para>
 515
 516 @op:
 517
 518
 519 <!-- ##### FUNCTION gtk_print_operation_draw_page_finish ##### -->
 520 <para>
 521
 522 </para>
 523
 524 @op:
 525
 526
 527 <!-- ##### FUNCTION gtk_print_operation_set_defer_drawing ##### -->
 528 <para>
 529
 530 </para>
 531
 532 @op:
 533
 534
 535 <!-- ##### FUNCTION gtk_print_operation_get_status ##### -->
 536 <para>
 537
 538 </para>
 539
 540 @op:
 541 @Returns:
 542
 543
 544 <!-- ##### FUNCTION gtk_print_operation_get_status_string ##### -->
 545 <para>
 546
 547 </para>
 548
 549 @op:
 550 @Returns:
 551
 552
 553 <!-- ##### FUNCTION gtk_print_operation_is_finished ##### -->
 554 <para>
 555
 556 </para>
 557
 558 @op:
 559 @Returns:
 560
 561
 562 <!-- ##### FUNCTION gtk_print_operation_set_support_selection ##### -->
 563 <para>
 564
 565 </para>
 566
 567 @op:
 568 @support_selection:
 569
 570
 571 <!-- ##### FUNCTION gtk_print_operation_get_support_selection ##### -->
 572 <para>
 573
 574 </para>
 575
 576 @op:
 577 @Returns:
 578
 579
 580 <!-- ##### FUNCTION gtk_print_operation_set_has_selection ##### -->
 581 <para>
 582
 583 </para>
 584
 585 @op:
 586 @has_selection:
 587
 588
 589 <!-- ##### FUNCTION gtk_print_operation_get_has_selection ##### -->
 590 <para>
 591
 592 </para>
 593
 594 @op:
 595 @Returns:
 596
 597
 598 <!-- ##### FUNCTION gtk_print_operation_set_embed_page_setup ##### -->
 599 <para>
 600
 601 </para>
 602
 603 @op:
 604 @embed:
 605
 606
 607 <!-- ##### FUNCTION gtk_print_operation_get_embed_page_setup ##### -->
 608 <para>
 609
 610 </para>
 611
 612 @op:
 613 @Returns:
 614
 615
 616 <!-- ##### FUNCTION gtk_print_run_page_setup_dialog ##### -->
 617 <para>
 618
 619 </para>
 620
 621 @parent:
 622 @page_setup:
 623 @settings:
 624 @Returns:
 625
 626
 627 <!-- ##### USER_FUNCTION GtkPageSetupDoneFunc ##### -->
 628 <para>
 629 The type of function that is passed to gtk_print_run_page_setup_dialog_async().
 630 This function will be called when the page setup dialog is dismissed, and
 631 also serves as destroy notify for @data.
 632 </para>
 633
 634 @page_setup: the #GtkPageSetup that has been
 635 @data: user data that has been passed to
 636        gtk_print_run_page_setup_dialog_async().
 637
 638
 639 <!-- ##### FUNCTION gtk_print_run_page_setup_dialog_async ##### -->
 640 <para>
 641
 642 </para>
 643
 644 @parent:
 645 @page_setup:
 646 @settings:
 647 @done_cb:
 648 @data:
 649
 650
 651 <!-- ##### STRUCT GtkPrintOperationPreview ##### -->
 652 <para>
 653
 654 </para>
 655
 656
 657 <!-- ##### SIGNAL GtkPrintOperationPreview::got-page-size ##### -->
 658 <para>
 659
 660 </para>
 661
 662 @printoperationpreview: the object which received the signal.
 663 @arg1:
 664 @arg2:
 665
 666 <!-- ##### SIGNAL GtkPrintOperationPreview::ready ##### -->
 667 <para>
 668
 669 </para>
 670
 671 @printoperationpreview: the object which received the signal.
 672 @arg1:
 673
 674 <!-- ##### FUNCTION gtk_print_operation_preview_end_preview ##### -->
 675 <para>
 676
 677 </para>
 678
 679 @preview:
 680
 681
 682 <!-- ##### FUNCTION gtk_print_operation_preview_is_selected ##### -->
 683 <para>
 684
 685 </para>
 686
 687 @preview:
 688 @page_nr:
 689 @Returns:
 690
 691
 692 <!-- ##### FUNCTION gtk_print_operation_preview_render_page ##### -->
 693 <para>
 694
 695 </para>
 696
 697 @preview:
 698 @page_nr:
 699
 700