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_OPENIndicates open mode. The file chooser will only let the user pick an existing file.
XFCE_FILE_CHOOSER_ACTION_SAVEIndicates save mode. The file chooser will let the user pick an existing file, or type in a new filename.
XFCE_FILE_CHOOSER_ACTION_SELECT_FOLDERIndicates an Open mode for selecting folders. The file chooser will let the user pick an existing folder.
XFCE_FILE_CHOOSER_ACTION_CREATE_FOLDERIndicates 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.