[Gengrid] Fixed item_show bug. Merge from opensource r74643.
[framework/uifw/elementary.git] / src / lib / elc_fileselector.h
1 /**
2  * @defgroup Fileselector File Selector
3  * @ingroup Elementary
4  *
5  * @image html img/widget/fileselector/preview-00.png
6  * @image latex img/widget/fileselector/preview-00.eps
7  *
8  * A file selector is a widget that allows a user to navigate
9  * through a file system, reporting file selections back via its
10  * API.
11  *
12  * It contains shortcut buttons for home directory (@c ~) and to
13  * jump one directory upwards (..), as well as cancel/ok buttons to
14  * confirm/cancel a given selection. After either one of those two
15  * former actions, the file selector will issue its @c "done" smart
16  * callback.
17  *
18  * There's a text entry on it, too, showing the name of the current
19  * selection. There's the possibility of making it editable, so it
20  * is useful on file saving dialogs on applications, where one
21  * gives a file name to save contents to, in a given directory in
22  * the system. This custom file name will be reported on the @c
23  * "done" smart callback (explained in sequence).
24  *
25  * Finally, it has a view to display file system items into in two
26  * possible forms:
27  * - list
28  * - grid
29  *
30  * If Elementary is built with support of the Ethumb thumbnailing
31  * library, the second form of view will display preview thumbnails
32  * of files which it supports.
33  *
34  * Smart callbacks one can register to:
35  *
36  * - @c "selected" - the user has clicked on a file (when not in
37  *      folders-only mode) or directory (when in folders-only mode)
38  * - @c "directory,open" - the list has been populated with new
39  *      content (@c event_info is a pointer to the directory's
40  *      path, a @b stringshared string)
41  * - @c "done" - the user has clicked on the "ok" or "cancel"
42  *      buttons (@c event_info is a pointer to the selection's
43  *      path, a @b stringshared string)
44  *
45  * Here is an example on its usage:
46  * @li @ref fileselector_example
47  */
48
49 /**
50  * @addtogroup Fileselector
51  * @{
52  */
53
54 /**
55  * Defines how a file selector widget is to layout its contents
56  * (file system entries).
57  */
58 typedef enum
59 {
60    ELM_FILESELECTOR_LIST = 0, /**< layout as a list */
61    ELM_FILESELECTOR_GRID, /**< layout as a grid */
62    ELM_FILESELECTOR_LAST /**< sentinel (helper) value, not used */
63 } Elm_Fileselector_Mode;
64
65 /**
66  * Add a new file selector widget to the given parent Elementary
67  * (container) object
68  *
69  * @param parent The parent object
70  * @return a new file selector widget handle or @c NULL, on errors
71  *
72  * This function inserts a new file selector widget on the canvas.
73  *
74  * @ingroup Fileselector
75  */
76 EAPI Evas_Object          *elm_fileselector_add(Evas_Object *parent);
77
78 /**
79  * Enable/disable the file name entry box where the user can type
80  * in a name for a file, in a given file selector widget
81  *
82  * @param obj The file selector object
83  * @param is_save @c EINA_TRUE to make the file selector a "saving
84  * dialog", @c EINA_FALSE otherwise
85  *
86  * Having the entry editable is useful on file saving dialogs on
87  * applications, where one gives a file name to save contents to,
88  * in a given directory in the system. This custom file name will
89  * be reported on the @c "done" smart callback.
90  *
91  * @see elm_fileselector_is_save_get()
92  *
93  * @ingroup Fileselector
94  */
95 EAPI void                  elm_fileselector_is_save_set(Evas_Object *obj, Eina_Bool is_save);
96
97 /**
98  * Get whether the given file selector is in "saving dialog" mode
99  *
100  * @param obj The file selector object
101  * @return @c EINA_TRUE, if the file selector is in "saving dialog"
102  * mode, @c EINA_FALSE otherwise (and on errors)
103  *
104  * @see elm_fileselector_is_save_set() for more details
105  *
106  * @ingroup Fileselector
107  */
108 EAPI Eina_Bool             elm_fileselector_is_save_get(const Evas_Object *obj);
109
110 /**
111  * Enable/disable folder-only view for a given file selector widget
112  *
113  * @param obj The file selector object
114  * @param only @c EINA_TRUE to make @p obj only display
115  * directories, @c EINA_FALSE to make files to be displayed in it
116  * too
117  *
118  * If enabled, the widget's view will only display folder items,
119  * naturally.
120  *
121  * @see elm_fileselector_folder_only_get()
122  *
123  * @ingroup Fileselector
124  */
125 EAPI void                  elm_fileselector_folder_only_set(Evas_Object *obj, Eina_Bool only);
126
127 /**
128  * Get whether folder-only view is set for a given file selector
129  * widget
130  *
131  * @param obj The file selector object
132  * @return only @c EINA_TRUE if @p obj is only displaying
133  * directories, @c EINA_FALSE if files are being displayed in it
134  * too (and on errors)
135  *
136  * @see elm_fileselector_folder_only_get()
137  *
138  * @ingroup Fileselector
139  */
140 EAPI Eina_Bool             elm_fileselector_folder_only_get(const Evas_Object *obj);
141
142 /**
143  * Enable/disable the "ok" and "cancel" buttons on a given file
144  * selector widget
145  *
146  * @param obj The file selector object
147  * @param buttons @c EINA_TRUE to show buttons, @c EINA_FALSE to hide.
148  *
149  * @note A file selector without those buttons will never emit the
150  * @c "done" smart event, and is only usable if one is just hooking
151  * to the other two events.
152  *
153  * @see elm_fileselector_buttons_ok_cancel_get()
154  *
155  * @ingroup Fileselector
156  */
157 EAPI void                  elm_fileselector_buttons_ok_cancel_set(Evas_Object *obj, Eina_Bool buttons);
158
159 /**
160  * Get whether the "ok" and "cancel" buttons on a given file
161  * selector widget are being shown.
162  *
163  * @param obj The file selector object
164  * @return @c EINA_TRUE if they are being shown, @c EINA_FALSE
165  * otherwise (and on errors)
166  *
167  * @see elm_fileselector_buttons_ok_cancel_set() for more details
168  *
169  * @ingroup Fileselector
170  */
171 EAPI Eina_Bool             elm_fileselector_buttons_ok_cancel_get(const Evas_Object *obj);
172
173 /**
174  * Enable/disable a tree view in the given file selector widget,
175  * <b>if it's in @c #ELM_FILESELECTOR_LIST mode</b>
176  *
177  * @param obj The file selector object
178  * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
179  * disable
180  *
181  * In a tree view, arrows are created on the sides of directories,
182  * allowing them to expand in place.
183  *
184  * @note If it's in other mode, the changes made by this function
185  * will only be visible when one switches back to "list" mode.
186  *
187  * @see elm_fileselector_expandable_get()
188  *
189  * @ingroup Fileselector
190  */
191 EAPI void                  elm_fileselector_expandable_set(Evas_Object *obj, Eina_Bool expand);
192
193 /**
194  * Get whether tree view is enabled for the given file selector
195  * widget
196  *
197  * @param obj The file selector object
198  * @return @c EINA_TRUE if @p obj is in tree view, @c EINA_FALSE
199  * otherwise (and or errors)
200  *
201  * @see elm_fileselector_expandable_set() for more details
202  *
203  * @ingroup Fileselector
204  */
205 EAPI Eina_Bool             elm_fileselector_expandable_get(const Evas_Object *obj);
206
207 /**
208  * Set, programmatically, the @b directory that a given file
209  * selector widget will display contents from
210  *
211  * @param obj The file selector object
212  * @param path The path to display in @p obj
213  *
214  * This will change the @b directory that @p obj is displaying. It
215  * will also clear the text entry area on the @p obj object, which
216  * displays select files' names.
217  *
218  * @see elm_fileselector_path_get()
219  *
220  * @ingroup Fileselector
221  */
222 EAPI void                  elm_fileselector_path_set(Evas_Object *obj, const char *path);
223
224 /**
225  * Get the parent directory's path that a given file selector
226  * widget is displaying
227  *
228  * @param obj The file selector object
229  * @return The (full) path of the directory the file selector is
230  * displaying, a @b stringshared string
231  *
232  * @see elm_fileselector_path_set()
233  *
234  * @ingroup Fileselector
235  */
236 EAPI const char           *elm_fileselector_path_get(const Evas_Object *obj);
237
238 /**
239  * Set, programmatically, the currently selected file/directory in
240  * the given file selector widget
241  *
242  * @param obj The file selector object
243  * @param path The (full) path to a file or directory
244  * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. The
245  * latter case occurs if the directory or file pointed to do not
246  * exist.
247  *
248  * @see elm_fileselector_selected_get()
249  *
250  * @ingroup Fileselector
251  */
252 EAPI Eina_Bool             elm_fileselector_selected_set(Evas_Object *obj, const char *path);
253
254 /**
255  * Get the currently selected item's (full) path, in the given file
256  * selector widget
257  *
258  * @param obj The file selector object
259  * @return The absolute path of the selected item, a @b
260  * stringshared string
261  *
262  * @note Custom editions on @p obj object's text entry, if made,
263  * will appear on the return string of this function, naturally.
264  *
265  * @see elm_fileselector_selected_set() for more details
266  *
267  * @ingroup Fileselector
268  */
269 EAPI const char           *elm_fileselector_selected_get(const Evas_Object *obj);
270
271 /**
272  * Set the mode in which a given file selector widget will display
273  * (layout) file system entries in its view
274  *
275  * @param obj The file selector object
276  * @param mode The mode of the fileselector, being it one of
277  * #ELM_FILESELECTOR_LIST (default) or #ELM_FILESELECTOR_GRID. The
278  * first one, naturally, will display the files in a list. The
279  * latter will make the widget to display its entries in a grid
280  * form.
281  *
282  * @note By using elm_fileselector_expandable_set(), the user may
283  * trigger a tree view for that list.
284  *
285  * @note If Elementary is built with support of the Ethumb
286  * thumbnailing library, the second form of view will display
287  * preview thumbnails of files which it supports. You must have
288  * elm_need_ethumb() called in your Elementary for thumbnailing to
289  * work, though.
290  *
291  * @see elm_fileselector_expandable_set().
292  * @see elm_fileselector_mode_get().
293  *
294  * @ingroup Fileselector
295  */
296 EAPI void                  elm_fileselector_mode_set(Evas_Object *obj, Elm_Fileselector_Mode mode);
297
298 /**
299  * Get the mode in which a given file selector widget is displaying
300  * (layouting) file system entries in its view
301  *
302  * @param obj The fileselector object
303  * @return The mode in which the fileselector is at
304  *
305  * @see elm_fileselector_mode_set() for more details
306  *
307  * @ingroup Fileselector
308  */
309 EAPI Elm_Fileselector_Mode elm_fileselector_mode_get(const Evas_Object *obj);
310
311 /**
312  * @}
313  */