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_WINDOW (main_window), NULL);
  52
  53   if (res == GTK_PRINT_OPERATION_RESULT_APPLY)
  54     {
  55       if (settings != NULL)
  56         g_object_unref (settings);
  57       settings = g_object_ref (gtk_print_operation_get_print_settings (print));
  58     }
  59
  60   g_object_unref (print);
  61 }
  62
  63 </programlisting>
  64 </example>
  65
  66 <para>
  67 Printing support was added in GTK+ 2.10.
  68 </para>
  69
  70 <!-- ##### SECTION See_Also ##### -->
  71 <para>
  72 #GtkPrintContext, #GtkPrintUnixDialog
  73 </para>
  74
  75 <!-- ##### SECTION Stability_Level ##### -->
  76
  77
  78 <!-- ##### STRUCT GtkPrintOperation ##### -->
  79 <para>
  80
  81 </para>
  82
  83
  84 <!-- ##### SIGNAL GtkPrintOperation::begin-print ##### -->
  85 <para>
  86
  87 </para>
  88
  89 @printoperation: the object which received the signal.
  90 @arg1:
  91
  92 <!-- ##### SIGNAL GtkPrintOperation::draw-page ##### -->
  93 <para>
  94
  95 </para>
  96
  97 @printoperation: the object which received the signal.
  98 @arg1:
  99 @arg2:
 100
 101 <!-- ##### SIGNAL GtkPrintOperation::end-print ##### -->
 102 <para>
 103
 104 </para>
 105
 106 @printoperation: the object which received the signal.
 107 @arg1:
 108
 109 <!-- ##### SIGNAL GtkPrintOperation::request-page-setup ##### -->
 110 <para>
 111
 112 </para>
 113
 114 @printoperation: the object which received the signal.
 115 @arg1:
 116 @arg2:
 117 @arg3:
 118
 119 <!-- ##### SIGNAL GtkPrintOperation::status-changed ##### -->
 120 <para>
 121
 122 </para>
 123
 124 @printoperation: the object which received the signal.
 125
 126 <!-- ##### ARG GtkPrintOperation:current-page ##### -->
 127 <para>
 128
 129 </para>
 130
 131 <!-- ##### ARG GtkPrintOperation:default-page-setup ##### -->
 132 <para>
 133
 134 </para>
 135
 136 <!-- ##### ARG GtkPrintOperation:job-name ##### -->
 137 <para>
 138
 139 </para>
 140
 141 <!-- ##### ARG GtkPrintOperation:number-of-pages ##### -->
 142 <para>
 143
 144 </para>
 145
 146 <!-- ##### ARG GtkPrintOperation:pdf-target ##### -->
 147 <para>
 148
 149 </para>
 150
 151 <!-- ##### ARG GtkPrintOperation:print-settings ##### -->
 152 <para>
 153
 154 </para>
 155
 156 <!-- ##### ARG GtkPrintOperation:show-dialog ##### -->
 157 <para>
 158
 159 </para>
 160
 161 <!-- ##### ARG GtkPrintOperation:status ##### -->
 162 <para>
 163
 164 </para>
 165
 166 <!-- ##### ARG GtkPrintOperation:status-string ##### -->
 167 <para>
 168
 169 </para>
 170
 171 <!-- ##### ARG GtkPrintOperation:unit ##### -->
 172 <para>
 173
 174 </para>
 175
 176 <!-- ##### ARG GtkPrintOperation:use-full-page ##### -->
 177 <para>
 178
 179 </para>
 180
 181 <!-- ##### ENUM GtkPrintStatus ##### -->
 182 <para>
 183
 184 </para>
 185
 186 @GTK_PRINT_STATUS_INITIAL:
 187 @GTK_PRINT_STATUS_PREPARING:
 188 @GTK_PRINT_STATUS_GENERATING_DATA:
 189 @GTK_PRINT_STATUS_SENDING_DATA:
 190 @GTK_PRINT_STATUS_PENDING:
 191 @GTK_PRINT_STATUS_PENDING_ISSUE:
 192 @GTK_PRINT_STATUS_PRINTING:
 193 @GTK_PRINT_STATUS_FINISHED:
 194 @GTK_PRINT_STATUS_FINISHED_ABORTED:
 195
 196 <!-- ##### ENUM GtkPrintOperationResult ##### -->
 197 <para>
 198
 199 </para>
 200
 201 @GTK_PRINT_OPERATION_RESULT_ERROR:
 202 @GTK_PRINT_OPERATION_RESULT_APPLY:
 203 @GTK_PRINT_OPERATION_RESULT_CANCEL:
 204
 205 <!-- ##### ENUM GtkPrintError ##### -->
 206 <para>
 207
 208 </para>
 209
 210 @GTK_PRINT_ERROR_GENERAL:
 211 @GTK_PRINT_ERROR_INTERNAL_ERROR:
 212 @GTK_PRINT_ERROR_NOMEM:
 213
 214 <!-- ##### MACRO GTK_PRINT_ERROR ##### -->
 215 <para>
 216 The #GQuark used for #GtkPrintError errors.
 217 </para>
 218
 219
 220
 221 <!-- ##### FUNCTION gtk_print_operation_new ##### -->
 222 <para>
 223
 224 </para>
 225
 226 @Returns:
 227
 228
 229 <!-- ##### FUNCTION gtk_print_operation_set_default_page_setup ##### -->
 230 <para>
 231
 232 </para>
 233
 234 @op:
 235 @default_page_setup:
 236
 237
 238 <!-- ##### FUNCTION gtk_print_operation_get_default_page_setup ##### -->
 239 <para>
 240
 241 </para>
 242
 243 @op:
 244 @Returns:
 245
 246
 247 <!-- ##### FUNCTION gtk_print_operation_set_print_settings ##### -->
 248 <para>
 249
 250 </para>
 251
 252 @op:
 253 @print_settings:
 254
 255
 256 <!-- ##### FUNCTION gtk_print_operation_get_print_settings ##### -->
 257 <para>
 258
 259 </para>
 260
 261 @op:
 262 @Returns:
 263
 264
 265 <!-- ##### FUNCTION gtk_print_operation_set_job_name ##### -->
 266 <para>
 267
 268 </para>
 269
 270 @op:
 271 @job_name:
 272
 273
 274 <!-- ##### FUNCTION gtk_print_operation_set_nr_of_pages ##### -->
 275 <para>
 276
 277 </para>
 278
 279 @op:
 280 @n_pages:
 281
 282
 283 <!-- ##### FUNCTION gtk_print_operation_set_current_page ##### -->
 284 <para>
 285
 286 </para>
 287
 288 @op:
 289 @current_page:
 290
 291
 292 <!-- ##### FUNCTION gtk_print_operation_set_use_full_page ##### -->
 293 <para>
 294
 295 </para>
 296
 297 @op:
 298 @full_page:
 299
 300
 301 <!-- ##### FUNCTION gtk_print_operation_set_unit ##### -->
 302 <para>
 303
 304 </para>
 305
 306 @op:
 307 @unit:
 308
 309
 310 <!-- ##### FUNCTION gtk_print_operation_set_show_dialog ##### -->
 311 <para>
 312
 313 </para>
 314
 315 @op:
 316 @show_dialog:
 317
 318
 319 <!-- ##### FUNCTION gtk_print_operation_set_pdf_target ##### -->
 320 <para>
 321
 322 </para>
 323
 324 @op:
 325 @filename:
 326
 327
 328 <!-- ##### FUNCTION gtk_print_operation_run ##### -->
 329 <para>
 330
 331 </para>
 332
 333 @op:
 334 @parent:
 335 @error:
 336 @Returns:
 337
 338
 339 <!-- ##### FUNCTION gtk_print_operation_run_async ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @op:
 345 @parent:
 346
 347
 348 <!-- ##### FUNCTION gtk_print_operation_get_status ##### -->
 349 <para>
 350
 351 </para>
 352
 353 @op:
 354 @Returns:
 355
 356
 357 <!-- ##### FUNCTION gtk_print_operation_get_status_string ##### -->
 358 <para>
 359
 360 </para>
 361
 362 @op:
 363 @Returns:
 364
 365
 366 <!-- ##### FUNCTION gtk_print_operation_is_finished ##### -->
 367 <para>
 368
 369 </para>
 370
 371 @op:
 372 @Returns:
 373
 374
 375 <!-- ##### FUNCTION gtk_print_run_page_setup_dialog ##### -->
 376 <para>
 377
 378 </para>
 379
 380 @parent:
 381 @page_setup:
 382 @settings:
 383 @Returns:
 384
 385
 386 <!-- ##### USER_FUNCTION GtkPageSetupDoneFunc ##### -->
 387 <para>
 388
 389 </para>
 390
 391 @page_setup:
 392 @data:
 393
 394
 395 <!-- ##### FUNCTION gtk_print_run_page_setup_dialog_async ##### -->
 396 <para>
 397
 398 </para>
 399
 400 @parent:
 401 @page_setup:
 402 @settings:
 403 @done_cb:
 404 @data:
 405
 406