summaryrefslogtreecommitdiff
path: root/doc/elementary/fileselector.rst
blob: 96da8c23b8fe86d8f8d9a1fa77880c087e3a0f10 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
.. currentmodule:: efl.elementary

Fileselector
############

.. image:: /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
============

.. _Elm_Fileselector_Mode:

Fileselector modes
------------------

.. data:: ELM_FILESELECTOR_LIST

    Layout as a list

.. data:: ELM_FILESELECTOR_GRID

    Layout as a grid


.. _Elm_Fileselector_Sort:

Fileselector sort method
------------------------

.. data:: ELM_FILESELECTOR_SORT_BY_FILENAME_ASC

    Sort by filename in ascending order

    .. versionadded:: 1.9

.. data:: ELM_FILESELECTOR_SORT_BY_FILENAME_DESC

    Sort by filename in descending order

    .. versionadded:: 1.9

.. data:: ELM_FILESELECTOR_SORT_BY_TYPE_ASC

    Sort by file type in ascending order

    .. versionadded:: 1.9

.. data:: ELM_FILESELECTOR_SORT_BY_TYPE_DESC

    Sort by file type in descending order

    .. versionadded:: 1.9

.. data:: ELM_FILESELECTOR_SORT_BY_SIZE_ASC

    Sort by file size in ascending order

    .. versionadded:: 1.9

.. data:: ELM_FILESELECTOR_SORT_BY_SIZE_DESC

    Sort by file size in descending order

    .. versionadded:: 1.9

.. data:: ELM_FILESELECTOR_SORT_BY_MODIFIED_ASC

    Sort by file modification date in ascending order

    .. versionadded:: 1.9

.. data:: ELM_FILESELECTOR_SORT_BY_MODIFIED_DESC

    Sort by file modification date in descending order

    .. versionadded:: 1.9


Inheritance diagram
===================

.. inheritance-diagram:: Fileselector
    :parts: 2


.. autoclass:: Fileselector