2 * @defgroup File_Selector_Entry File Selector Entry
4 * @image html img/widget/fileselector_entry/preview-00.png
5 * @image latex img/widget/fileselector_entry/preview-00.eps
7 * This is an entry made to be filled with or display a <b>file
8 * system path string</b>. Besides the entry itself, the widget has
9 * a @ref File_Selector_Button "file selector button" on its side,
10 * which will raise an internal @ref Fileselector "file selector widget",
11 * when clicked, for path selection aided by file system
14 * This file selector may appear in an Elementary window or in an
15 * inner window. When a file is chosen from it, the (inner) window
16 * is closed and the selected file's path string is exposed both as
17 * an smart event and as the new text on the entry.
19 * This widget encapsulates operations on its internal file
20 * selector on its own API. There is less control over its file
21 * selector than that one would have instatiating one directly.
23 * Smart callbacks one can register to:
24 * - @c "changed" - The text within the entry was changed
25 * - @c "activated" - The entry has had editing finished and
26 * changes are to be "committed"
27 * - @c "press" - The entry has been clicked
28 * - @c "longpressed" - The entry has been clicked (and held) for a
30 * - @c "clicked" - The entry has been clicked
31 * - @c "clicked,double" - The entry has been double clicked
32 * - @c "focused" - The entry has received focus
33 * - @c "unfocused" - The entry has lost focus
34 * - @c "selection,paste" - A paste action has occurred on the
36 * - @c "selection,copy" - A copy action has occurred on the entry
37 * - @c "selection,cut" - A cut action has occurred on the entry
38 * - @c "unpressed" - The file selector entry's button was released
39 * after being pressed.
40 * - @c "file,chosen" - The user has selected a path via the file
41 * selector entry's internal file selector, whose string pointer
42 * comes as the @c event_info data (a stringshared string)
44 * Here is an example on its usage:
45 * @li @ref fileselector_entry_example
47 * @see @ref File_Selector_Button for a similar widget.
52 * Add a new file selector entry widget to the given parent
53 * Elementary (container) object
55 * @param parent The parent object
56 * @return a new file selector entry widget handle or @c NULL, on
60 elm_fileselector_entry_add(Evas_Object *parent)
64 * Set the label for a given file selector entry widget's button
66 * @param obj The file selector entry widget
67 * @param label The text label to be displayed on @p obj widget's
70 * @deprecated use elm_object_text_set() instead.
72 EINA_DEPRECATED EAPI void elm_fileselector_entry_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
75 * Get the label set for a given file selector entry widget's button
77 * @param obj The file selector entry widget
78 * @return The widget button's label
80 * @deprecated use elm_object_text_set() instead.
82 EINA_DEPRECATED EAPI const char *elm_fileselector_entry_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
85 * Set the icon on a given file selector entry widget's button
87 * @param obj The file selector entry widget
88 * @param icon The icon object for the entry's button
90 * Once the icon object is set, a previously set one will be
91 * deleted. If you want to keep the latter, use the
92 * elm_fileselector_entry_button_icon_unset() function.
94 * @see elm_fileselector_entry_button_icon_get()
96 EAPI void elm_fileselector_entry_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
99 * Get the icon set for a given file selector entry widget's button
101 * @param obj The file selector entry widget
102 * @return The icon object currently set on @p obj widget's button
103 * or @c NULL, if none is
105 * @see elm_fileselector_entry_button_icon_set()
107 EAPI Evas_Object *elm_fileselector_entry_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
110 * Unset the icon used in a given file selector entry widget's
113 * @param obj The file selector entry widget
114 * @return The icon object that was being used on @p obj widget's
115 * button or @c NULL, on errors
117 * Unparent and return the icon object which was set for this
120 * @see elm_fileselector_entry_button_icon_set()
122 EAPI Evas_Object *elm_fileselector_entry_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
125 * Set the title for a given file selector entry widget's window
127 * @param obj The file selector entry widget
128 * @param title The title string
130 * This will change the window's title, when the file selector pops
131 * out after a click on the entry's button. Those windows have the
132 * default (unlocalized) value of @c "Select a file" as titles.
134 * @note It will only take any effect if the file selector
135 * entry widget is @b not under "inwin mode".
137 * @see elm_fileselector_entry_window_title_get()
139 EAPI void elm_fileselector_entry_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
142 * Get the title set for a given file selector entry widget's
145 * @param obj The file selector entry widget
146 * @return Title of the file selector entry's window
148 * @see elm_fileselector_entry_window_title_get() for more details
150 EAPI const char *elm_fileselector_entry_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
153 * Set the size of a given file selector entry widget's window,
154 * holding the file selector itself.
156 * @param obj The file selector entry widget
157 * @param width The window's width
158 * @param height The window's height
160 * @note it will only take any effect if the file selector entry
161 * widget is @b not under "inwin mode". The default size for the
162 * window (when applicable) is 400x400 pixels.
164 * @see elm_fileselector_entry_window_size_get()
166 EAPI void elm_fileselector_entry_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
169 * Get the size of a given file selector entry widget's window,
170 * holding the file selector itself.
172 * @param obj The file selector entry widget
173 * @param width Pointer into which to store the width value
174 * @param height Pointer into which to store the height value
176 * @note Use @c NULL pointers on the size values you're not
177 * interested in: they'll be ignored by the function.
179 * @see elm_fileselector_entry_window_size_set(), for more details
181 EAPI void elm_fileselector_entry_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
184 * Set the initial file system path and the entry's path string for
185 * a given file selector entry widget
187 * @param obj The file selector entry widget
188 * @param path The path string
190 * It must be a <b>directory</b> path, which will have the contents
191 * displayed initially in the file selector's view, when invoked
192 * from @p obj. The default initial path is the @c "HOME"
193 * environment variable's value.
195 * @see elm_fileselector_entry_path_get()
197 EAPI void elm_fileselector_entry_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
200 * Get the entry's path string for a given file selector entry
203 * @param obj The file selector entry widget
204 * @return path The path string
206 * @see elm_fileselector_entry_path_set() for more details
208 EAPI const char *elm_fileselector_entry_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
211 * Enable/disable a tree view in the given file selector entry
212 * widget's internal file selector
214 * @param obj The file selector entry widget
215 * @param value @c EINA_TRUE to enable tree view, @c EINA_FALSE to disable
217 * This has the same effect as elm_fileselector_expandable_set(),
218 * but now applied to a file selector entry's internal file
221 * @note There's no way to put a file selector entry's internal
222 * file selector in "grid mode", as one may do with "pure" file
225 * @see elm_fileselector_expandable_get()
227 EAPI void elm_fileselector_entry_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
230 * Get whether tree view is enabled for the given file selector
231 * entry widget's internal file selector
233 * @param obj The file selector entry widget
234 * @return @c EINA_TRUE if @p obj widget's internal file selector
235 * is in tree view, @c EINA_FALSE otherwise (and or errors)
237 * @see elm_fileselector_expandable_set() for more details
239 EAPI Eina_Bool elm_fileselector_entry_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
242 * Set whether a given file selector entry widget's internal file
243 * selector is to display folders only or the directory contents,
246 * @param obj The file selector entry widget
247 * @param value @c EINA_TRUE to make @p obj widget's internal file
248 * selector only display directories, @c EINA_FALSE to make files
249 * to be displayed in it too
251 * This has the same effect as elm_fileselector_folder_only_set(),
252 * but now applied to a file selector entry's internal file
255 * @see elm_fileselector_folder_only_get()
257 EAPI void elm_fileselector_entry_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
260 * Get whether a given file selector entry widget's internal file
261 * selector is displaying folders only or the directory contents,
264 * @param obj The file selector entry widget
265 * @return @c EINA_TRUE if @p obj widget's internal file
266 * selector is only displaying directories, @c EINA_FALSE if files
267 * are being displayed in it too (and on errors)
269 * @see elm_fileselector_entry_folder_only_set() for more details
271 EAPI Eina_Bool elm_fileselector_entry_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
274 * Enable/disable the file name entry box where the user can type
275 * in a name for a file, in a given file selector entry widget's
276 * internal file selector.
278 * @param obj The file selector entry widget
279 * @param value @c EINA_TRUE to make @p obj widget's internal
280 * file selector a "saving dialog", @c EINA_FALSE otherwise
282 * This has the same effect as elm_fileselector_is_save_set(),
283 * but now applied to a file selector entry's internal file
286 * @see elm_fileselector_is_save_get()
288 EAPI void elm_fileselector_entry_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
291 * Get whether the given file selector entry widget's internal
292 * file selector is in "saving dialog" mode
294 * @param obj The file selector entry widget
295 * @return @c EINA_TRUE, if @p obj widget's internal file selector
296 * is in "saving dialog" mode, @c EINA_FALSE otherwise (and on
299 * @see elm_fileselector_entry_is_save_set() for more details
301 EAPI Eina_Bool elm_fileselector_entry_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
304 * Set whether a given file selector entry widget's internal file
305 * selector will raise an Elementary "inner window", instead of a
306 * dedicated Elementary window. By default, it won't.
308 * @param obj The file selector entry widget
309 * @param value @c EINA_TRUE to make it use an inner window, @c
310 * EINA_TRUE to make it use a dedicated window
312 * @see elm_win_inwin_add() for more information on inner windows
313 * @see elm_fileselector_entry_inwin_mode_get()
315 EAPI void elm_fileselector_entry_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
318 * Get whether a given file selector entry widget's internal file
319 * selector will raise an Elementary "inner window", instead of a
320 * dedicated Elementary window.
322 * @param obj The file selector entry widget
323 * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
324 * if it will use a dedicated window
326 * @see elm_fileselector_entry_inwin_mode_set() for more details
328 EAPI Eina_Bool elm_fileselector_entry_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
331 * Set the initial file system path for a given file selector entry
334 * @param obj The file selector entry widget
335 * @param path The path string
337 * It must be a <b>directory</b> path, which will have the contents
338 * displayed initially in the file selector's view, when invoked
339 * from @p obj. The default initial path is the @c "HOME"
340 * environment variable's value.
342 * @see elm_fileselector_entry_path_get()
344 EAPI void elm_fileselector_entry_selected_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
347 * Get the parent directory's path to the latest file selection on
348 * a given filer selector entry widget
350 * @param obj The file selector object
351 * @return The (full) path of the directory of the last selection
352 * on @p obj widget, a @b stringshared string
354 * @see elm_fileselector_entry_path_set()
356 EAPI const char *elm_fileselector_entry_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);