1
2@c %start of fragment
3
4@node GtkFileSelection
5@chapter GtkFileSelection
6Prompt the user for a file or directory name
7
8@section Overview
9@code{<gtk-file-selection>} should be used to retrieve file or directory names
10from the user. It will create a new dialog window containing a directory list,
11and a file list corresponding to the current working directory. The filesystem
12can be navigated using the directory list or the drop-down history menu.
13Alternatively, the TAB key can be used to navigate using filename completion -
14common in text based editors such as emacs and jed.
15
16File selection dialogs are created with a call to @code{gtk-file-selection-new}.
17
18The default filename can be set using @code{gtk-file-selection-set-filename} and
19the selected filename retrieved using @code{gtk-file-selection-get-filename}.
20
21Use @code{gtk-file-selection-complete} to display files and directories that
22match a given pattern. This can be used for example, to show only *.txt files,
23or only files beginning with gtk*.
24
25Simple file operations; create directory, delete file, and rename file, are
26available from buttons at the top of the dialog. These can be hidden using
27@code{gtk-file-selection-hide-fileop-buttons} and shown again using
28@code{gtk-file-selection-show-fileop-buttons}.
29
30
31
32@example
33
34
35/* The file selection widget and the string to store the chosen filename */
36
37void store_filename (GtkWidget *widget, gpointer user_data) @{
38   GtkWidget *file_selector = GTK_WIDGET (user_data);
39   const gchar *selected_filename;
40
41   selected_filename = gtk_file_selection_get_filename (GTK_FILE_SELECTION (file_selector));
42   g_print ("Selected filename: %s\n", selected_filename);
43@}
44
45void create_file_selection (void) @{
46
47   GtkWidget *file_selector;
48
49   /* Create the selector */
50
51   file_selector = gtk_file_selection_new ("Please select a file for editing.");
52
53   g_signal_connect (GTK_FILE_SELECTION (file_selector)->ok_button,
54                     "clicked",
55                     G_CALLBACK (store_filename),
56                     file_selector);
57
58   /* Ensure that the dialog box is destroyed when the user clicks a button. */
59
60   g_signal_connect_swapped (GTK_FILE_SELECTION (file_selector)->ok_button,
61                             "clicked",
62                             G_CALLBACK (gtk_widget_destroy),
63                             file_selector);
64
65   g_signal_connect_swapped (GTK_FILE_SELECTION (file_selector)->cancel_button,
66                             "clicked",
67                             G_CALLBACK (gtk_widget_destroy),
68                             file_selector);
69
70   /* Display that dialog */
71
72   gtk_widget_show (file_selector);
73@}
74
75@end example
76
77@section Usage
78@include defuns-gtkfilesel.xml.texi
79
80@c %end of fragment
81