A file selector is a widget that allows a user to navigate through a file system, reporting file selections back via its API.

It contains shortcut buttons for home directory (~) and to jump one directory upwards (..), as well as cancel/ok buttons to confirm/cancel a given selection. After either one of those two former actions, the file selector will issue its "done" smart callback.

There's a text entry on it, too, showing the name of the current selection. There's the possibility of making it editable, so it is useful on file saving dialogs on applications, where one gives a file name to save contents to, in a given directory in the system. This custom file name will be reported on the "done" smart callback (explained in sequence).

Finally, it has a view to display file system items into in two possible forms:

list
grid

If Elementary is built with support of the Ethumb thumbnailing library, the second form of view will display preview thumbnails of files which it supports.

This widget inherits from the Layout one, so that all the functions acting on it also work for file selector objects.

This widget emits the following signals, besides the ones sent from Layout:

"activated" - the user activated a file. This can happen by double-clicking or pressing Enter key. (event_info is a pointer to the activated file path)
"selected" - the user has clicked on a file (when not in folders-only mode) or directory (when in folders-only mode)
"selected,invalid" - the user has tried to access wrong path which does not exist.
"directory,open" - the list has been populated with new content (event_info is a pointer to the directory's path, a stringshared string)
"done" - the user has clicked on the "ok" or "cancel" buttons (event_info is a pointer to the selection's path, a stringshared string)
"focused" - When the fileselector has received focus. (since 1.9)
"unfocused" - When the fileselector has lost focus. (since 1.9)

For text, elm_layout_text_set() will work here on:

"ok" - OK button label if the ok button is set.
Since (EFL) :
1.8
"cancel" - Cancel button label if the cancel button is set.
Since (EFL) :
1.8
Here is an example on its usage:
File selector widget example

Functions
Evas_Object *	elm_fileselector_add (Evas_Object *parent)
void	elm_fileselector_is_save_set (Evas_Object *obj, Eina_Bool is_save)
Eina_Bool	elm_fileselector_is_save_get (const Evas_Object *obj)
void	elm_fileselector_folder_only_set (Evas_Object *obj, Eina_Bool only)
Eina_Bool	elm_fileselector_folder_only_get (const Evas_Object *obj)
void	elm_fileselector_expandable_set (Evas_Object *obj, Eina_Bool expand)
Eina_Bool	elm_fileselector_expandable_get (const Evas_Object *obj)
void	elm_fileselector_path_set (Evas_Object obj, const char path)
const char *	elm_fileselector_path_get (const Evas_Object *obj)
void	elm_fileselector_mode_set (Evas_Object *obj, Elm_Fileselector_Mode mode)
Elm_Fileselector_Mode	elm_fileselector_mode_get (const Evas_Object *obj)
void	elm_fileselector_multi_select_set (Evas_Object *obj, Eina_Bool multi)
Eina_Bool	elm_fileselector_multi_select_get (const Evas_Object *obj)
Eina_Bool	elm_fileselector_selected_set (Evas_Object obj, const char path)
const char *	elm_fileselector_selected_get (const Evas_Object *obj)
const Eina_List *	elm_fileselector_selected_paths_get (const Evas_Object *obj)
Eina_Bool	elm_fileselector_mime_types_filter_append (Evas_Object obj, const char mime_types, const char *filter_name)
Eina_Bool	elm_fileselector_custom_filter_append (Evas_Object obj, Elm_Fileselector_Filter_Func func, void data, const char *filter_name)
void	elm_fileselector_filters_clear (Evas_Object *obj)
void	elm_fileselector_hidden_visible_set (Evas_Object *obj, Eina_Bool visible)
Eina_Bool	elm_fileselector_hidden_visible_get (const Evas_Object *obj)
void	elm_fileselector_thumbnail_size_set (Evas_Object *obj, Evas_Coord w, Evas_Coord h)
void	elm_fileselector_thumbnail_size_get (const Evas_Object obj, Evas_Coord w, Evas_Coord *h)
Elm_Fileselector_Sort	elm_fileselector_sort_method_get (const Evas_Object *obj)
void	elm_fileselector_sort_method_set (Evas_Object *obj, Elm_Fileselector_Sort sort)

Function Documentation

Evas_Object* elm_fileselector_add ( Evas_Object * parent )

Add a new file selector widget to the given parent Elementary (container) object

Parameters:

parent The parent object

Returns:: a new file selector widget handle or NULL, on errors

This function inserts a new file selector widget on the canvas.

Examples:: fileselector_example.c.

Eina_Bool elm_fileselector_custom_filter_append	(	Evas_Object *	obj,
		Elm_Fileselector_Filter_Func	func,
		void *	data,
		const char *	filter_name
	)

Append custom filter into filter list

Parameters:

obj	The file selector object
func	The function to call when manipulating files and directories.
data	The data to be passed to this `func` call.
filter_name	The name to be displayed, "custom" will be displayed if NULL

Returns:: EINA_TRUE on success, EINA_FALSE on failure.

Note:: first added filter will be the default filter at the moment.

Since (EFL) :: 1.9

Eina_Bool elm_fileselector_expandable_get ( const Evas_Object * obj )

Get whether tree view is enabled for the given file selector widget

Parameters:

obj	The file selector object

Returns:: EINA_TRUE if obj is in tree view, EINA_FALSE otherwise (and or errors)

See also:: elm_fileselector_expandable_set() for more details

Examples:: fileselector_button_example.c, fileselector_entry_example.c, and fileselector_example.c.

void elm_fileselector_expandable_set	(	Evas_Object *	obj,
		Eina_Bool	expand
	)

Enable/disable a tree view in the given file selector widget, if it's in #ELM_FILESELECTOR_LIST mode

Parameters:

obj	The file selector object
expand	`EINA_TRUE` to enable tree view, `EINA_FALSE` to disable

In a tree view, arrows are created on the sides of directories, allowing them to expand in place.

Note:: If it's in other mode, the changes made by this function will only be visible when one switches back to "list" mode.

See also:: elm_fileselector_expandable_get()

Examples:: fileselector_button_example.c, fileselector_entry_example.c, and fileselector_example.c.

void elm_fileselector_filters_clear ( Evas_Object * obj )

Clear all filters registered

Parameters:

obj	The file selector object

Note:: If filter list is empty, file selector assume that all files are matched.

See also:: elm_fileselector_mime_type_filter_append()

Since (EFL) :: 1.8

Eina_Bool elm_fileselector_folder_only_get ( const Evas_Object * obj )

Get whether folder-only view is set for a given file selector widget

Parameters:

obj	The file selector object

Returns:: only EINA_TRUE if obj is only displaying directories, EINA_FALSE if files are being displayed in it too (and on errors)

See also:: elm_fileselector_folder_only_get()

Examples:: fileselector_button_example.c, fileselector_entry_example.c, and fileselector_example.c.

void elm_fileselector_folder_only_set	(	Evas_Object *	obj,
		Eina_Bool	only
	)

Enable/disable folder-only view for a given file selector widget

Parameters:

obj	The file selector object
only	`EINA_TRUE` to make `obj` only display directories, `EINA_FALSE` to make files to be displayed in it too

If enabled, the widget's view will only display folder items, naturally.

See also:: elm_fileselector_folder_only_get()

Examples:: fileselector_button_example.c, fileselector_entry_example.c, and fileselector_example.c.

Eina_Bool elm_fileselector_hidden_visible_get ( const Evas_Object * obj )

Get if hidden files/directories in the file selector widget are visible or not.

Parameters:

obj	The file selector object

Returns:: Visibility of hidden files/directories (EINA_TRUE = enabled/EINA_FALSE = disabled). Default is EINA_FALSE.

See also:: elm_fileselector_hidden_visible_set()

Since (EFL) :: 1.8

void elm_fileselector_hidden_visible_set	(	Evas_Object *	obj,
		Eina_Bool	visible
	)

Enable or disable visibility of hidden files/directories in the file selector widget.

Parameters:

obj	The file selector object
visible	Visibility of hidden files/directories. Default is disabled.

This enables (EINA_TRUE) or disables (EINA_FALSE) visibility of hidden files/directories in the list/grid of the file selector widget.

Since (EFL) :: 1.8

Eina_Bool elm_fileselector_is_save_get ( const Evas_Object * obj )

Get whether the given file selector is in "saving dialog" mode

Parameters:

obj	The file selector object

Returns:: EINA_TRUE, if the file selector is in "saving dialog" mode, EINA_FALSE otherwise (and on errors)

See also:: elm_fileselector_is_save_set() for more details

Examples:: fileselector_button_example.c, fileselector_entry_example.c, and fileselector_example.c.

void elm_fileselector_is_save_set	(	Evas_Object *	obj,
		Eina_Bool	is_save
	)

Enable/disable the file name entry box where the user can type in a name for a file, in a given file selector widget

Parameters:

obj	The file selector object
is_save	`EINA_TRUE` to make the file selector a "saving dialog", `EINA_FALSE` otherwise. Default is `EINA_TRUE`.

Having the entry editable is useful on file saving dialogs on applications, where one gives a file name to save contents to, in a given directory in the system. This custom file name will be reported on the "done" smart callback.

See also:: elm_fileselector_is_save_get()

Examples:: fileselector_button_example.c, fileselector_entry_example.c, and fileselector_example.c.

Eina_Bool elm_fileselector_mime_types_filter_append	(	Evas_Object *	obj,
		const char *	mime_types,
		const char *	filter_name
	)

Append mime types filter into filter list

Parameters:

obj	The file selector object
mime_types	comma(,) separated mime types to be allowed.
filter_name	The name to be displayed, `mime_types` will be displayed if NULL

Returns:: EINA_TRUE on success, EINA_FALSE on failure.

Note:: a sub type of mime can be asterisk(*); mime type filter is only working with efreet now.; first added filter will be the default filter at the moment.

See also:: elm_need_efreet(); elm_fileselector_filters_clear()

Since (EFL) :: 1.8

Elm_Fileselector_Mode elm_fileselector_mode_get ( const Evas_Object * obj )

Get the mode in which a given file selector widget is displaying (layouting) file system entries in its view

Parameters:

obj	The fileselector object

Returns:: The mode in which the fileselector is at

See also:: elm_fileselector_mode_set() for more details

void elm_fileselector_mode_set	(	Evas_Object *	obj,
		Elm_Fileselector_Mode	mode
	)

Set the mode in which a given file selector widget will display (layout) file system entries in its view

Parameters:

obj	The file selector object
mode	The mode of the fileselector, being it one of #ELM_FILESELECTOR_LIST (default) or #ELM_FILESELECTOR_GRID. The first one, naturally, will display the files in a list. The latter will make the widget to display its entries in a grid form.

Note:: By using elm_fileselector_expandable_set(), the user may trigger a tree view for that list.; If Elementary is built with support of the Ethumb thumbnailing library, the second form of view will display preview thumbnails of files which it supports. You must have elm_need_ethumb() called in your Elementary for thumbnailing to work, though.

See also:: elm_fileselector_expandable_set().; elm_fileselector_mode_get().

Examples:: fileselector_example.c.

Eina_Bool elm_fileselector_multi_select_get ( const Evas_Object * obj )

Get if multi-selection in the file selector is enabled or disabled.

Parameters:

obj	The file selector object

Returns:: Multi-select enabled/disabled (EINA_TRUE = enabled/EINA_FALSE = disabled). Default is EINA_FALSE.

See also:: elm_fileselector_multi_select_set()

Since (EFL) :: 1.8

void elm_fileselector_multi_select_set	(	Evas_Object *	obj,
		Eina_Bool	multi
	)

Enable or disable multi-selection in the file selector widget.

Parameters:

obj	The file selector object
multi	Multi-select enable/disable. Default is disabled.

This enables (EINA_TRUE) or disables (EINA_FALSE) multi-selection in the list/grid of the file selector widget. This allows more than 1 item to be selected. To retrieve the list of selected paths, use elm_fileselector_selected_paths_get().

See also:: elm_fileselector_selected_paths_get(); elm_fileselector_multi_select_get()

Since (EFL) :: 1.8

const char* elm_fileselector_path_get ( const Evas_Object * obj )

Get the parent directory's path that a given file selector widget is displaying

Parameters:

obj	The file selector object

Returns:: The (full) path of the directory the file selector is displaying, a stringshared string

See also:: elm_fileselector_path_set()

Examples:: fileselector_example.c.

void elm_fileselector_path_set	(	Evas_Object *	obj,
		const char *	path
	)

Set, programmatically, the directory that a given file selector widget will display contents from

Parameters:

obj	The file selector object
path	The path to display in `obj`

This will change the directory that obj is displaying. It will also clear the text entry area on the obj object, which displays select files' names.

See also:: elm_fileselector_path_get()

Examples:: fileselector_button_example.c, fileselector_entry_example.c, and fileselector_example.c.

const char* elm_fileselector_selected_get ( const Evas_Object * obj )

Get the currently selected item's (full) path, in the given file selector widget

Parameters:

obj	The file selector object

Returns:: The absolute path of the selected item, a stringshared string

Note:: Custom editions on obj object's text entry, if made, will appear on the return string of this function, naturally.

See also:: elm_fileselector_selected_set() for more details

Examples:: fileselector_example.c.

const Eina_List* elm_fileselector_selected_paths_get ( const Evas_Object * obj )

Get a list of selected paths in the file selector.

Parameters:

obj	The file selector object

Returns:: The list of selected paths, or NULL if not in multi-select mode or none are selected.

It returns a list of the selected paths. This list pointer is only valid so long as the selection doesn't change (no items are selected or unselected, or unselected implicitly by deletion). The list contains const char *. The order of the items in this list is the order which they were selected, i.e. the first item in this list is the first item that was selected, and so on.

Note:: If not in multi-select mode, consider using function elm_fileselector_selected_get() instead.

See also:: elm_fileselector_multi_select_set(); elm_fileselector_selected_get()

Since (EFL) :: 1.8

Eina_Bool elm_fileselector_selected_set	(	Evas_Object *	obj,
		const char *	path
	)

Set, programmatically, the currently selected file/directory in the given file selector widget

Parameters:

obj	The file selector object
path	The (full) path to a file or directory

Returns:: EINA_TRUE on success, EINA_FALSE on failure. The latter case occurs if the directory or file pointed to do not exist.

See also:: elm_fileselector_selected_get()

Elm_Fileselector_Sort elm_fileselector_sort_method_get ( const Evas_Object * obj )

Get the sort method of the file selector widget.

Parameters:

obj	The file selector object

Returns:: The sort method

See also:: elm_fileselector_sort_method_set()

Since (EFL) :: 1.9

void elm_fileselector_sort_method_set	(	Evas_Object *	obj,
		Elm_Fileselector_Sort	sort
	)

Set the sort method of the file selector widget.

Parameters:

obj	The file selector object
sort	The sort method

See also:: elm_fileselector_sort_method_get()

Since (EFL) :: 1.9

void elm_fileselector_thumbnail_size_get	(	const Evas_Object *	obj,
		Evas_Coord *	w,
		Evas_Coord *	h
	)

Get the size for the thumbnail of a given file selector widget

Parameters:

obj	The file selector object.
w	Pointer to a variable where to store the thumbnail's width.
h	Pointer to a variable where to store the thumbnail's height.

Note:: Use NULL pointers on the size values you're not interested in: they'll be ignored by the function.

See also:: elm_fileselector_thumbnail_size_set()

Since (EFL) :: 1.9

void elm_fileselector_thumbnail_size_set	(	Evas_Object *	obj,
		Evas_Coord	w,
		Evas_Coord	h
	)

Set the size for the thumbnail of the file selector widget's view.

Parameters:

obj	The file selector object
w	The thumbnail's width.
h	The thumbnail's height.

Note:: If w or h is 0, default value will be used.

See also:: elm_fileselector_thumbnail_size_get()

Since (EFL) :: 1.9

Functions

Function Documentation