2 * @defgroup Fileselector File Selector
4 * @image html img/widget/fileselector/preview-00.png
5 * @image latex img/widget/fileselector/preview-00.eps
7 * A file selector is a widget that allows a user to navigate
8 * through a file system, reporting file selections back via its
11 * It contains shortcut buttons for home directory (@c ~) and to
12 * jump one directory upwards (..), as well as cancel/ok buttons to
13 * confirm/cancel a given selection. After either one of those two
14 * former actions, the file selector will issue its @c "done" smart
17 * There's a text entry on it, too, showing the name of the current
18 * selection. There's the possibility of making it editable, so it
19 * is useful on file saving dialogs on applications, where one
20 * gives a file name to save contents to, in a given directory in
21 * the system. This custom file name will be reported on the @c
22 * "done" smart callback (explained in sequence).
24 * Finally, it has a view to display file system items into in two
29 * If Elementary is built with support of the Ethumb thumbnailing
30 * library, the second form of view will display preview thumbnails
31 * of files which it supports.
33 * Smart callbacks one can register to:
35 * - @c "selected" - the user has clicked on a file (when not in
36 * folders-only mode) or directory (when in folders-only mode)
37 * - @c "directory,open" - the list has been populated with new
38 * content (@c event_info is a pointer to the directory's
39 * path, a @b stringshared string)
40 * - @c "done" - the user has clicked on the "ok" or "cancel"
41 * buttons (@c event_info is a pointer to the selection's
42 * path, a @b stringshared string)
44 * Here is an example on its usage:
45 * @li @ref fileselector_example
49 * @addtogroup Fileselector
54 * Defines how a file selector widget is to layout its contents
55 * (file system entries).
59 ELM_FILESELECTOR_LIST = 0, /**< layout as a list */
60 ELM_FILESELECTOR_GRID, /**< layout as a grid */
61 ELM_FILESELECTOR_LAST /**< sentinel (helper) value, not used */
62 } Elm_Fileselector_Mode;
65 * Add a new file selector widget to the given parent Elementary
68 * @param parent The parent object
69 * @return a new file selector widget handle or @c NULL, on errors
71 * This function inserts a new file selector widget on the canvas.
73 * @ingroup Fileselector
75 EAPI Evas_Object *elm_fileselector_add(Evas_Object *parent);
78 * Enable/disable the file name entry box where the user can type
79 * in a name for a file, in a given file selector widget
81 * @param obj The file selector object
82 * @param is_save @c EINA_TRUE to make the file selector a "saving
83 * dialog", @c EINA_FALSE otherwise
85 * Having the entry editable is useful on file saving dialogs on
86 * applications, where one gives a file name to save contents to,
87 * in a given directory in the system. This custom file name will
88 * be reported on the @c "done" smart callback.
90 * @see elm_fileselector_is_save_get()
92 * @ingroup Fileselector
94 EAPI void elm_fileselector_is_save_set(Evas_Object *obj, Eina_Bool is_save);
97 * Get whether the given file selector is in "saving dialog" mode
99 * @param obj The file selector object
100 * @return @c EINA_TRUE, if the file selector is in "saving dialog"
101 * mode, @c EINA_FALSE otherwise (and on errors)
103 * @see elm_fileselector_is_save_set() for more details
105 * @ingroup Fileselector
107 EAPI Eina_Bool elm_fileselector_is_save_get(const Evas_Object *obj);
110 * Enable/disable folder-only view for a given file selector widget
112 * @param obj The file selector object
113 * @param only @c EINA_TRUE to make @p obj only display
114 * directories, @c EINA_FALSE to make files to be displayed in it
117 * If enabled, the widget's view will only display folder items,
120 * @see elm_fileselector_folder_only_get()
122 * @ingroup Fileselector
124 EAPI void elm_fileselector_folder_only_set(Evas_Object *obj, Eina_Bool only);
127 * Get whether folder-only view is set for a given file selector
130 * @param obj The file selector object
131 * @return only @c EINA_TRUE if @p obj is only displaying
132 * directories, @c EINA_FALSE if files are being displayed in it
133 * too (and on errors)
135 * @see elm_fileselector_folder_only_get()
137 * @ingroup Fileselector
139 EAPI Eina_Bool elm_fileselector_folder_only_get(const Evas_Object *obj);
142 * Enable/disable the "ok" and "cancel" buttons on a given file
145 * @param obj The file selector object
146 * @param buttons @c EINA_TRUE to show buttons, @c EINA_FALSE to hide.
148 * @note A file selector without those buttons will never emit the
149 * @c "done" smart event, and is only usable if one is just hooking
150 * to the other two events.
152 * @see elm_fileselector_buttons_ok_cancel_get()
154 * @ingroup Fileselector
156 EAPI void elm_fileselector_buttons_ok_cancel_set(Evas_Object *obj, Eina_Bool buttons);
159 * Get whether the "ok" and "cancel" buttons on a given file
160 * selector widget are being shown.
162 * @param obj The file selector object
163 * @return @c EINA_TRUE if they are being shown, @c EINA_FALSE
164 * otherwise (and on errors)
166 * @see elm_fileselector_buttons_ok_cancel_set() for more details
168 * @ingroup Fileselector
170 EAPI Eina_Bool elm_fileselector_buttons_ok_cancel_get(const Evas_Object *obj);
173 * Enable/disable a tree view in the given file selector widget,
174 * <b>if it's in @c #ELM_FILESELECTOR_LIST mode</b>
176 * @param obj The file selector object
177 * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
180 * In a tree view, arrows are created on the sides of directories,
181 * allowing them to expand in place.
183 * @note If it's in other mode, the changes made by this function
184 * will only be visible when one switches back to "list" mode.
186 * @see elm_fileselector_expandable_get()
188 * @ingroup Fileselector
190 EAPI void elm_fileselector_expandable_set(Evas_Object *obj, Eina_Bool expand);
193 * Get whether tree view is enabled for the given file selector
196 * @param obj The file selector object
197 * @return @c EINA_TRUE if @p obj is in tree view, @c EINA_FALSE
198 * otherwise (and or errors)
200 * @see elm_fileselector_expandable_set() for more details
202 * @ingroup Fileselector
204 EAPI Eina_Bool elm_fileselector_expandable_get(const Evas_Object *obj);
207 * Set, programmatically, the @b directory that a given file
208 * selector widget will display contents from
210 * @param obj The file selector object
211 * @param path The path to display in @p obj
213 * This will change the @b directory that @p obj is displaying. It
214 * will also clear the text entry area on the @p obj object, which
215 * displays select files' names.
217 * @see elm_fileselector_path_get()
219 * @ingroup Fileselector
221 EAPI void elm_fileselector_path_set(Evas_Object *obj, const char *path);
224 * Get the parent directory's path that a given file selector
225 * widget is displaying
227 * @param obj The file selector object
228 * @return The (full) path of the directory the file selector is
229 * displaying, a @b stringshared string
231 * @see elm_fileselector_path_set()
233 * @ingroup Fileselector
235 EAPI const char *elm_fileselector_path_get(const Evas_Object *obj);
238 * Set, programmatically, the currently selected file/directory in
239 * the given file selector widget
241 * @param obj The file selector object
242 * @param path The (full) path to a file or directory
243 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. The
244 * latter case occurs if the directory or file pointed to do not
247 * @see elm_fileselector_selected_get()
249 * @ingroup Fileselector
251 EAPI Eina_Bool elm_fileselector_selected_set(Evas_Object *obj, const char *path);
254 * Get the currently selected item's (full) path, in the given file
257 * @param obj The file selector object
258 * @return The absolute path of the selected item, a @b
259 * stringshared string
261 * @note Custom editions on @p obj object's text entry, if made,
262 * will appear on the return string of this function, naturally.
264 * @see elm_fileselector_selected_set() for more details
266 * @ingroup Fileselector
268 EAPI const char *elm_fileselector_selected_get(const Evas_Object *obj);
271 * Set the mode in which a given file selector widget will display
272 * (layout) file system entries in its view
274 * @param obj The file selector object
275 * @param mode The mode of the fileselector, being it one of
276 * #ELM_FILESELECTOR_LIST (default) or #ELM_FILESELECTOR_GRID. The
277 * first one, naturally, will display the files in a list. The
278 * latter will make the widget to display its entries in a grid
281 * @note By using elm_fileselector_expandable_set(), the user may
282 * trigger a tree view for that list.
284 * @note If Elementary is built with support of the Ethumb
285 * thumbnailing library, the second form of view will display
286 * preview thumbnails of files which it supports. You must have
287 * elm_need_ethumb() called in your Elementary for thumbnailing to
290 * @see elm_fileselector_expandable_set().
291 * @see elm_fileselector_mode_get().
293 * @ingroup Fileselector
295 EAPI void elm_fileselector_mode_set(Evas_Object *obj, Elm_Fileselector_Mode mode);
298 * Get the mode in which a given file selector widget is displaying
299 * (layouting) file system entries in its view
301 * @param obj The fileselector object
302 * @return The mode in which the fileselector is at
304 * @see elm_fileselector_mode_set() for more details
306 * @ingroup Fileselector
308 EAPI Elm_Fileselector_Mode elm_fileselector_mode_get(const Evas_Object *obj);