Gnome User Interface Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GnomeFileEntry

## Name

GnomeFileEntry -- An entry widget for file names.

## Synopsis

    #include <gnome.h>

    struct      GnomeFileEntry;
    GtkWidget*  gnome_file_entry_new            (char *history_id,
                                                 char *browse_dialog_title);
    GtkWidget*  gnome_file_entry_gnome_entry    (GnomeFileEntry *fentry);
    GtkWidget*  gnome_file_entry_gtk_entry      (GnomeFileEntry *fentry);
    void        gnome_file_entry_set_title      (GnomeFileEntry *fentry,
                                                 char *browse_dialog_title);
    void        gnome_file_entry_set_default_path
                                                (GnomeFileEntry *fentry,
                                                 char *path);
    void        gnome_file_entry_set_directory  (GnomeFileEntry *fentry,
                                                 int directory_entry);
    char*       gnome_file_entry_get_full_path  (GnomeFileEntry *fentry,
                                                 int file_must_exist);
    void        gnome_file_entry_set_modal      (GnomeFileEntry *fentry,
                                                 int is_modal);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GtkContainer
                   +----GtkBox
                         +----GtkHBox
                               +----GnomeFileEntry

## Description

This widget provides an entry box with history (a GnomeEntry) and a button which can pop up a file selector dialog box (GtkFileSelection). It also accepts DND drops from the filemanager and other sources.

The following is an example of its use. It is a collection of excerpts from the sound section of the GNOME control center.

    static SoundProps *
    sound_properties_create(void)
    {
       char *path;
       GtkWidget *btn_filename;
       SoundProps *retval;

    ...
       /* Create the gnome_file_entry widget, with a given title */

       btn_filename = gnome_file_entry_new(NULL, _("Select sound file"));

       /* sets the default path */
       path = gnome_datadir_file ("sounds/");
       gnome_file_entry_set_default_path(GNOME_FILE_ENTRY (retval->btn_filename), path);

       /* Connect the function sound_properties_event_change_file to the
       event "changed" of the entry widget of gnome_file_entry. The
       function will be called with a pointer to the entry widget in the
       gnome_file_entry and the "retval" value. Look at
       sound_properties_event_change_file below. */

       gtk_signal_connect(GTK_OBJECT(gnome_file_entry_gtk_entry(GNOME_FILE_ENTRY(btn_filename))),
                           "changed",
                           GTK_SIGNAL_FUNC(sound_properties_event_change_file),
                           retval);
    ...

    }
    ...

    /* This is the callback function for the "changed" event of the
    gnome_file_entry.  */

    static void
    sound_properties_event_change_file(GtkEditable *entry, SoundProps *props)
    {
        char *tmp, *sounddir, *tmp2;

    ...
        /* Get the current value of the gnome_file_entry */
        tmp = gtk_entry_get_text(GTK_ENTRY(entry));

    ...

    }

    ...

    static void
    sound_properties_event_play(GtkWidget *widget, SoundProps *props)
    {
        GtkWidget *entry;

        /* This code shows how to read the current value of the widget,
           you first have to get a pointer to the entry widget of the
           gnome_file_entry*/

        entry = gnome_file_entry_gtk_entry(GNOME_FILE_ENTRY(props->btn_filename));

        gnome_sound_play(gtk_entry_get_text(GTK_ENTRY(entry)));
    }

    ...

    /* This is the way that you set the value of the widget */

    GtkWidget *btn_filename;

    gtk_entry_set_text(GTK_ENTRY(gnome_file_entry_gtk_entry(GNOME_FILE_ENTRY(btn_filename))),
    ctmp);

## Details

### struct GnomeFileEntry

    struct GnomeFileEntry;

### gnome_file_entry_new ()

    GtkWidget*  gnome_file_entry_new            (char *history_id,
                                                 char *browse_dialog_title);

Creates a new GnomeFileEntry widget.

`history_id` : | the id given to gnome_entry_new (see GnomeEntry).
`browse_dialog_title` : | Title for the file dialog window.
Returns : | A pointer to the widget, NULL if it cannot be created.

### gnome_file_entry_gnome_entry ()

    GtkWidget*  gnome_file_entry_gnome_entry    (GnomeFileEntry *fentry);

It returns a pointer to the gnome entry widget of the widget (seeGnomeEntry).

`fentry` : | The GnomeFileEntry widget to work with.
Returns : | A pointer to the component GnomeEntry widget

### gnome_file_entry_gtk_entry ()

    GtkWidget*  gnome_file_entry_gtk_entry      (GnomeFileEntry *fentry);

Similar to gnome_file_entry_gnome_entry but returns the gtk entry instead of the Gnome entry widget.

`fentry` : | The GnomeFileEntry widget to work with.
Returns : | Returns the GtkEntry widget

### gnome_file_entry_set_title ()

    void        gnome_file_entry_set_title      (GnomeFileEntry *fentry,
                                                 char *browse_dialog_title);

Set the title of the browse dialog to `browse_dialog_title`. The new title will go into effect the next time the browse button is pressed.

`fentry` : | The GnomeFileEntry widget to work with.
`browse_dialog_title` : | The new title for the file browse dialog window.

### gnome_file_entry_set_default_path ()

    void        gnome_file_entry_set_default_path
                                                (GnomeFileEntry *fentry,
                                                 char *path);

Set the default path of browse dialog to `path`. The default path is only used if the entry is empty or if the current path of the entry is not an absolute path, in which case the default path is prepended to it before the dialog is started.

`fentry` : | The GnomeFileEntry widget to work with.
`path` : | A path string.

### gnome_file_entry_set_directory ()

    void        gnome_file_entry_set_directory  (GnomeFileEntry *fentry,
                                                 int directory_entry);

Sets whether this is a directory only entry. If `directory_entry` is true, then gnome_file_entry_get_full_path will check for the file being a directory, and the browse dialog will have the file list disabled.

`fentry` : | The GnomeFileEntry widget to work with.
`directory_entry` : | boolean

### gnome_file_entry_get_full_path ()

    char*       gnome_file_entry_get_full_path  (GnomeFileEntry *fentry,
                                                 int file_must_exist);

Gets the full absolute path of the file from the entry. If `file_must_exist` is false, nothing is tested and the path is returned. If `file_must_exist` is true, then the path is only returned if the path actually exists. In case the entry is a directory entry (see gnome_file_entry_set_directory), then if the path exists and is a directory then it's returned; if not, it is assumed it was a file so we try to strip it, and try again. It allocates memory for the returned string.

`fentry` : | The GnomeFileEntry widget to work with.
`file_must_exist` : | boolean
Returns : | a newly allocated string with the path or NULL if something went wrong

### gnome_file_entry_set_modal ()

    void        gnome_file_entry_set_modal      (GnomeFileEntry *fentry,
                                                 int is_modal);

Sets the modality of the browse dialog.

`fentry` : | The GnomeFileEntry widget to work with.
`is_modal` : | true if the window is to be modal, false otherwise.

## See Also

GnomeEntry, GnomeIconEntry, GnomePixmapEntry, GnomeNumberEntry

<<< Previous Page | Home | Up | Next Page >>>
GnomeEntry | GnomeFontPicker