## XfceFileChooser

XfceFileChooser — a wrapper around GtkFileSelection and GtkFileChooserDialog

## Synopsis

    #include <libxfcegui4/libxfcegui4.h>

    typedef     XfceFileChooser;
    enum        XfceFileChooserAction;
    void        (*PreviewUpdateFunc)            (XfceFileChooser *chooser,
                                                 gpointer user_data);
    GtkWidget*  xfce_file_chooser_dialog_new    (const gchar *title,
                                                 GtkWindow *parent,
                                                 XfceFileChooserAction action,
                                                 const gchar *first_button_text,
                                                 ...);
    GtkWidget*  xfce_file_chooser_new           (const gchar *title,
                                                 GtkWindow *parent,
                                                 XfceFileChooserAction action,
                                                 const gchar *first_button_text,
                                                 ...);
    void        xfce_file_chooser_set_select_multiple
                                                (XfceFileChooser *chooser,
                                                 gboolean select_multiple);
    gboolean    xfce_file_chooser_get_select_multiple
                                                (XfceFileChooser *chooser);
    void        xfce_file_chooser_set_current_name
                                                (XfceFileChooser *chooser,
                                                 const gchar *name);
    gchar*      xfce_file_chooser_get_filename  (XfceFileChooser *chooser);
    gboolean    xfce_file_chooser_set_filename  (XfceFileChooser *chooser,
                                                 const gchar *filename);
    GSList*     xfce_file_chooser_get_filenames (XfceFileChooser *chooser);
    gboolean    xfce_file_chooser_set_current_folder
                                                (XfceFileChooser *chooser,
                                                 const gchar *filename);
    gchar*      xfce_file_chooser_get_current_folder
                                                (XfceFileChooser *chooser);
    void        xfce_file_chooser_set_preview_widget
                                                (XfceFileChooser *chooser,
                                                 GtkWidget *preview_widget);
    GtkWidget*  xfce_file_chooser_get_preview_widget
                                                (XfceFileChooser *chooser);
    void        xfce_file_chooser_set_preview_callback
                                                (XfceFileChooser *chooser,
                                                 PreviewUpdateFunc func,
                                                 gpointer user_data);
    void        xfce_file_chooser_set_preview_widget_active
                                                (XfceFileChooser *chooser,
                                                 gboolean active);
    gboolean    xfce_file_chooser_get_preview_widget_active
                                                (XfceFileChooser *chooser);
    void        xfce_file_chooser_set_use_preview_label
                                                (XfceFileChooser *chooser,
                                                 gboolean use_label);
    void        xfce_file_chooser_set_extra_widget
                                                (XfceFileChooser *chooser,
                                                 GtkWidget *extra_widget);
    GtkWidget*  xfce_file_chooser_get_extra_widget
                                                (XfceFileChooser *chooser);
    void        xfce_file_chooser_add_filter    (XfceFileChooser *chooser,
                                                 XfceFileFilter *filter);
    void        xfce_file_chooser_remove_filter (XfceFileChooser *chooser,
                                                 XfceFileFilter *filter);
    void        xfce_file_chooser_set_filter    (XfceFileChooser *chooser,
                                                 XfceFileFilter *filter);
    void        xfce_file_chooser_set_local_only
                                                (XfceFileChooser *chooser,
                                                 gboolean local_only);
    gboolean    xfce_file_chooser_get_local_only
                                                (XfceFileChooser *chooser);
    gboolean    xfce_file_chooser_add_shortcut_folder
                                                (XfceFileChooser *chooser,
                                                 const gchar *folder,
                                                 GError **error);
    gboolean    xfce_file_chooser_remove_shortcut_folder
                                                (XfceFileChooser *chooser,
                                                 const gchar *folder,
                                                 GError **error);
    typedef     XfceFileFilter;
    XfceFileFilter* xfce_file_filter_new        ();
    void        xfce_file_filter_set_name       (XfceFileFilter *filter,
                                                 const gchar *name);
    void        xfce_file_filter_add_mime_type  (XfceFileFilter *filter,
                                                 const gchar *mime_type);
    void        xfce_file_filter_add_pattern    (XfceFileFilter *filter,
                                                 const gchar *pattern);

## Description

XfceFileChooser is meant to be used as a gtk-version-neutral file selector. If libxfcegui4 is compiled against GTK+ 2.0 or 2.2, XfceFileChooser will use the older GtkFileSelection. If libxfcegui4 is compiled against GTK+ 2.4 or greater, XfceFileChooser will use GtkFileChooserDialog. The API of XfceFileChooser is designed to be similar to that of the GtkFileChooser interface, and may behave differently from the older GtkFileSelection API.

## Details

### XfceFileChooser

    typedef GtkDialog XfceFileChooser;

### enum XfceFileChooserAction

    typedef enum {
    	XFCE_FILE_CHOOSER_ACTION_OPEN,
    	XFCE_FILE_CHOOSER_ACTION_SAVE,
    	XFCE_FILE_CHOOSER_ACTION_SELECT_FOLDER,
    	XFCE_FILE_CHOOSER_ACTION_CREATE_FOLDER
    } XfceFileChooserAction;

Describes whether a XfceFileChooser is being used to open existing files or to save to a possibly new file.

`XFCE_FILE_CHOOSER_ACTION_OPEN` | Indicates open mode. The file chooser will only let the user pick an existing file.
`XFCE_FILE_CHOOSER_ACTION_SAVE` | Indicates save mode. The file chooser will let the user pick an existing file, or type in a new filename.
`XFCE_FILE_CHOOSER_ACTION_SELECT_FOLDER` | Indicates an Open mode for selecting folders. The file chooser will let the user pick an existing folder.
`XFCE_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.

### PreviewUpdateFunc ()

    void        (*PreviewUpdateFunc)            (XfceFileChooser *chooser,
                                                 gpointer user_data);

Use this function prototype for functions to be passed to `xfce_file_chooser_set_preview_callback()`.

`chooser` : | The XfceFileChooser where the signal occurred.
`user_data` : | The `user_data` passed to `xfce_file_chooser_set_preview_callback()`.

### xfce_file_chooser_dialog_new ()

    GtkWidget*  xfce_file_chooser_dialog_new    (const gchar *title,
                                                 GtkWindow *parent,
                                                 XfceFileChooserAction action,
                                                 const gchar *first_button_text,
                                                 ...);

### Warning

`xfce_file_chooser_dialog_new` is deprecated and should not be used in newly-written code. Use `xfce_file_chooser_new()` instead.

`title` : | The dialog's window title, or `NULL`.
`parent` : | The dialog's transient parent window, or `NULL`.
`action` : | Open or save mode for dialog.
`first_button_text` : | Stock ID or text for the first button.
`...` : | Response ID for the first button, followed by additional (button, ID) pairs, terminated with a `NULL` argument.
Returns : | a new XfceFileChooser dialog widget.

### xfce_file_chooser_new ()

    GtkWidget*  xfce_file_chooser_new           (const gchar *title,
                                                 GtkWindow *parent,
                                                 XfceFileChooserAction action,
                                                 const gchar *first_button_text,
                                                 ...);

Constructs a new file chooser dialog. If compiled against GTK+ 2.4 (or above), this will create a GtkFileChooserDialog. For GTK+ 2.0 and 2.2, this creates a GtkFileSelection.

Since 4.1

`title` : | The dialog's window title, or `NULL`.
`parent` : | The dialog's transient parent window, or `NULL`.
`action` : | Open or save mode for dialog.
`first_button_text` : | Stock ID or text for the first button.
`...` : | Response ID for the first button, followed by additional (button, ID) pairs, terminated with a `NULL` argument.
Returns : | a new XfceFileChooser dialog widget.

### xfce_file_chooser_set_select_multiple ()

    void        xfce_file_chooser_set_select_multiple
                                                (XfceFileChooser *chooser,
                                                 gboolean select_multiple);

Sets whether multiple files can be selected in the file chooser.

Since 4.1

`chooser` : | An XfceFileChooser.
`select_multiple` : | `TRUE` it multiple files can be selected.

### xfce_file_chooser_get_select_multiple ()

    gboolean    xfce_file_chooser_get_select_multiple
                                                (XfceFileChooser *chooser);

Gets whether multiple files can be selected in the file chooser. See `xfce_file_chooser_set_select_multiple()`.

Since 4.1

`chooser` : | An XfceFileChooser.
Returns : | `TRUE` if multiple files can be selected, `FALSE` otherwise.

### xfce_file_chooser_set_current_name ()

    void        xfce_file_chooser_set_current_name
                                                (XfceFileChooser *chooser,
                                                 const gchar *name);

Sets the name to be displayed in the file chooser's entry box, as if entered by the user. This function is meant to be used, e.g., to suggest a file name to a user in a "Save as..." dialog.

To preselect a particular existing filename, see `xfce_file_chooser_set_filename()`.

Since 4.1

`chooser` : | An XfceFileChooser.
`name` : | The filename to use (UTF-8 only).

### xfce_file_chooser_get_filename ()

    gchar*      xfce_file_chooser_get_filename  (XfceFileChooser *chooser);

Returns the currently selected file in the file chooser. If multiple files are selected, behavior is indeterminate.

Since 4.1

`chooser` : | An XfceFileChooser.
Returns : | The currently selected filename, or `NULL` if no file is selected. This string is allocated by libxfcegui4 and should be released with `g_free()` when it is no longer needed.

### xfce_file_chooser_set_filename ()

    gboolean    xfce_file_chooser_set_filename  (XfceFileChooser *chooser,
                                                 const gchar *filename);

Sets `filename` as the currently selected file in the file chooser, changing the file chooser's directory view if necessary.

Note that the file must exist, or nothing will occur except for possibly a directory change. If you wish to suggest a file name to the user, use `xfce_file_chooser_set_current_name()` instead.

Since 4.1

`chooser` : | An XfceFileChooser.
`filename` : | A filename to set.
Returns : | `TRUE` if the file exists and was selected, `FALSE` otherwise.

### xfce_file_chooser_get_filenames ()

    GSList*     xfce_file_chooser_get_filenames (XfceFileChooser *chooser);

Gets a list of file names selected in the file chooser. This is intended for use when `xfce_file_chooser_set_select_multiple()` is used to allow the selection of multiple files.

Since 4.1

`chooser` : | An XfceFileChooser.
Returns : | A GSList containing the filenames of all selected files in the file chooser. Release the list with `g_slist_free()` and the filenames with `g_free()` when they are no longer needed.

### xfce_file_chooser_set_current_folder ()

    gboolean    xfce_file_chooser_set_current_folder
                                                (XfceFileChooser *chooser,
                                                 const gchar *filename);

Sets the current folder of `chooser` to `filename`.

Since 4.1

`chooser` : | An XfceFileChooser.
`filename` : | The full path of the new current folder.
Returns : | `TRUE` if the folder exists and could be changed, `FALSE` otherwise.

### xfce_file_chooser_get_current_folder ()

    gchar*      xfce_file_chooser_get_current_folder
                                                (XfceFileChooser *chooser);

Gets the current folder visible in the file chooser.

Since 4.1

`chooser` : | An XfceFileChooser.
Returns : | The currently-selected folder. Release with `g_free()` when no longer needed.

### xfce_file_chooser_set_preview_widget ()

    void        xfce_file_chooser_set_preview_widget
                                                (XfceFileChooser *chooser,
                                                 GtkWidget *preview_widget);

Sets an app-supplied widget to be shown as a "preview widget" for the file chooser. To implement the preview, set a callback function using `xfce_file_chooser_set_preview_callback()`. In this callback function, use `xfce_file_chooser_get_filename()` to get the currently selected file. Finally, use `xfce_file_chooser_set_preview_widget_active()` to tell the file chooser whether or not a preview should be shown for that file.

Since 4.1

`chooser` : | An XfceFileChooser.
`preview_widget` : | A widget used to preview file data.

### xfce_file_chooser_get_preview_widget ()

    GtkWidget*  xfce_file_chooser_get_preview_widget
                                                (XfceFileChooser *chooser);

Retrieves the preview widget set by `xfce_file_chooser_set_preview_widget()`.

Since 4.1

`chooser` : | An XfceFileChooser.
Returns : | A GtkWidget, or `NULL` if no preview widget was set.

### xfce_file_chooser_set_preview_callback ()

    void        xfce_file_chooser_set_preview_callback
                                                (XfceFileChooser *chooser,
                                                 PreviewUpdateFunc func,
                                                 gpointer user_data);

Sets a callback function to be executed whenever the preview widget requires updating. Unfortunately, this method limits the application to a single callback function, but this should be sufficient for most uses.

Since 4.1

`chooser` : | An XfceFileChooser.
`func` : | A callback function.
`user_data` : | Data to be passed to `func`.

### xfce_file_chooser_set_preview_widget_active ()

    void        xfce_file_chooser_set_preview_widget_active
                                                (XfceFileChooser *chooser,
                                                 gboolean active);

Sets whether or not the currently selected file supports some type of preview, handled by the widget set with `xfce_file_chooser_set_preview_widget()`. This should be used in the preview callback every time the selected file is changed.

Since 4.1

`chooser` : | An XfceFileChooser.
`active` : | `TRUE` or `FALSE` depending on whether or not the preview should be shown.

### xfce_file_chooser_get_preview_widget_active ()

    gboolean    xfce_file_chooser_get_preview_widget_active
                                                (XfceFileChooser *chooser);

Gets whether or not the preview widget is displayed for the current file. See `xfce_file_chooser_set_preview_widget_active()`.

Since 4.1

`chooser` : | An XfceFileChooser.
Returns : | `TRUE` if the preview widget is active, `FALSE` otherwise.

### xfce_file_chooser_set_use_preview_label ()

    void        xfce_file_chooser_set_use_preview_label
                                                (XfceFileChooser *chooser,
                                                 gboolean use_label);

Sets whether the file chooser should display a text label above the preview widget containing the name of the selected file.

Since 4.1

`chooser` : | An XfceFileChooser.
`use_label` : | Whether to display a stock label with the name of the previewed file.

### xfce_file_chooser_set_extra_widget ()

    void        xfce_file_chooser_set_extra_widget
                                                (XfceFileChooser *chooser,
                                                 GtkWidget *extra_widget);

Sets a widget to display in the file chooser to provide extra options to the user.

Since 4.1

`chooser` : | An XfceFileChooser.
`extra_widget` : | An extra widget to display.

### xfce_file_chooser_get_extra_widget ()

    GtkWidget*  xfce_file_chooser_get_extra_widget
                                                (XfceFileChooser *chooser);

Gets the widget set with `xfce_file_chooser_set_extra_widget()`.

Since 4.1

`chooser` : | An XfceFileChooser.
Returns : | The extra GtkWidget.

### xfce_file_chooser_add_filter ()

    void        xfce_file_chooser_add_filter    (XfceFileChooser *chooser,
                                                 XfceFileFilter *filter);

Adds a filter to the list of filters that the user can select to restrict the view of the file chooser.

Note: This currently does nothing when libxfcegui4 is compiled against GTK+ 2.2 or lower.

Since 4.1

`chooser` : | An XfceFileChooser.
`filter` : | An XfceFileFilter created with `xfce_file_filter_new()`.

### xfce_file_chooser_remove_filter ()

    void        xfce_file_chooser_remove_filter (XfceFileChooser *chooser,
                                                 XfceFileFilter *filter);

Removes `filter` from the list of filters displayed by the file chooser.

Note: This currently does nothing when libxfcegui4 is compiled against GTK+ 2.2 or lower.

Since 4.1

`chooser` : | An XfceFileChooser.
`filter` : | An XfceFileFilter.

### xfce_file_chooser_set_filter ()

    void        xfce_file_chooser_set_filter    (XfceFileChooser *chooser,
                                                 XfceFileFilter *filter);

Sets the file chooser's currently selected file filter to `filter`. This filter must have been added previously using `xfce_file_chooser_add_filter()`.

Note: This currently does nothing when libxfcegui4 is compiled against GTK+ 2.2 or lower.

Since 4.1

`chooser` : | An XfceFileChooser.
`filter` : | An XfceFileFilter.

### xfce_file_chooser_set_local_only ()

    void        xfce_file_chooser_set_local_only
                                                (XfceFileChooser *chooser,
                                                 gboolean local_only);

### Warning

`xfce_file_chooser_set_local_only` is deprecated and should not be used in newly-written code. This function isn't really useful in the context of Xfce.

Since 4.1

Sets whether or not the file chooser can display and/or allow the selection of non-local files.

`chooser` : | An XfceFileChooser.
`local_only` : | Whether to only allow the display of local files.

### xfce_file_chooser_get_local_only ()

    gboolean    xfce_file_chooser_get_local_only
                                                (XfceFileChooser *chooser);

### Warning

`xfce_file_chooser_get_local_only` is deprecated and should not be used in newly-written code. This function isn't really useful in the context of Xfce.

Since 4.1

Gets whether or not the file chooser can display and/or allow the selection of non-local files.

Return value:

`chooser` : | An XfceFileChooser.
Returns : | `TRUE` if non-local files are allowed, `FALSE` otherwise.

### xfce_file_chooser_add_shortcut_folder ()

    gboolean    xfce_file_chooser_add_shortcut_folder
                                                (XfceFileChooser *chooser,
                                                 const gchar *folder,
                                                 GError **error);

Adds a folder to be displayed in the shortcut folders list in the file chooser. The folder name is validated, so only valid paths may be added.

Note: This currently does nothing when libxfcegui4 is compiled against GTK+ 2.2 or lower.

Since 4.1

`chooser` : | An XfceFileChooser.
`folder` : | The full path to a folder name.
`error` : | Location to store any errors, or `NULL`.
Returns : | `TRUE` if the folder given is valid, `FALSE` otherwise. If `error` is non-`NULL`, it will be set with any error that occurs.

### xfce_file_chooser_remove_shortcut_folder ()

    gboolean    xfce_file_chooser_remove_shortcut_folder
                                                (XfceFileChooser *chooser,
                                                 const gchar *folder,
                                                 GError **error);

Removes the specified folder from the file chooser's shortcut folder list.

Note: This currently does nothing when libxfcegui4 is compiled against GTK+ 2.2 or lower.

Since 4.1

`chooser` : | An XfceFileChooser.
`folder` : | The full path to an existing shortcut folder name.
`error` : | Location to store any errors, or `NULL`.
Returns : | `TRUE` if the removal succeeded, `FALSE` otherwise. If `error` is non-`NULL`, it will be set with any error that occurs.

### XfceFileFilter

    typedef GtkObject XfceFileFilter;

With GTK+ 2.4, this object is mapped to a GtkFileFilter. However, with GTK+ 2.0 or 2.2, this object doesn't exist, so functions that use it will return and expect a `NULL` value. As such, pointers to an XfceFileFilter should be treated as opaque, and no attempt should be made to dereference them.

### xfce_file_filter_new ()

    XfceFileFilter* xfce_file_filter_new        ();

Create a new empty file filter.

Note: this will always return `NULL` when libxfcegui4 is compiled against GTK+ 2.2 or below, as file filters are not supported.

Since 4.1

Returns : | An XfceFileFilter, or `NULL` (GTK+ 2.2 and below).

### xfce_file_filter_set_name ()

    void        xfce_file_filter_set_name       (XfceFileFilter *filter,
                                                 const gchar *name);

Sets a name to be displayed in in the option menu which describes the filter's purpose.

Note: this function has no effect when libxfcegui4 is compiled against GTK+ 2.2 or below, as file filters are not supported.

Since 4.1

`filter` : | An XfceFileFilter.
`name` : | The name of the filter.

### xfce_file_filter_add_mime_type ()

    void        xfce_file_filter_add_mime_type  (XfceFileFilter *filter,
                                                 const gchar *mime_type);

Adds a MIME type to the file filter. All files matching this MIME type will be displayed in the file chooser when the filter is selected.

Note: this function has no effect when libxfcegui4 is compiled against GTK+ 2.2 or below, as file filters are not supported.

Since 4.1

`filter` : | An XfceFileFilter.
`mime_type` : | A registered MIME type.

### xfce_file_filter_add_pattern ()

    void        xfce_file_filter_add_pattern    (XfceFileFilter *filter,
                                                 const gchar *pattern);

Adds a shell-glob-type file pattern to the file filter. All files matching the pattern will be displayed in the file chooser when the filter is selected.

Note: this function has no effect when libxfcegui4 is compiled against GTK+ 2.2 or below, as file filters are not supported.

Since 4.1

`filter` : | An XfceFileFilter.
`pattern` : | A file pattern.