gtkfilechooser.sgml 10.7 KB
Newer Older
1
2
3
4
<!-- ##### SECTION Title ##### -->
GtkFileChooser

<!-- ##### SECTION Short_Description ##### -->
5
File chooser interface used by #GtkFileChooserWidget and #GtkFileChooserDialog.
6
7

<!-- ##### SECTION Long_Description ##### -->
8
9
10
11
12
13
14
15
16
    <para>
      #GtkFileChooser is an interface that can be implemented by file
      selection widgets.  In GTK+, the main objects that implement
      this interface are #GtkFileChooserWidget and
      #GtkFileChooserDialog.  You do not need to write an object that
      implements the #GtkFileChooser interface unless you are trying
      to adapt an existing file selector to expose a standard
      programming interface.
    </para>
17

18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
    <refsect2 id="gtkfilechooser-preview">
      <title>Adding a Preview Widget</title>

      <para>
	You can add a custom preview widget to a file chooser and then
	get notification about when the preview needs to be updated.
	To install a preview widget, use
	gtk_file_chooser_set_preview_widget().  Then, connect to the
	#GtkFileChooser::update-preview signal to get notified when
	you need to update the contents of the preview.
      </para>

      <para>
	Your callback should use
	gtk_file_chooser_get_preview_filename() to see what needs
	previewing.  Once you have generated the preview for the
	corresponding file, you must call
	gtk_file_chooser_set_preview_widget_active() with a boolean
	flag that indicates whether your callback could successfully
	generate a preview.
      </para>

      <example id="example-gtkfilechooser-preview">
	<title>Sample Usage</title>

	<programlisting>
{
  GtkImage *preview;

  ...

  preview = gtk_image_new ();

  gtk_file_chooser_set_preview_widget (my_file_chooser, preview);
  g_signal_connect (my_file_chooser, "update-preview",
		    G_CALLBACK (update_preview_cb), preview);
}

static void
update_preview_cb (GtkFileChooser *file_chooser, gpointer data)
{
  GtkWidget *preview;
  char *filename;
  GdkPixbuf *pixbuf;
  gboolean have_preview;

  preview = GTK_WIDGET (data);
  filename = gtk_file_chooser_get_preview_filename (file_chooser);

  pixbuf = gdk_pixbuf_new_from_file_at_size (filename, 128, 128, NULL);
  have_preview = (pixbuf != NULL);
  g_free (filename);

  gtk_image_set_from_pixbuf (GTK_IMAGE (preview), pixbuf);
  if (pixbuf)
    gdk_pixbuf_unref (pixbuf);

  gtk_file_chooser_set_preview_widget_active (file_chooser, have_preview);
}
	</programlisting>
      </example>
    </refsect2>

    <refsect2 id="gtkfilechooser-extra">
      <title>Adding Extra Widgets</title>

      <para>
	You can add extra widgets to a file chooser to provide options
	that are not present in the default design.  For example, you
	can add a toggle button to give the user the option to open a
	file in read-only mode.  You can use
	gtk_file_chooser_set_extra_widget() to insert additional
	widgets in a file chooser.
      </para>

      <example id="example-gtkfilechooser-extra">
	<title>Sample Usage</title>

	<programlisting>
{
  GtkWidget *toggle;

  ...

  toggle = gtk_check_button_new_with_label ("Open file read-only");
  gtk_widget_show (toggle);
  gtk_file_chooser_set_extra_widget (my_file_chooser, toggle);
}
	</programlisting>
      </example>

      <note>
	<para>
	  If you want to set more than one extra widget in the file
	  chooser, you can a container such as a GtkVBox or a GtkTable
	  and include your widgets in it.  Then, set the container as
	  the whole extra widget.
	</para>
      </note>
    </refsect2>

119
<!-- ##### SECTION See_Also ##### -->
120
121
122
    <para>
      #GtkFileChooserDialog, #GtkFileChooserWidget
    </para>
123

124
125
126
127
128
129
<!-- ##### STRUCT GtkFileChooser ##### -->
<para>

</para>


Owen Taylor's avatar
Owen Taylor committed
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
<!-- ##### SIGNAL GtkFileChooser::current-folder-changed ##### -->
<para>

</para>

@filechooser: the object which received the signal.

<!-- ##### SIGNAL GtkFileChooser::file-activated ##### -->
<para>

</para>

@filechooser: the object which received the signal.

<!-- ##### SIGNAL GtkFileChooser::selection-changed ##### -->
<para>

</para>

@filechooser: the object which received the signal.

<!-- ##### SIGNAL GtkFileChooser::update-preview ##### -->
<para>

</para>

@filechooser: the object which received the signal.

<!-- ##### ARG GtkFileChooser:action ##### -->
<para>

</para>

<!-- ##### ARG GtkFileChooser:extra-widget ##### -->
<para>

</para>

<!-- ##### ARG GtkFileChooser:file-system-backend ##### -->
<para>

</para>

<!-- ##### ARG GtkFileChooser:filter ##### -->
<para>

</para>

<!-- ##### ARG GtkFileChooser:folder-mode ##### -->
<para>

</para>

<!-- ##### ARG GtkFileChooser:local-only ##### -->
<para>

</para>

<!-- ##### ARG GtkFileChooser:preview-widget ##### -->
<para>

</para>

<!-- ##### ARG GtkFileChooser:preview-widget-active ##### -->
<para>

</para>

<!-- ##### ARG GtkFileChooser:select-multiple ##### -->
<para>

</para>

<!-- ##### ARG GtkFileChooser:show-hidden ##### -->
<para>

</para>

208
<!-- ##### ENUM GtkFileChooserAction ##### -->
209
210
211
212
    <para>
      Describes whether a #GtkFileChooser is being used to open
      existing files or to save to a possibly new file.
    </para>
213

214
@GTK_FILE_CHOOSER_ACTION_OPEN: Indicates open mode.  The file chooser
215
    will only let the user pick an existing file.
216
@GTK_FILE_CHOOSER_ACTION_SAVE: Indicates save mode.  The file chooser
217
218
    will let the user pick an existing file, or type in a new
    filename.
219
220
221
222
223
224
@GTK_FILE_CHOOSER_ACTION_SELECT_FOLDER: Indicates an Open mode for
    selecting folders.  The file chooser will let the user pick an
    existing folder.
@GTK_FILE_CHOOSER_ACTION_CREATE_FOLDER: Indicates a mode for creating a
    new folder.  The file chooser will let the user name an existing or
    new folder.
225
226

<!-- ##### MACRO GTK_FILE_CHOOSER_ERROR ##### -->
227
228
229
    <para>
      Used to get the #GError quark for #GtkFileChooser errors.
    </para>
230
231
232
233



<!-- ##### ENUM GtkFileChooserError ##### -->
234
235
236
237
    <para>
      These identify the various errors that can occur while calling
      #GtkFileChooser functions.
    </para>
238

239
240
@GTK_FILE_CHOOSER_ERROR_NONEXISTENT: Indicates that a file does not exist.
@GTK_FILE_CHOOSER_ERROR_BAD_FILENAME: Indicates a malformed filename.
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273

<!-- ##### FUNCTION gtk_file_chooser_error_quark ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_action ##### -->
<para>

</para>

@chooser: 
@action: 


<!-- ##### FUNCTION gtk_file_chooser_get_action ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_local_only ##### -->
<para>

</para>

@chooser: 
274
275
@local_only: 
<!-- # Unused Parameters # -->
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
@files_only: 


<!-- ##### FUNCTION gtk_file_chooser_get_local_only ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_select_multiple ##### -->
<para>

</para>

@chooser: 
@select_multiple: 


<!-- ##### FUNCTION gtk_file_chooser_get_select_multiple ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_current_name ##### -->
<para>

</para>

@chooser: 
@name: 


<!-- ##### FUNCTION gtk_file_chooser_get_filename ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_filename ##### -->
<para>

</para>

@chooser: 
@filename: 


<!-- ##### FUNCTION gtk_file_chooser_select_filename ##### -->
<para>

</para>

@chooser: 
@filename: 


<!-- ##### FUNCTION gtk_file_chooser_unselect_filename ##### -->
<para>

</para>

@chooser: 
@filename: 


<!-- ##### FUNCTION gtk_file_chooser_select_all ##### -->
<para>

</para>

@chooser: 


<!-- ##### FUNCTION gtk_file_chooser_unselect_all ##### -->
<para>

</para>

@chooser: 


<!-- ##### FUNCTION gtk_file_chooser_get_filenames ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_current_folder ##### -->
<para>

</para>

@chooser: 
@filename: 


<!-- ##### FUNCTION gtk_file_chooser_get_current_folder ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_get_uri ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_uri ##### -->
<para>

</para>

@chooser: 
@uri: 


<!-- ##### FUNCTION gtk_file_chooser_select_uri ##### -->
<para>

</para>

@chooser: 
@uri: 


<!-- ##### FUNCTION gtk_file_chooser_unselect_uri ##### -->
<para>

</para>

@chooser: 
@uri: 


<!-- ##### FUNCTION gtk_file_chooser_get_uris ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_current_folder_uri ##### -->
<para>

</para>

@chooser: 
@uri: 


<!-- ##### FUNCTION gtk_file_chooser_get_current_folder_uri ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_preview_widget ##### -->
<para>

</para>

@chooser: 
@preview_widget: 


<!-- ##### FUNCTION gtk_file_chooser_get_preview_widget ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_preview_widget_active ##### -->
<para>

</para>

@chooser: 
@active: 


<!-- ##### FUNCTION gtk_file_chooser_get_preview_widget_active ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_get_preview_filename ##### -->
<para>

</para>

498
@chooser: 
499
@Returns: 
500
501
<!-- # Unused Parameters # -->
@file_chooser: 
502
503
504
505
506
507
508


<!-- ##### FUNCTION gtk_file_chooser_get_preview_uri ##### -->
<para>

</para>

509
@chooser: 
510
@Returns: 
511
512
<!-- # Unused Parameters # -->
@file_chooser: 
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614


<!-- ##### FUNCTION gtk_file_chooser_set_extra_widget ##### -->
<para>

</para>

@chooser: 
@extra_widget: 


<!-- ##### FUNCTION gtk_file_chooser_get_extra_widget ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_add_filter ##### -->
<para>

</para>

@chooser: 
@filter: 


<!-- ##### FUNCTION gtk_file_chooser_remove_filter ##### -->
<para>

</para>

@chooser: 
@filter: 


<!-- ##### FUNCTION gtk_file_chooser_list_filters ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_set_filter ##### -->
<para>

</para>

@chooser: 
@filter: 


<!-- ##### FUNCTION gtk_file_chooser_get_filter ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder ##### -->
<para>

</para>

@chooser: 
@folder: 
@error: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder ##### -->
<para>

</para>

@chooser: 
@folder: 
@error: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folders ##### -->
<para>

</para>

@chooser: 
@Returns: 


<!-- ##### FUNCTION gtk_file_chooser_add_shortcut_folder_uri ##### -->
<para>

</para>

@chooser: 
615
@uri: 
616
617
@error: 
@Returns: 
618
619
<!-- # Unused Parameters # -->
@folder: 
620
621
622
623
624
625
626
627


<!-- ##### FUNCTION gtk_file_chooser_remove_shortcut_folder_uri ##### -->
<para>

</para>

@chooser: 
628
@uri: 
629
630
@error: 
@Returns: 
631
632
<!-- # Unused Parameters # -->
@folder: 
633
634
635
636
637
638
639
640
641
642
643


<!-- ##### FUNCTION gtk_file_chooser_list_shortcut_folder_uris ##### -->
<para>

</para>

@chooser: 
@Returns: 


644
645
646
647
648
649
650
651
652

<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gtk-docs.sgml" "book" "refentry")
End:
-->