Next: , Previous: GtkColorSelectionDialog, Up: Top

80 GtkFileSelection

Prompt the user for a file or directory name

80.1 Overview

<gtk-file-selection> should be used to retrieve file or directory names from the user. It will create a new dialog window containing a directory list, and a file list corresponding to the current working directory. The filesystem can be navigated using the directory list or the drop-down history menu. Alternatively, the TAB key can be used to navigate using filename completion - common in text based editors such as emacs and jed.

File selection dialogs are created with a call to gtk-file-selection-new.

The default filename can be set using gtk-file-selection-set-filename and the selected filename retrieved using gtk-file-selection-get-filename.

Use gtk-file-selection-complete to display files and directories that match a given pattern. This can be used for example, to show only *.txt files, or only files beginning with gtk*.

Simple file operations; create directory, delete file, and rename file, are available from buttons at the top of the dialog. These can be hidden using gtk-file-selection-hide-fileop-buttons and shown again using gtk-file-selection-show-fileop-buttons.

     /* The file selection widget and the string to store the chosen filename */
     void store_filename (GtkWidget *widget, gpointer user_data) {
        GtkWidget *file_selector = GTK_WIDGET (user_data);
        const gchar *selected_filename;
        selected_filename = gtk_file_selection_get_filename (GTK_FILE_SELECTION (file_selector));
        g_print ("Selected filename: %s\n", selected_filename);
     void create_file_selection (void) {
        GtkWidget *file_selector;
        /* Create the selector */
        file_selector = gtk_file_selection_new ("Please select a file for editing.");
        g_signal_connect (GTK_FILE_SELECTION (file_selector)->ok_button,
                          G_CALLBACK (store_filename),
        /* Ensure that the dialog box is destroyed when the user clicks a button. */
        g_signal_connect_swapped (GTK_FILE_SELECTION (file_selector)->ok_button,
                                  G_CALLBACK (gtk_widget_destroy),
        g_signal_connect_swapped (GTK_FILE_SELECTION (file_selector)->cancel_button,
                                  G_CALLBACK (gtk_widget_destroy),
        /* Display that dialog */
        gtk_widget_show (file_selector);

80.2 Usage

— Class: <gtk-file-selection>

Derives from <gtk-dialog>.

This class defines the following slots:

Whether buttons for creating/manipulating files should be displayed
The currently selected filename
Whether to allow multiple files to be selected
— Function: gtk-file-selection-new (title mchars) ⇒  (ret <gtk-widget>)

Creates a new file selection dialog box. By default it will contain a <gtk-tree-view> of the application's current working directory, and a file listing. Operation buttons that allow the user to create a directory, delete files and rename files, are also present.

a message that will be placed in the file requestor's titlebar.
the new file selection.
— Function: gtk-file-selection-set-filename (self <gtk-file-selection>) (filename mchars)
— Method: set-filename

Sets a default path for the file requestor. If filename includes a directory path, then the requestor will open with that path as its current working directory.

This has the consequence that in order to open the requestor with a working directory and an empty filename, filename must have a trailing directory separator.

The encoding of filename is preferred GLib file name encoding, which may not be UTF-8. See g-filename-from-utf8.

a <gtk-file-selection>.
a string to set as the default file name.
— Function: gtk-file-selection-get-filename (self <gtk-file-selection>) ⇒  (ret mchars)
— Method: get-filename

This function returns the selected filename in the GLib file name encoding. To convert to UTF-8, call g-filename-to-utf8. The returned string points to a statically allocated buffer and should be copied if you plan to keep it around.

If no file is selected then the selected directory path is returned.

a <gtk-file-selection>
currently-selected filename in the on-disk encoding.
— Function: gtk-file-selection-complete (self <gtk-file-selection>) (pattern mchars)
— Method: complete

Will attempt to match pattern to a valid filenames or subdirectories in the current directory. If a match can be made, the matched filename will appear in the text entry field of the file selection dialog. If a partial match can be made, the "Files" list will contain those file names which have been partially matched, and the "Folders" list those directories which have been partially matched.

a <gtk-file-selection>.
a string of characters which may or may not match any filenames in the current directory.