fileselector Module

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.

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

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

For text, elm_layout_text_set() will work here on:

• 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.fileselector.ELM_FILESELECTOR_LIST

Layout as a list

efl.elementary.fileselector.ELM_FILESELECTOR_GRID

Layout as a grid

class efl.elementary.fileselector.Fileselector

Bases: efl.elementary.layout_class.LayoutClass

This is the class that actually implements the widget.

buttons_ok_cancel

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

callback_activated_add()

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_directory_open_add()

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

callback_done_add()

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

callback_selected_add()

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.

expandable

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

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

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

hidden_visible

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.

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

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

mime_types_filter_append(list mime_types, str 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 :filters_clear()

New in version 1.8.

mode

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

multi_select

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.

path

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

selected

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

Type :string Raises RuntimeError:  when setting the selected file path fails

selected_paths

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.

See also

multi_select selected

New in version 1.8.