GTK+ Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GtkFileSelection

## Name

GtkFileSelection -- prompt the user for a file or directory name.

## Synopsis

    #include <gtk/gtk.h>

    struct      GtkFileSelection;
    GtkWidget*  gtk_file_selection_new          (const gchar *title);
    void        gtk_file_selection_set_filename (GtkFileSelection *filesel,
                                                 const gchar *filename);
    gchar*      gtk_file_selection_get_filename (GtkFileSelection *filesel);
    void        gtk_file_selection_complete     (GtkFileSelection *filesel,
                                                 const gchar *pattern);
    void        gtk_file_selection_show_fileop_buttons
                                                (GtkFileSelection *filesel);
    void        gtk_file_selection_hide_fileop_buttons
                                                (GtkFileSelection *filesel);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkBin
                         +----GtkWindow
                               +----GtkFileSelection

## Description

GtkFileSelection 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 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().

Example 1. Getting a filename from the user

    /* The file selection widget and the string to store the chosen filename */

    GtkWidget *file_selector;
    gchar *selected_filename;

    void store_filename(GtkFileSelection *selector, gpointer user_data) {
       selected_filename = gtk_file_selection_get_filename (GTK_FILE_SELECTION(file_selector));
    }

    void create_file_selection(void) {

       /* Create the selector */

       file_selector = gtk_file_selection_new("Please select a file for editing.");

       gtk_signal_connect (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button),
       			   "clicked", GTK_SIGNAL_FUNC (store_filename), NULL);

       /* Ensure that the dialog box is destroyed when the user clicks a button. */

       gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->ok_button),
       					  "clicked", GTK_SIGNAL_FUNC (gtk_widget_destroy),
       					  (gpointer) file_selector);

       gtk_signal_connect_object (GTK_OBJECT (GTK_FILE_SELECTION(file_selector)->cancel_button),
       					  "clicked", GTK_SIGNAL_FUNC (gtk_widget_destroy),
       					  (gpointer) file_selector);

       /* Display that dialog */

       gtk_widget_show (file_selector);
    }

## Details

### struct GtkFileSelection

    struct GtkFileSelection;

The GtkFileSelection struct contains the following GtkWidget fields:

*fileop_dialog; | the dialog box used to display the GtkFileSelection. It can be customized by adding/removing widgets from it using the standard GtkDialog functions.
*dir_list, *file_list; | the two GtkCList widgets corresponding to directories and files.
*ok_button, *cancel_button; | the two main buttons that signals should be connected to in order to perform an action when the user hits either OK or Cancel.
*history_pulldown; | the GtkOptionMenu used to create the drop-down directory history.
*fileop_c_dir, *fileop_del_file, *fileop_ren_file; | the buttons that appear at the top of the file selection dialog. These "operation buttons" can be hidden and redisplayed with gtk_file_selection_hide_fileop_buttons() and gtk_file_selection_show_fileop_buttons() respectively.

### gtk_file_selection_new ()

    GtkWidget*  gtk_file_selection_new          (const gchar *title);

Creates a new file selection dialog box. By default it will contain a GtkCList 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.

`title` : | a message that will be placed in the file requestor's titlebar.
Returns : | the new file selection.

### gtk_file_selection_set_filename ()

    void        gtk_file_selection_set_filename (GtkFileSelection *filesel,
                                                 const gchar *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.

`filesel` : | a GtkFileSelection.
`filename` : | a string to set as the default file name.

### gtk_file_selection_get_filename ()

    gchar*      gtk_file_selection_get_filename (GtkFileSelection *filesel);

Retrieves the currently selected filename from the file selection dialog. If no file is selected then the selected directory path is returned.

`filesel` : | a GtkFileSelection
Returns : | a string containing the selected file's full path.

### gtk_file_selection_complete ()

    void        gtk_file_selection_complete     (GtkFileSelection *filesel,
                                                 const gchar *pattern);

Will attempt to match `pattern` to a valid filename 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.

`filesel` : | a GtkFileSelection.
`pattern` : | a string of characters which may or may not match any filenames in the current directory.

### gtk_file_selection_show_fileop_buttons ()

    void        gtk_file_selection_show_fileop_buttons
                                                (GtkFileSelection *filesel);

Shows the file operation buttons, if they have previously been hidden. The rest of the widgets in the dialog will be resized accordingly.

`filesel` : | a GtkFileSelection.

### gtk_file_selection_hide_fileop_buttons ()

    void        gtk_file_selection_hide_fileop_buttons
                                                (GtkFileSelection *filesel);

Hides the file operation buttons that normally appear at the top of the dialog. Useful if you wish to create a custom file selector, based on GtkFileSelection.

`filesel` : | a GtkFileSelection.

## See Also

GtkDialog

  Add your own widgets into the GtkFileSelection.

<<< Previous Page | Home | Up | Next Page >>>
GtkEventBox | GtkFixed