[elementary] Documenting/exemplifying file selector

entry.



SVN revision: 61403

legacy/elementary/doc/examples.dox

@@ -36,6 +36,10 @@
  * @ref flipselector_example
  *
  * @ref fileselector_example
+ *
+ * @ref fileselector_button_example
+ *
+ * @ref fileselector_entry_example
  */
 
 /**
@@ -1414,6 +1418,8 @@
  * @image html screenshots/clock_example.png
  * @image latex screenshots/clock_example.eps
  *
+ * See the full @ref clock_example_c "source code" for this example.
+ *
  * @example clock_example.c
  */
 
@@ -1471,6 +1477,8 @@
  * @image html screenshots/flipselector_example.png
  * @image latex screenshots/flipselector_example.eps
  *
+ * See the full @ref flipselector_example_c "source code" for this example.
+ *
  * @example flipselector_example.c
  */
 
@@ -1544,6 +1552,8 @@
  * @image html screenshots/fileselector_example.png
  * @image latex screenshots/fileselector_example.eps
  *
+ * See the full @ref fileselector_example_c "source code" for this example.
+ *
  * @example fileselector_example.c
  */
 
@@ -1607,13 +1617,88 @@
  * @image html screenshots/fileselector_button_example_03.png
  * @image latex screenshots/fileselector_button_example_03.eps
  *
- * The other checkboxes there have straightforward meanings. Play with
- * them to get the behavior, their respective API calls on the file
- * selector button where shown in the code.
+ * Play with the checkboxes to get the behavior changes on the file
+ * selector button. The respective API calls on the widget coming from
+ * those knobs where shown in the code already.
+ *
+ * See the full @ref fileselector_button_example_c "source code" for
+ * this example.
  *
  * @example fileselector_button_example.c
  */
 
+/**
+ * @page fileselector_entry_example File selector entry widget example
+ *
+ * This code places an Elementary file selector entry widget on a
+ * window, along with some other checkboxes. Those are there just as
+ * knobs on the file selector entry's state.
+ *
+ * Here's how we instantiate it:
+ * @dontinclude fileselector_entry_example.c
+ * @skip ic = elm_icon_add
+ * @until evas_object_show
+ *
+ * Note that we set on it's button both icon and label
+ * decorations. It's set to exhibit the path of (and list the contents
+ * of, when internal file selector is launched) the @c "/tmp"
+ * directory, also, with elm_fileselector_entry_path_set(). What
+ * follows are checkboxes to exercise some of its API funtions:
+ * @dontinclude fileselector_entry_example.c
+ * @skip ck = elm_check_add
+ * @until callback_add(fs_entry
+ *
+ * The checkboxes will toggle whether the file selector entry's
+ * internal file selector:
+ * - must have an editable text entry for file names (thus, be in
+ *   "save dialog mode")
+ * - is to be raised as an "inner window" (note it's the default
+ *   behavior) or as a dedicated window
+ * - is to populate its view with folders only
+ * - is to expand its folders, in its view, <b>in place</b>, and not
+ *   repainting it entirely just with the contents of a sole
+ *   directory.
+ *
+ * Observe how the entry's text will match the string coming from the
+ * @c "file,chosen" smart event:
+ * @dontinclude fileselector_entry_example.c
+ * @skip hook on the
+ * @until }
+ * Whenever you dismiss or acknowledges the file selector, after it's
+ * raised, the @c event_info string will contain the last selection on
+ * it (if any was made).
+ *
+ * Try, also, to type in a valid system path and, then, open the file
+ * selector's window: it will start the file browsing there, for you.
+ *
+ * This is how the example, just after called, should look like:
+ * @image html screenshots/fileselector_entry_example_00.png
+ * @image latex screenshots/fileselector_entry_example_00.eps
+ *
+ * Click on the file selector entry to raise its internal file
+ * selector, which will be contained on an <b>"inner window"</b>:
+ * @image html screenshots/fileselector_entry_example_01.png
+ * @image latex screenshots/fileselector_entry_example_01.eps
+ *
+ * Toggle the "inwin mode" switch off and, if you click on the file
+ * selector entry again, you'll get @b two windows, the original one
+ * (note the last selection there!)
+ * @image html screenshots/fileselector_entry_example_02.png
+ * @image latex screenshots/fileselector_entry_example_02.eps
+ * and the file selector's new one
+ * @image html screenshots/fileselector_entry_example_03.png
+ * @image latex screenshots/fileselector_entry_example_03.eps
+ *
+ * Play with the checkboxes to get the behavior changes on the file
+ * selector entry. The respective API calls on the widget coming from
+ * those knobs where shown in the code already.
+ *
+ * See the full @ref fileselector_entry_example_c "source code" for
+ * this example.
+ *
+ * @example fileselector_entry_example.c
+ */
+
 /**
  * @page tutorial_hover Hover example
  * @dontinclude hover_example_01.c
@@ -1940,3 +2025,33 @@
  * @include general_funcs_example.c
  * @example general_funcs_example.c
  */
+
+/**
+ * @page clock_example_c Clock example
+ * @include clock_example.c
+ * @example clock_example.c
+ */
+
+/**
+ * @page flipselector_example_c Flipselector example
+ * @include flipselector_example.c
+ * @example flipselector_example.c
+ */
+
+/**
+ * @page fileselector_example_c Fileselector example
+ * @include fileselector_example.c
+ * @example fileselector_example.c
+ */
+
+/**
+ * @page fileselector_button_example_c Fileselector button example
+ * @include fileselector_button_example.c
+ * @example fileselector_button_example.c
+ */
+
+/**
+ * @page fileselector_entry_example_c Fileselector entry example
+ * @include fileselector_entry_example.c
+ * @example fileselector_entry_example.c
+ */

legacy/elementary/src/examples/Makefile.am

@@ -61,6 +61,7 @@ SRCS = \
 	flipselector_example.c \
 	fileselector_example.c \
 	fileselector_button_example.c \
+	fileselector_entry_example.c \
 	theme_example.edc
 
 pkglib_PROGRAMS =
@@ -114,6 +115,7 @@ pkglib_PROGRAMS += \
 	flipselector_example \
 	fileselector_example \
 	fileselector_button_example \
+	fileselector_entry_example \
 	theme_example.edj
 
 # This variable will hold the list of screenshots that will be made

legacy/elementary/src/examples/fileselector_entry_example.c

@@ -0,0 +1,174 @@
+/**
+ * Simple Elementary's <b>file selector entry widget</b> example,
+ * illustrating its usage and API.
+ *
+ * See stdout/stderr for output. Compile with:
+ *
+ * @verbatim
+ * gcc -g `pkg-config --cflags --libs elementary` file selector_entry_example.c -o file selector_entry_example
+ * @endverbatim
+ */
+
+#include <Elementary.h>
+#ifdef HAVE_CONFIG_H
+# include "elementary_config.h"
+#else
+# define __UNUSED__
+#endif
+
+static void
+_on_done(void        *data __UNUSED__,
+         Evas_Object *obj __UNUSED__,
+         void        *event_info __UNUSED__)
+{
+   elm_exit();
+}
+
+/* hook on the sole smart callback */
+static void
+_file_chosen(void        *data __UNUSED__,
+             Evas_Object *obj __UNUSED__,
+             void        *event_info)
+{
+   const char *file = event_info;
+
+   if (file)
+     printf("File chosen: %s\n", file);
+   else
+     printf("File selection canceled.\n");
+}
+
+/* toggle inwin mode */
+static void
+_inwin_mode_toggle(void        *data,
+                   Evas_Object *obj __UNUSED__,
+                   void        *event_info __UNUSED__)
+{
+   Evas_Object *fs_entry = data;
+   Eina_Bool old_val = elm_fileselector_entry_inwin_mode_get(fs_entry);
+
+   elm_fileselector_entry_inwin_mode_set(fs_entry, !old_val);
+   printf("Inwin mode set to: %s\n", old_val ? "false" : "true");
+}
+
+static void
+_current_sel_toggle(void        *data,
+                    Evas_Object *obj __UNUSED__,
+                    void        *event_info __UNUSED__)
+{
+   Evas_Object *fs_entry = data;
+   Eina_Bool old_val = elm_fileselector_entry_is_save_get(fs_entry);
+   elm_fileselector_entry_is_save_set(fs_entry, !old_val);
+
+   printf("%s text entry with selected item's name\n",
+          old_val ? "Disabling" : "Enabling");
+}
+
+static void
+_folder_only_toggle(void        *data,
+                    Evas_Object *obj __UNUSED__,
+                    void        *event_info __UNUSED__)
+{
+   Evas_Object *fs_entry = data;
+   Eina_Bool old_val = elm_fileselector_entry_folder_only_get(fs_entry);
+   elm_fileselector_entry_folder_only_set(fs_entry, !old_val);
+
+   printf("Folder only mode set to: %s\n", old_val ? "false" : "true");
+}
+
+static void
+_expandable_toggle(void        *data,
+                   Evas_Object *obj __UNUSED__,
+                   void        *event_info __UNUSED__)
+{
+   Evas_Object *fs_entry = data;
+   Eina_Bool old_val = elm_fileselector_entry_expandable_get(fs_entry);
+   elm_fileselector_entry_expandable_set(fs_entry, !old_val);
+
+   printf("Expandable folders mode set to: %s\n", old_val ? "false" : "true");
+}
+
+EAPI int
+elm_main(int    argc __UNUSED__,
+         char **argv __UNUSED__)
+{
+   Evas_Object *win, *bg, *vbox, *hbox, *ic, *ck, *fs_entry, *sep;
+
+   win = elm_win_add(NULL, "fileselector-entry", ELM_WIN_BASIC);
+   elm_win_title_set(win, "File Selector Entry Example");
+   evas_object_smart_callback_add(win, "delete,request", _on_done, NULL);
+
+   bg = elm_bg_add(win);
+   elm_win_resize_object_add(win, bg);
+   evas_object_size_hint_weight_set(bg, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_show(bg);
+
+   vbox = elm_box_add(win);
+   elm_win_resize_object_add(win, vbox);
+   evas_object_size_hint_weight_set(vbox, EVAS_HINT_EXPAND, EVAS_HINT_EXPAND);
+   evas_object_show(vbox);
+
+   ic = elm_icon_add(win);
+   elm_icon_standard_set(ic, "file");
+   evas_object_size_hint_aspect_set(ic, EVAS_ASPECT_CONTROL_VERTICAL, 1, 1);
+
+   /* file selector entry */
+   fs_entry = elm_fileselector_entry_add(win);
+   evas_object_size_hint_align_set(fs_entry, EVAS_HINT_FILL, 0);
+   elm_fileselector_entry_path_set(fs_entry, "/tmp");
+   elm_object_text_set(fs_entry, "Select a file");
+   elm_fileselector_entry_button_icon_set(fs_entry, ic);
+
+   elm_box_pack_end(vbox, fs_entry);
+   evas_object_show(fs_entry);
+   evas_object_show(ic);
+
+   /* attribute setting knobs */
+   sep = elm_separator_add(win);
+   elm_separator_horizontal_set(sep, EINA_TRUE);
+   elm_box_pack_end(vbox, sep);
+   evas_object_show(sep);
+
+   hbox = elm_box_add(win);
+   elm_box_horizontal_set(hbox, EINA_TRUE);
+   elm_box_pack_end(vbox, hbox);
+   evas_object_show(hbox);
+
+   ck = elm_check_add(win);
+   elm_object_text_set(ck, "editable selection");
+   elm_check_state_set(ck, elm_fileselector_entry_is_save_get(fs_entry));
+   evas_object_smart_callback_add(ck, "changed", _current_sel_toggle, fs_entry);
+   elm_box_pack_end(hbox, ck);
+   evas_object_show(ck);
+
+   ck = elm_check_add(win);
+   elm_object_text_set(ck, "\"inwin\" mode");
+   elm_check_state_set(ck, elm_fileselector_entry_inwin_mode_get(fs_entry));
+   evas_object_smart_callback_add(ck, "changed", _inwin_mode_toggle, fs_entry);
+   elm_box_pack_end(hbox, ck);
+   evas_object_show(ck);
+
+   ck = elm_check_add(win);
+   elm_object_text_set(ck, "folders only");
+   elm_check_state_set(ck, elm_fileselector_entry_folder_only_get(fs_entry));
+   evas_object_smart_callback_add(ck, "changed", _folder_only_toggle, fs_entry);
+   elm_box_pack_end(hbox, ck);
+   evas_object_show(ck);
+
+   ck = elm_check_add(win);
+   elm_object_text_set(ck, "expandable");
+   elm_check_state_set(ck, elm_fileselector_entry_expandable_get(fs_entry));
+   evas_object_smart_callback_add(ck, "changed", _expandable_toggle, fs_entry);
+   elm_box_pack_end(hbox, ck);
+   evas_object_show(ck);
+
+   evas_object_smart_callback_add(fs_entry, "file,chosen", _file_chosen, NULL);
+
+   evas_object_resize(win, 400, 400);
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+
+ELM_MAIN()

legacy/elementary/src/lib/Elementary.h.in

@@ -3171,29 +3171,363 @@ extern "C" {
     * @}
     */
 
+    /**
+    * @defgroup File_Selector_Entry File Selector Entry
+    *
+    * This is an entry made to be filled with or display a <b>file
+    * system path string</b>. Besides the entry itself, the widget has
+    * a @ref File_Selector_Button "file selector button" on its side,
+    * which will raise an internal @ref Fileselector "file selector widget",
+    * when clicked, for path selection aided by file system
+    * navigation.
+    *
+    * This file selector may appear in an Elementary window or in an
+    * inner window. When a file is chosen from it, the (inner) window
+    * is closed and the selected file's path string is exposed both as
+    * an smart event and as the new text on the entry.
+    *
+    * This widget encapsulates operations on its internal file
+    * selector on its own API. There is less control over its file
+    * selector than that one would have instatiating one directly.
+    *
+    * Smart callbacks one can register to:
+    * - @c "changed" - The text within the entry was changed
+    * - @c "activated" - The entry has had editing finished and
+    *   changes are to be "committed"
+    * - @c "press" - The entry has been clicked
+    * - @c "longpressed" - The entry has been clicked (and held) for a
+    *   couple seconds
+    * - @c "clicked" - The entry has been clicked
+    * - @c "clicked,double" - The entry has been double clicked
+    * - @c "focused" - The entry has received focus
+    * - @c "unfocused" - The entry has lost focus
+    * - @c "selection,paste" - A paste action has occurred on the
+    *   entry
+    * - @c "selection,copy" - A copy action has occurred on the entry
+    * - @c "selection,cut" - A cut action has occurred on the entry
+    * - @c "unpressed" - The file selector entry's button was released
+    *   after being pressed.
+    * - @c "file,chosen" - The user has selected a path via the file
+    *   selector entry's internal file selector, whose string pointer
+    *   comes as the @c event_info data (a stringshared string)
+    *
+    * Here is an example on its usage:
+    * @li @ref fileselector_entry_example
+    *
+    * @see @ref File_Selector_Button for a similar widget.
+    * @{
+    */
+
+   /**
+    * Add a new file selector entry widget to the given parent
+    * Elementary (container) object
+    *
+    * @param parent The parent object
+    * @return a new file selector entry widget handle or @c NULL, on
+    * errors
+    */
    EAPI Evas_Object *elm_fileselector_entry_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the label for a given file selector entry widget's button
+    *
+    * @param obj The file selector entry widget
+    * @param label The text label to be displayed on @p obj widget's
+    * button
+    *
+    * @deprecated use elm_object_text_set() instead.
+    */
    EINA_DEPRECATED EAPI void         elm_fileselector_entry_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the label set for a given file selector entry widget's button
+    *
+    * @param obj The file selector entry widget
+    * @return The widget button's label
+    *
+    * @deprecated use elm_object_text_set() instead.
+    */
    EINA_DEPRECATED EAPI const char  *elm_fileselector_entry_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the icon on a given file selector entry widget's button
+    *
+    * @param obj The file selector entry widget
+    * @param icon The icon object for the entry's button
+    *
+    * Once the icon object is set, a previously set one will be
+    * deleted. If you want to keep the latter, use the
+    * elm_fileselector_entry_button_icon_unset() function.
+    *
+    * @see elm_fileselector_entry_button_icon_get()
+    */
    EAPI void         elm_fileselector_entry_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the icon set for a given file selector entry widget's button
+    *
+    * @param obj The file selector entry widget
+    * @return The icon object currently set on @p obj widget's button
+    * or @c NULL, if none is
+    *
+    * @see elm_fileselector_entry_button_icon_set()
+    */
    EAPI Evas_Object *elm_fileselector_entry_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Unset the icon used in a given file selector entry widget's
+    * button
+    *
+    * @param obj The file selector entry widget
+    * @return The icon object that was being used on @p obj widget's
+    * button or @c NULL, on errors
+    *
+    * Unparent and return the icon object which was set for this
+    * widget's button.
+    *
+    * @see elm_fileselector_entry_button_icon_set()
+    */
    EAPI Evas_Object *elm_fileselector_entry_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the title for a given file selector entry widget's window
+    *
+    * @param obj The file selector entry widget
+    * @param title The title string
+    *
+    * This will change the window's title, when the file selector pops
+    * out after a click on the entry's button. Those windows have the
+    * default (unlocalized) value of @c "Select a file" as titles.
+    *
+    * @note It will only take any effect if the file selector
+    * entry widget is @b not under "inwin mode".
+    *
+    * @see elm_fileselector_entry_window_title_get()
+    */
    EAPI void         elm_fileselector_entry_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the title set for a given file selector entry widget's
+    * window
+    *
+    * @param obj The file selector entry widget
+    * @return Title of the file selector entry's window
+    *
+    * @see elm_fileselector_entry_window_title_get() for more details
+    */
    EAPI const char  *elm_fileselector_entry_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the size of a given file selector entry widget's window,
+    * holding the file selector itself.
+    *
+    * @param obj The file selector entry widget
+    * @param width The window's width
+    * @param height The window's height
+    *
+    * @note it will only take any effect if the file selector entry
+    * widget is @b not under "inwin mode". The default size for the
+    * window (when applicable) is 400x400 pixels.
+    *
+    * @see elm_fileselector_entry_window_size_get()
+    */
    EAPI void         elm_fileselector_entry_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the size of a given file selector entry widget's window,
+    * holding the file selector itself.
+    *
+    * @param obj The file selector entry widget
+    * @param width Pointer into which to store the width value
+    * @param height Pointer into which to store the height value
+    *
+    * @note Use @c NULL pointers on the size values you're not
+    * interested in: they'll be ignored by the function.
+    *
+    * @see elm_fileselector_entry_window_size_set(), for more details
+    */
    EAPI void         elm_fileselector_entry_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the initial file system path and the entry's path string for
+    * a given file selector entry widget
+    *
+    * @param obj The file selector entry widget
+    * @param path The path string
+    *
+    * It must be a <b>directory</b> path, which will have the contents
+    * displayed initially in the file selector's view, when invoked
+    * from @p obj. The default initial path is the @c "HOME"
+    * environment variable's value.
+    *
+    * @see elm_fileselector_entry_path_get()
+    */
    EAPI void         elm_fileselector_entry_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the entry's path string for a given file selector entry
+    * widget
+    *
+    * @param obj The file selector entry widget
+    * @return path The path string
+    *
+    * @see elm_fileselector_entry_path_set() for more details
+    */
    EAPI const char  *elm_fileselector_entry_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Enable/disable a tree view in the given file selector entry
+    * widget's internal file selector
+    *
+    * @param obj The file selector entry widget
+    * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
+    * disable
+    *
+    * This has the same effect as elm_fileselector_expandable_set(),
+    * but now applied to a file selector entry's internal file
+    * selector.
+    *
+    * @note There's no way to put a file selector entry's internal
+    * file selector in "grid mode", as one may do with "pure" file
+    * selectors.
+    *
+    * @see elm_fileselector_expandable_get()
+    */
    EAPI void         elm_fileselector_entry_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get whether tree view is enabled for the given file selector
+    * entry widget's internal file selector
+    *
+    * @param obj The file selector entry widget
+    * @return @c EINA_TRUE if @p obj widget's internal file selector
+    * is in tree view, @c EINA_FALSE otherwise (and or errors)
+    *
+    * @see elm_fileselector_expandable_set() for more details
+    */
    EAPI Eina_Bool    elm_fileselector_entry_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set whether a given file selector entry widget's internal file
+    * selector is to display folders only or the directory contents,
+    * as well.
+    *
+    * @param obj The file selector entry widget
+    * @param only @c EINA_TRUE to make @p obj widget's internal file
+    * selector only display directories, @c EINA_FALSE to make files
+    * to be displayed in it too
+    *
+    * This has the same effect as elm_fileselector_folder_only_set(),
+    * but now applied to a file selector entry's internal file
+    * selector.
+    *
+    * @see elm_fileselector_folder_only_get()
+    */
    EAPI void         elm_fileselector_entry_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get whether a given file selector entry widget's internal file
+    * selector is displaying folders only or the directory contents,
+    * as well.
+    *
+    * @param obj The file selector entry widget
+    * @return @c EINA_TRUE if @p obj widget's internal file
+    * selector is only displaying directories, @c EINA_FALSE if files
+    * are being displayed in it too (and on errors)
+    *
+    * @see elm_fileselector_entry_folder_only_set() for more details
+    */
    EAPI Eina_Bool    elm_fileselector_entry_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Enable/disable the file name entry box where the user can type
+    * in a name for a file, in a given file selector entry widget's
+    * internal file selector.
+    *
+    * @param obj The file selector entry widget
+    * @param is_save @c EINA_TRUE to make @p obj widget's internal
+    * file selector a "saving dialog", @c EINA_FALSE otherwise
+    *
+    * This has the same effect as elm_fileselector_is_save_set(),
+    * but now applied to a file selector entry's internal file
+    * selector.
+    *
+    * @see elm_fileselector_is_save_get()
+    */
    EAPI void         elm_fileselector_entry_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get whether the given file selector entry widget's internal
+    * file selector is in "saving dialog" mode
+    *
+    * @param obj The file selector entry widget
+    * @return @c EINA_TRUE, if @p obj widget's internal file selector
+    * is in "saving dialog" mode, @c EINA_FALSE otherwise (and on
+    * errors)
+    *
+    * @see elm_fileselector_entry_is_save_set() for more details
+    */
    EAPI Eina_Bool    elm_fileselector_entry_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set whether a given file selector entry widget's internal file
+    * selector will raise an Elementary "inner window", instead of a
+    * dedicated Elementary window. By default, it won't.
+    *
+    * @param obj The file selector entry widget
+    * @param value @c EINA_TRUE to make it use an inner window, @c
+    * EINA_TRUE to make it use a dedicated window
+    *
+    * @see elm_win_inwin_add() for more information on inner windows
+    * @see elm_fileselector_entry_inwin_mode_get()
+    */
    EAPI void         elm_fileselector_entry_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get whether a given file selector entry widget's internal file
+    * selector will raise an Elementary "inner window", instead of a
+    * dedicated Elementary window.
+    *
+    * @param obj The file selector entry widget
+    * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
+    * if it will use a dedicated window
+    *
+    * @see elm_fileselector_entry_inwin_mode_set() for more details
+    */
    EAPI Eina_Bool    elm_fileselector_entry_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the initial file system path for a given file selector entry
+    * widget
+    *
+    * @param obj The file selector entry widget
+    * @param path The path string
+    *
+    * It must be a <b>directory</b> path, which will have the contents
+    * displayed initially in the file selector's view, when invoked
+    * from @p obj. The default initial path is the @c "HOME"
+    * environment variable's value.
+    *
+    * @see elm_fileselector_entry_path_get()
+    */
    EAPI void         elm_fileselector_entry_selected_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the parent directory's path to the latest file selection on
+    * a given filer selector entry widget
+    *
+    * @param obj The file selector object
+    * @return The (full) path of the directory of the last selection
+    * on @p obj widget, a @b stringshared string
+    *
+    * @see elm_fileselector_entry_path_set()
+    */
    EAPI const char  *elm_fileselector_entry_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 
+   /**
+    * @}
+    */
+
    /* scroller policy */
    typedef enum _Elm_Scroller_Policy
      {

legacy/elementary/src/lib/elc_fileselector_entry.c

@@ -1,18 +1,6 @@
 #include <Elementary.h>
 #include "elm_priv.h"
 
- /**
- * @defgroup File_Selector_Entry File Selector Entry
- *
- * An entry that shows to enter/display path and have an associated
- * button to allow selecting the file from a dialog.
- *
- * The button, when clicked, creates an Elementary window (or inner
- * window) with an Elementary File Selector within. When a file is
- * chosen, the (inner) window is closed and the selected file is
- * exposed as an evas_object_smart_callback_call() of the button.
- */
-
 typedef struct _Widget_Data Widget_Data;
 
 struct _Widget_Data
@@ -232,14 +220,6 @@ _elm_fileselector_entry_button_label_get(const Evas_Object *obj, const char *ite
    return elm_object_text_get(wd->button);
 }
 
-/**
- * Add a new file selector entry into the parent object.
- *
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- *
- * @ingroup File_Selector_Entry
- */
 EAPI Evas_Object *
 elm_fileselector_entry_add(Evas_Object *parent)
 {
@@ -318,15 +298,6 @@ elm_fileselector_entry_add(Evas_Object *parent)
    return obj;
 }
 
-/**
- * Set the label used in the file selector entry.
- *
- * @param obj The entry object
- * @param label The text label text to be displayed on the entry
- *
- * @ingroup File_Selector_Entry
- * @deprecated use elm_object_text_set() instead.
- */
 EAPI void
 elm_fileselector_entry_button_label_set(Evas_Object *obj, const char *label)
 {
@@ -339,16 +310,6 @@ elm_fileselector_entry_button_label_get(const Evas_Object *obj)
    return _elm_fileselector_entry_button_label_get(obj, NULL);
 }
 
-/**
- * Set the path to start the entry's file selector with, when clicked.
- *
- * @param obj The entry object
- * @param path Path to a file/directory
- *
- * Default path is "HOME" environment variable's value.
- *
- * @ingroup File_Selector_Entry
- */
 EAPI void
 elm_fileselector_entry_selected_set(Evas_Object *obj, const char *path)
 {
@@ -358,16 +319,6 @@ elm_fileselector_entry_selected_set(Evas_Object *obj, const char *path)
    elm_fileselector_button_path_set(wd->button, path);
 }
 
-/**
- * Get the <b>last</b> path which the entry's file selector was set to.
- *
- * @param obj The entry object
- * @param path Path to a file/directory
- *
- * Default path is "HOME" environment variable's value.
- *
- * @ingroup File_Selector_Entry
- */
 EAPI const char *
 elm_fileselector_entry_selected_get(const Evas_Object *obj)
 {
@@ -377,17 +328,6 @@ elm_fileselector_entry_selected_get(const Evas_Object *obj)
    return elm_fileselector_button_path_get(wd->button);
 }
 
-/**
- * Set the title of the file selector entry's window.
- *
- * @param obj The entry object
- * @param title The title string
- *
- * Note that it will only take any effect if the fileselector entry
- * not at "inwin mode".
- *
- * @ingroup File_Selector_Entry
- */
 EAPI void
 elm_fileselector_entry_window_title_set(Evas_Object *obj, const char *title)
 {
@@ -397,13 +337,6 @@ elm_fileselector_entry_window_title_set(Evas_Object *obj, const char *title)
    elm_fileselector_button_window_title_set(wd->button, title);
 }
 
-/**
- * Get the title of the file selector entry's window.
- *
- * @param obj The entry object
- *
- * @ingroup File_Selector_Entry
- */
 EAPI const char *
 elm_fileselector_entry_window_title_get(const Evas_Object *obj)
 {
@@ -413,18 +346,6 @@ elm_fileselector_entry_window_title_get(const Evas_Object *obj)
    return elm_fileselector_button_window_title_get(wd->button);
 }
 
-/**
- * Set the size of the file selector entry's window.
- *
- * @param obj The entry object
- * @param width The width
- * @param height The height
- *
- * Note that it will only take any effect if the fileselector entry not at
- * "inwin mode". Default size for the window (when applicable) is 400x400.
- *
- * @ingroup File_Selector_Entry
- */
 EAPI void
 elm_fileselector_entry_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height)
 {
@@ -434,15 +355,6 @@ elm_fileselector_entry_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_
    elm_fileselector_button_window_size_set(wd->button, width, height);
 }
 
-/**
- * Get the size of the file selector entry's window.
- *
- * @param obj The entry object
- * @param width Pointer into which to store the width value
- * @param height Pointer into which to store the height value
- *
- * @ingroup File_Selector_Entry
- */
 EAPI void
 elm_fileselector_entry_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height)
 {
@@ -452,16 +364,6 @@ elm_fileselector_entry_window_size_get(const Evas_Object *obj, Evas_Coord *width
    elm_fileselector_button_window_size_get(wd->button, width, height);
 }
 
-/**
- * Set the starting path of the file selector entry's window.
- *
- * @param obj The entry object
- * @param path The path string
- *
- * It must be a <b>directory</b> path.
- *
- * @ingroup File_Selector_Entry
- */
 EAPI void
 elm_fileselector_entry_path_set(Evas_Object *obj, const char *path)
 {
@@ -472,13 +374,6 @@ elm_fileselector_entry_path_set(Evas_Object *obj, const char *path)
    elm_entry_entry_set(wd->entry, path);
 }
 
-/**
- * Get the <b>last</b> path of the file selector entry's window.
- *
- * @param obj The entry object
- *
- * @ingroup File_Selector_Entry
- */
 EAPI const char *
 elm_fileselector_entry_path_get(const Evas_Object *obj)
 {
@@ -488,17 +383,6 @@ elm_fileselector_entry_path_get(const Evas_Object *obj)
    return elm_entry_entry_get(wd->entry);
 }
 
-/**
- * Set whether the entry's file selector is to present itself as an
- * Elementary Generic List (which will expand its entries for nested
- * directories) or as canonical list, which will be rendered again
- * with the contents of each selected directory.
- *
- * @param obj The entry object
- * @param value The expandable flag
- *
- * @ingroup File_Selector_Entry
- */
 EAPI void
 elm_fileselector_entry_expandable_set(Evas_Object *obj, Eina_Bool value)
 {
@@ -508,14 +392,6 @@ elm_fileselector_entry_expandable_set(Evas_Object *obj, Eina_Bool value)
    elm_fileselector_button_expandable_set(wd->button, value);
 }
 
-/**
- * Get the entry's file selector expandable flag.
- *
- * @param obj The entry object
- * @return value The expandable flag
- *
- * @ingroup File_Selector_Entry
- */
 EAPI Eina_Bool
 elm_fileselector_entry_expandable_get(const Evas_Object *obj)
 {
@@ -525,15 +401,6 @@ elm_fileselector_entry_expandable_get(const Evas_Object *obj)
    return elm_fileselector_button_expandable_get(wd->button);
 }
 
-/**
- * Set whether the entry's file selector list is to display folders
- * only or the directory contents, as well.
- *
- * @param obj The entry object
- * @param value The "folder only" flag
- *
- * @ingroup File_Selector_Entry
- */
 EAPI void
 elm_fileselector_entry_folder_only_set(Evas_Object *obj, Eina_Bool value)
 {
@@ -543,14 +410,6 @@ elm_fileselector_entry_folder_only_set(Evas_Object *obj, Eina_Bool value)
    elm_fileselector_button_folder_only_set(wd->button, value);
 }
 
-/**
- * Get the entry's file selector "folder only" flag.
- *
- * @param obj The entry object
- * @return value The "folder only" flag
- *
- * @ingroup File_Selector_Entry
- */
 EAPI Eina_Bool
 elm_fileselector_entry_folder_only_get(const Evas_Object *obj)
 {
@@ -560,15 +419,6 @@ elm_fileselector_entry_folder_only_get(const Evas_Object *obj)
    return elm_fileselector_button_folder_only_get(wd->button);
 }
 
-/**
- * Set whether the entry's file selector has an editable text entry
- * which will hold its current selection.
- *
- * @param obj The entry object
- * @param value The "is save" flag
- *
- * @ingroup File_Selector_Entry
- */
 EAPI void
 elm_fileselector_entry_is_save_set(Evas_Object *obj, Eina_Bool value)
 {
@@ -578,14 +428,6 @@ elm_fileselector_entry_is_save_set(Evas_Object *obj, Eina_Bool value)
    elm_fileselector_button_is_save_set(wd->button, value);
 }
 
-/**
- * Get the entry's file selector "is save" flag.
- *
- * @param obj The entry object
- * @return value The "is save" flag
- *
- * @ingroup File_Selector_Entry
- */
 EAPI Eina_Bool
 elm_fileselector_entry_is_save_get(const Evas_Object *obj)
 {
@@ -595,16 +437,6 @@ elm_fileselector_entry_is_save_get(const Evas_Object *obj)
    return elm_fileselector_button_is_save_get(wd->button);
 }
 
-/**
- * Set whether the entry's file selector will raise an Elementary
- * Inner Window, instead of a dedicated Elementary Window. By default,
- * it won't.
- *
- * @param obj The entry object
- * @param value The "inwin mode" flag
- *
- * @ingroup File_Selector_Entry
- */
 EAPI void
 elm_fileselector_entry_inwin_mode_set(Evas_Object *obj, Eina_Bool value)
 {
@@ -614,14 +446,6 @@ elm_fileselector_entry_inwin_mode_set(Evas_Object *obj, Eina_Bool value)
    elm_fileselector_button_inwin_mode_set(wd->button, value);
 }
 
-/**
- * Get the entry's file selector "inwin mode" flag.
- *
- * @param obj The entry object
- * @return value The "inwin mode" flag
- *
- * @ingroup File_Selector_Entry
- */
 EAPI Eina_Bool
 elm_fileselector_entry_inwin_mode_get(const Evas_Object *obj)
 {
@@ -631,16 +455,6 @@ elm_fileselector_entry_inwin_mode_get(const Evas_Object *obj)
    return elm_fileselector_button_inwin_mode_get(wd->button);
 }
 
-/**
- * Set the icon used for the entry button
- *
- * Once the icon object is set, a previously set one will be deleted.
- *
- * @param obj The entry object
- * @param icon  The image for the entry
- *
- * @ingroup File_Selector_Entry
- */
 EAPI void
 elm_fileselector_entry_button_icon_set(Evas_Object *obj, Evas_Object *icon)
 {
@@ -650,14 +464,6 @@ elm_fileselector_entry_button_icon_set(Evas_Object *obj, Evas_Object *icon)
    elm_fileselector_button_icon_set(wd->button, icon);
 }
 
-/**
- * Get the icon used for the entry button
- *
- * @param obj The entry object
- * @return The image for the entry
- *
- * @ingroup File_Selector_Entry
- */
 EAPI Evas_Object *
 elm_fileselector_entry_button_icon_get(const Evas_Object *obj)
 {
@@ -667,16 +473,6 @@ elm_fileselector_entry_button_icon_get(const Evas_Object *obj)
    return elm_fileselector_button_icon_get(wd->button);
 }
 
-/**
- * Unset the icon used for the entry button
- *
- * Unparent and return the icon object which was set for this widget.
- *
- * @param obj The entry object
- * @return The icon object that was being used
- *
- * @ingroup File_Selector_Entry
- */
 EAPI Evas_Object *
 elm_fileselector_entry_button_icon_unset(Evas_Object *obj)
 {