Table Of Contents

Previous topic

Entry

Next topic

Fileselector Button

Fileselector

../_images/fileselector-preview.png

Widget description

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.

Emitted signals

  • activated - the user activated a file. This can happen by double-clicking or pressing Enter key. (event_info is a string with 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)
  • directory,open - the list has been populated with new content (event_info is the directory’s path)
  • done - the user has clicked on the “ok” or “cancel” buttons (event_info is the selection’s path)

Layout text parts

  • ok - OK button label if the ok button is set. (since 1.8)
  • cancel - Cancel button label if the cancel button is set. (since 1.8)

Enumerations

Fileselector modes

efl.elementary.ELM_FILESELECTOR_LIST

Layout as a list

efl.elementary.ELM_FILESELECTOR_GRID

Layout as a grid

Fileselector sort method

efl.elementary.ELM_FILESELECTOR_SORT_BY_FILENAME_ASC

Sort by filename in ascending order

New in version 1.9.

efl.elementary.ELM_FILESELECTOR_SORT_BY_FILENAME_DESC

Sort by filename in descending order

New in version 1.9.

efl.elementary.ELM_FILESELECTOR_SORT_BY_TYPE_ASC

Sort by file type in ascending order

New in version 1.9.

efl.elementary.ELM_FILESELECTOR_SORT_BY_TYPE_DESC

Sort by file type in descending order

New in version 1.9.

efl.elementary.ELM_FILESELECTOR_SORT_BY_SIZE_ASC

Sort by file size in ascending order

New in version 1.9.

efl.elementary.ELM_FILESELECTOR_SORT_BY_SIZE_DESC

Sort by file size in descending order

New in version 1.9.

efl.elementary.ELM_FILESELECTOR_SORT_BY_MODIFIED_ASC

Sort by file modification date in ascending order

New in version 1.9.

efl.elementary.ELM_FILESELECTOR_SORT_BY_MODIFIED_DESC

Sort by file modification date in descending order

New in version 1.9.

Inheritance diagram

class efl.elementary.Fileselector

Bases: efl.elementary.__init__.LayoutClass

This is the class that actually implements the widget.

Parameters:
  • parent (efl.evas.Object) – The parent object
  • **kwargs – All the remaining keyword arguments are interpreted as properties of the instance
buttons_ok_cancel None

Enable/disable the “ok” and “cancel” buttons on a given file selector widget

Note

A file selector without those buttons will never emit the "done" smart event, and is only usable if one is just hooking to the other two events.

Type:bool
buttons_ok_cancel_get()
buttons_ok_cancel_set(buttons)
callback_activated_add(func, *args, **kwargs)

the user activated a file. This can happen by double-clicking or pressing Enter key. (event_info is a string with the activated file path).

callback_activated_del(func)
callback_directory_open_add(func, *args, **kwargs)

The list has been populated with new content (event_info is the directory’s path).

callback_directory_open_del(func)
callback_done_add(func, *args, **kwargs)

The user has clicked on the “ok” or “cancel” buttons (event_info is a string with the selection’s path).

callback_done_del(func)
callback_selected_add(func, *args, **kwargs)

The user has clicked on a file (when not in folders-only mode) or directory (when in folders-only mode). Parameter event_info contains the selected file or directory.

callback_selected_del(func)
current_name None

The name of the file in a save fileselector

Type:string

New in version 1.12.

current_name_get()
current_name_set(name)
custom_filter_append(func, data=None, filter_name=None)

Append custom filter into filter list.

Parameters:
  • func (callable) – The function to call when manipulating files and directories.
  • data – The data to be passed to the function.
  • filter_name (string) – The name to be displayed, “custom” will be displayed if None

Note

filter function signature is: func(path, is_dir, data)

Note

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

Seealso:mime_types_filter_append()
Seealso:filters_clear()

New in version 1.9.

expandable None

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

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.

Type:bool
expandable_get()
expandable_set(expand)
filters_clear()

Clear all filters registered

Note

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

Seealso:mime_types_filter_append()

New in version 1.8.

folder_only None

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

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

Type:bool
folder_only_get()
folder_only_set(folder_only)
hidden_visible None

Visibility of hidden files/directories in the file selector widget.

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

Default is disabled.

Type:bool

New in version 1.8.

hidden_visible_get()
hidden_visible_set(visible)
is_save None

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

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.

Type:bool
is_save_get()
is_save_set(is_save)
mime_types_filter_append(mime_types, filter_name=None)

Append mime types filter into filter list

Parameters:
  • mime_types (list) – mime types to be allowed.
  • filter_name (string) – The name to be displayed, mime_types will be displayed if None
Raises RuntimeWarning:
 

if setting mime_types failed

Note

a sub type of mime can be asterisk(*)

Note

mime type filter is only working with efreet now.

Note

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

Seealso:need_efreet()
Seealso:custom_filter_append()
Seealso:filters_clear()

New in version 1.8.

mode None

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

Note

By using expandable, the user may trigger a tree view for that list.

Note

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.

Seealso:expandable
Type:Fileselector modes
mode_get()
mode_set(mode)
multi_select None

Multi-selection in the file selector widget.

This enables (True) or disables (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 selected_paths.

Type:bool

New in version 1.8.

multi_select_get()
multi_select_set(multi)
path None

The directory that a given file selector widget will display contents from

Setting this will change the directory displayed. It will also clear the text entry area on the object, which displays select files’ names.

Type:string
path_get()
path_set(path)
selected None

The currently selected file/directory in the given file selector widget.

Type:string
Raises RuntimeError:
 when setting the selected file path fails
selected_get()
selected_paths None

A list of selected paths in the file selector.

It returns a list of the selected paths. This list 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 strings. 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 selected instead.

New in version 1.8.

selected_set(path)
sort_method None

The way files are sorted in the fileselector.

Type:Fileselector sort method

New in version 1.9.

sort_method_get()
sort_method_set(method)
thumbnail_size None

The size (in pixels) for the thumbnail images.

Type:tuple (w, h)

New in version 1.9.

thumbnail_size_get()
thumbnail_size_set(w, h)