XfceFileChooser

## 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);
    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 {
     /*< prefix=XFCE_FILE_CHOOSER_ACTION_ >*/
    	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 GtkFileChooser 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,
                                                             ...);

### Warning

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

Since 4.1

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.

`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);

### Warning

`xfce_file_chooser_set_select_multiple` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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

`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);

### Warning

`xfce_file_chooser_get_select_multiple` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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

`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);

### Warning

`xfce_file_chooser_set_current_name` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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

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

### xfce_file_chooser_get_filename ()

    gchar *             xfce_file_chooser_get_filename      (XfceFileChooser *chooser);

### Warning

`xfce_file_chooser_get_filename` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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

`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);

### Warning

`xfce_file_chooser_set_filename` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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.

`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);

### Warning

`xfce_file_chooser_get_filenames` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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.

`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);

### Warning

`xfce_file_chooser_set_current_folder` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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

`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);

### Warning

`xfce_file_chooser_get_current_folder` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

Gets the current folder visible in the file chooser.

`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);

### Warning

`xfce_file_chooser_set_preview_widget` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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.

`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);

### Warning

`xfce_file_chooser_get_preview_widget` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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

`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);

### Warning

`xfce_file_chooser_set_preview_callback` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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.

`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);

### Warning

`xfce_file_chooser_set_preview_widget_active` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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.

`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);

### Warning

`xfce_file_chooser_get_preview_widget_active` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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

`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);

### Warning

`xfce_file_chooser_set_use_preview_label` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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

`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);

### Warning

`xfce_file_chooser_set_extra_widget` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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

`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);

### Warning

`xfce_file_chooser_get_extra_widget` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

Gets the widget set with `xfce_file_chooser_set_extra_widget()`.

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

### xfce_file_chooser_add_filter ()

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

### Warning

`xfce_file_chooser_add_filter` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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.

`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);

### Warning

`xfce_file_chooser_remove_filter` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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.

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

### xfce_file_chooser_set_filter ()

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

### Warning

`xfce_file_chooser_set_filter` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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.

`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. Use GtkFileChooser instead.

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. Use GtkFileChooser instead.

Since 4.1

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

`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);

### Warning

`xfce_file_chooser_add_shortcut_folder` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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.

`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);

### Warning

`xfce_file_chooser_remove_shortcut_folder` is deprecated and should not be used in newly-written code. Use GtkFileChooser instead.

Since 4.1

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.

`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                (void);

### Warning

`xfce_file_filter_new` is deprecated and should not be used in newly-written code. Use GtkFileFilter instead.

Since 4.1

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.

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);

### Warning

`xfce_file_filter_set_name` is deprecated and should not be used in newly-written code. Use GtkFileFilter instead.

Since 4.1

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.

`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);

### Warning

`xfce_file_filter_add_mime_type` is deprecated and should not be used in newly-written code. Use GtkFileFilter instead.

Since 4.1

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.

`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);

### Warning

`xfce_file_filter_add_pattern` is deprecated and should not be used in newly-written code. Use GtkFileFilter instead.

Since 4.1

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.

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