[elementary] Documenting/exemplifying file selector

button widget.



SVN revision: 61402

legacy/elementary/doc/examples.dox

@@ -1547,6 +1547,73 @@
  * @example fileselector_example.c
  */
 
+/**
+ * @page fileselector_button_example File selector button widget example
+ *
+ * This code places an Elementary file selector button widget on a
+ * window, along with some other checkboxes and a text entry. Those
+ * are there just as knobs on the file selector button's state and to
+ * display information from it.
+ *
+ * Here's how we instantiate it:
+ * @dontinclude fileselector_button_example.c
+ * @skip ic = elm_icon_add
+ * @until evas_object_show
+ *
+ * Note that we set on it both icon and label decorations. It's set to
+ * list the contents of the @c "/tmp" directory, too, with
+ * elm_fileselector_button_path_set(). What follows are checkboxes to
+ * exercise some of its API funtions:
+ * @dontinclude fileselector_button_example.c
+ * @skip ck = elm_check_add
+ * @until evas_object_show(en)
+ *
+ * The checkboxes will toggle whether the file selector button'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.
+ *
+ * The entry labeled @c "Last selection" will exercise the @c
+ * "file,chosen" smart event coming from the file selector button:
+ * @dontinclude fileselector_button_example.c
+ * @skip hook on the
+ * @until toggle inwin
+ *
+ * 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).
+ *
+ * This is how the example, just after called, should look like:
+ * @image html screenshots/fileselector_button_example_00.png
+ * @image latex screenshots/fileselector_button_example_00.eps
+ *
+ * Click on the file selector button to raise its internal file
+ * selector, which will be contained on an <b>"inner window"</b>:
+ * @image html screenshots/fileselector_button_example_01.png
+ * @image latex screenshots/fileselector_button_example_01.eps
+ *
+ * Toggle the "inwin mode" switch off and, if you click on the file
+ * selector button again, you'll get @b two windows, the original one
+ * (note the last selection there!)
+ * @image html screenshots/fileselector_button_example_02.png
+ * @image latex screenshots/fileselector_button_example_02.eps
+ * and the file selector's new one
+ * @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.
+ *
+ * @example fileselector_button_example.c
+ */
+
 /**
  * @page tutorial_hover Hover example
  * @dontinclude hover_example_01.c

legacy/elementary/src/examples/Makefile.am

@@ -60,6 +60,7 @@ SRCS = \
 	image_example_01.c \
 	flipselector_example.c \
 	fileselector_example.c \
+	fileselector_button_example.c \
 	theme_example.edc
 
 pkglib_PROGRAMS =
@@ -112,6 +113,7 @@ pkglib_PROGRAMS += \
 	image_example_01 \
 	flipselector_example \
 	fileselector_example \
+	fileselector_button_example \
 	theme_example.edj
 
 # This variable will hold the list of screenshots that will be made

legacy/elementary/src/examples/fileselector_button_example.c

@@ -0,0 +1,185 @@
+/**
+ * Simple Elementary's <b>file selector button 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_button_example.c -o file selector_button_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();
+}
+
+static void /* hook on the sole smart callback */
+_file_chosen(void            *data,
+             Evas_Object *obj __UNUSED__,
+             void            *event_info)
+{
+   Evas_Object *entry = data;
+   const char *file = event_info;
+   if (file)
+     {
+        elm_entry_entry_set(entry, 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_bt = data;
+   Eina_Bool old_val = elm_fileselector_button_inwin_mode_get(fs_bt);
+
+   elm_fileselector_button_inwin_mode_set(fs_bt, !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_bt = data;
+   Eina_Bool old_val = elm_fileselector_button_is_save_get(fs_bt);
+   elm_fileselector_button_is_save_set(fs_bt, !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_bt = data;
+   Eina_Bool old_val = elm_fileselector_button_folder_only_get(fs_bt);
+   elm_fileselector_button_folder_only_set(fs_bt, !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_bt = data;
+   Eina_Bool old_val = elm_fileselector_button_expandable_get(fs_bt);
+   elm_fileselector_button_expandable_set(fs_bt, !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_bt, *en, *lb, *sep;
+
+   win = elm_win_add(NULL, "fileselector-button", ELM_WIN_BASIC);
+   elm_win_title_set(win, "File Selector Button 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 button */
+   fs_bt = elm_fileselector_button_add(win);
+   elm_fileselector_button_path_set(fs_bt, "/tmp");
+   elm_object_text_set(fs_bt, "Select a file");
+   elm_fileselector_button_icon_set(fs_bt, ic);
+
+   elm_box_pack_end(vbox, fs_bt);
+   evas_object_show(fs_bt);
+   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_button_is_save_get(fs_bt));
+   evas_object_smart_callback_add(ck, "changed", _current_sel_toggle, fs_bt);
+   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_button_inwin_mode_get(fs_bt));
+   evas_object_smart_callback_add(ck, "changed", _inwin_mode_toggle, fs_bt);
+   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_button_folder_only_get(fs_bt));
+   evas_object_smart_callback_add(ck, "changed", _folder_only_toggle, fs_bt);
+   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_button_expandable_get(fs_bt));
+   evas_object_smart_callback_add(ck, "changed", _expandable_toggle, fs_bt);
+   elm_box_pack_end(hbox, ck);
+   evas_object_show(ck);
+
+   lb = elm_label_add(win);
+   elm_object_text_set(lb, "Last selection:");
+   elm_box_pack_end(vbox, lb);
+   evas_object_show(lb);
+
+   en = elm_entry_add(win);
+   elm_entry_line_wrap_set(en, EINA_FALSE);
+   elm_entry_editable_set(en, EINA_FALSE);
+   evas_object_smart_callback_add(fs_bt, "file,chosen", _file_chosen, en);
+   elm_box_pack_end(vbox, en);
+   evas_object_show(en);
+
+   evas_object_resize(win, 400, 400);
+   evas_object_show(win);
+
+   elm_run();
+   return 0;
+}
+
+ELM_MAIN()

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

@@ -2860,36 +2860,315 @@ extern "C" {
     * @}
     */
 
-   /* fileselector */
-   EAPI Evas_Object *elm_fileselector_button_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
-   EINA_DEPRECATED EAPI void         elm_fileselector_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
-   EINA_DEPRECATED EAPI const char  *elm_fileselector_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void         elm_fileselector_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
-   EAPI Evas_Object *elm_fileselector_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI Evas_Object *elm_fileselector_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void         elm_fileselector_button_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
-   EAPI const char  *elm_fileselector_button_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void         elm_fileselector_button_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
-   EAPI void         elm_fileselector_button_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
-   EAPI void         elm_fileselector_button_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
-   EAPI const char  *elm_fileselector_button_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void         elm_fileselector_button_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-   EAPI Eina_Bool    elm_fileselector_button_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void         elm_fileselector_button_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-   EAPI Eina_Bool    elm_fileselector_button_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void         elm_fileselector_button_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-   EAPI Eina_Bool    elm_fileselector_button_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   EAPI void         elm_fileselector_button_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
-   EAPI Eina_Bool    elm_fileselector_button_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
-   /* available styles:
-    * default
-    * anchor
-    * hoversel_vertical
-    * hoversel_vertical_entry
+   /**
+    * @defgroup File_Selector_Button File Selector Button
+    *
+    * This is a button that, when clicked, creates an Elementary
+    * window (or inner window) <b> with a @ref Fileselector "file
+    * selector widget" within</b>. When a file is chosen, the (inner)
+    * window is closed and the button emits a signal having the
+    * selected file as it's @c event_info.
+    *
+    * 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.
+    *
+    * The following styles are available for this button:
+    * @li @c "default"
+    * @li @c "anchor"
+    * @li @c "hoversel_vertical"
+    * @li @c "hoversel_vertical_entry"
+    *
+    * Smart callbacks one can register to:
+    * - @c "file,chosen" - the user has selected a path, whose string
+    *   pointer comes as the @c event_info data (a stringshared
+    *   string)
+    *
+    * Here is an example on its usage:
+    * @li @ref fileselector_button_example
+    *
+    * @see @ref File_Selector_Entry for a similar widget.
+    * @{
     */
-   /* smart callbacks called:
-    * "file,chosen" - the user has selected a path, whose string pointer comes
-                      as event info
+
+   /**
+    * Add a new file selector button widget to the given parent
+    * Elementary (container) object
+    *
+    * @param parent The parent object
+    * @return a new file selector button widget handle or @c NULL, on
+    * errors
+    */
+   EAPI Evas_Object *elm_fileselector_button_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the label for a given file selector button widget
+    *
+    * @param obj The file selector button widget
+    * @param label The text label to be displayed on @p obj
+    *
+    * @deprecated use elm_object_text_set() instead.
+    */
+   EINA_DEPRECATED EAPI void         elm_fileselector_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the label set for a given file selector button widget
+    *
+    * @param obj The file selector button widget
+    * @return The button label
+    *
+    * @deprecated use elm_object_text_set() instead.
+    */
+   EINA_DEPRECATED EAPI const char  *elm_fileselector_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the icon on a given file selector button widget
+    *
+    * @param obj The file selector button widget
+    * @param icon The icon object for the 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_button_icon_unset() function.
+    *
+    * @see elm_fileselector_button_icon_get()
+    */
+   EAPI void         elm_fileselector_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the icon set for a given file selector button widget
+    *
+    * @param obj The file selector button widget
+    * @return The icon object currently set on @p obj or @c NULL, if
+    * none is
+    *
+    * @see elm_fileselector_button_icon_set()
+    */
+   EAPI Evas_Object *elm_fileselector_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Unset the icon used in a given file selector button widget
+    *
+    * @param obj The file selector button widget
+    * @return The icon object that was being used on @p obj or @c
+    * NULL, on errors
+    *
+    * Unparent and return the icon object which was set for this
+    * widget.
+    *
+    * @see elm_fileselector_button_icon_set()
+    */
+   EAPI Evas_Object *elm_fileselector_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the title for a given file selector button widget's window
+    *
+    * @param obj The file selector button widget
+    * @param title The title string
+    *
+    * This will change the window's title, when the file selector pops
+    * out after a click on the 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
+    * button widget is @b not under "inwin mode".
+    *
+    * @see elm_fileselector_button_window_title_get()
+    */
+   EAPI void         elm_fileselector_button_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the title set for a given file selector button widget's
+    * window
+    *
+    * @param obj The file selector button widget
+    * @return Title of the file selector button's window
+    *
+    * @see elm_fileselector_button_window_title_get() for more details
+    */
+   EAPI const char  *elm_fileselector_button_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the size of a given file selector button widget's window,
+    * holding the file selector itself.
+    *
+    * @param obj The file selector button widget
+    * @param width The window's width
+    * @param height The window's height
+    *
+    * @note it will only take any effect if the file selector button
+    * widget is @b not under "inwin mode". The default size for the
+    * window (when applicable) is 400x400 pixels.
+    *
+    * @see elm_fileselector_button_window_size_get()
+    */
+   EAPI void         elm_fileselector_button_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the size of a given file selector button widget's window,
+    * holding the file selector itself.
+    *
+    * @param obj The file selector button 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_button_window_size_set(), for more details
+    */
+   EAPI void         elm_fileselector_button_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set the initial file system path for a given file selector
+    * button widget
+    *
+    * @param obj The file selector button 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_button_path_get()
+    */
+   EAPI void         elm_fileselector_button_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get the initial file system path set for a given file selector
+    * button widget
+    *
+    * @param obj The file selector button widget
+    * @return path The path string
+    *
+    * @see elm_fileselector_button_path_set() for more details
+    */
+   EAPI const char  *elm_fileselector_button_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Enable/disable a tree view in the given file selector button
+    * widget's internal file selector
+    *
+    * @param obj The file selector button 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 button's internal file
+    * selector.
+    *
+    * @note There's no way to put a file selector button's internal
+    * file selector in "grid mode", as one may do with "pure" file
+    * selectors.
+    *
+    * @see elm_fileselector_expandable_get()
+    */
+   EAPI void         elm_fileselector_button_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get whether tree view is enabled for the given file selector
+    * button widget's internal file selector
+    *
+    * @param obj The file selector button 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_button_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set whether a given file selector button widget's internal file
+    * selector is to display folders only or the directory contents,
+    * as well.
+    *
+    * @param obj The file selector button 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 button's internal file
+    * selector.
+    *
+    * @see elm_fileselector_folder_only_get()
+    */
+   EAPI void         elm_fileselector_button_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get whether a given file selector button widget's internal file
+    * selector is displaying folders only or the directory contents,
+    * as well.
+    *
+    * @param obj The file selector button 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_button_folder_only_set() for more details
+    */
+   EAPI Eina_Bool    elm_fileselector_button_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 button widget's
+    * internal file selector.
+    *
+    * @param obj The file selector button 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 button's internal file
+    * selector.
+    *
+    * @see elm_fileselector_is_save_get()
+    */
+   EAPI void         elm_fileselector_button_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get whether the given file selector button widget's internal
+    * file selector is in "saving dialog" mode
+    *
+    * @param obj The file selector button 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_button_is_save_set() for more details
+    */
+   EAPI Eina_Bool    elm_fileselector_button_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * Set whether a given file selector button 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 button 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_button_inwin_mode_get()
+    */
+   EAPI void         elm_fileselector_button_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
+
+   /**
+    * Get whether a given file selector button widget's internal file
+    * selector will raise an Elementary "inner window", instead of a
+    * dedicated Elementary window.
+    *
+    * @param obj The file selector button widget
+    * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
+    * if it will use a dedicated window
+    *
+    * @see elm_fileselector_button_inwin_mode_set() for more details
+    */
+   EAPI Eina_Bool    elm_fileselector_button_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
+
+   /**
+    * @}
     */
 
    EAPI Evas_Object *elm_fileselector_entry_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
@@ -6532,7 +6811,7 @@ extern "C" {
     * widget is displaying
     *
     * @param obj The file selector object
-    * @return The (ful) path of the directory the fileselector is
+    * @return The (full) path of the directory the file selector is
     * displaying, a @b stringshared string
     *
     * @see elm_fileselector_path_set()

legacy/elementary/src/lib/elc_fileselector_button.c

@@ -1,21 +1,6 @@
 #include <Elementary.h>
 #include "elm_priv.h"
 
-/**
- * @defgroup File_Selector_Button File Selector Button
- *
- * A button that, 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.
- *
- * Signals that you can add callbacks for are:
- *
- * "file,chosen" - the user has selected a path, whose string pointer comes
- *                 as event info
- *
- */
-
 typedef struct _Widget_Data Widget_Data;
 
 struct _Widget_Data
@@ -275,14 +260,6 @@ _elm_fileselector_button_label_get(const Evas_Object *obj, const char *item)
    return elm_object_text_get(wd->btn);
 }
 
-/**
- * Add a new file selector button into the parent object.
- *
- * @param parent The parent object
- * @return The new object or NULL if it cannot be created
- *
- * @ingroup File_Selector_Button
- */
 EAPI Evas_Object *
 elm_fileselector_button_add(Evas_Object *parent)
 {
@@ -327,15 +304,6 @@ elm_fileselector_button_add(Evas_Object *parent)
    return obj;
 }
 
-/**
- * Set the label used in the file selector button.
- *
- * @param obj The button object
- * @param label The text label text to be displayed on the button
- *
- * @ingroup File_Selector_Button
- * @deprecated use elm_object_text_set() instead.
- */
 EAPI void
 elm_fileselector_button_label_set(Evas_Object *obj,
                                   const char  *label)
@@ -343,32 +311,12 @@ elm_fileselector_button_label_set(Evas_Object *obj,
    _elm_fileselector_button_label_set(obj, NULL, label);
 }
 
-/**
- * Get the label used in the file selector button.
- *
- * @param obj The button object
- * @return The button label
- *
- * @ingroup File_Selector_Button
- * @deprecated use elm_object_text_set() instead.
- */
 EAPI const char *
 elm_fileselector_button_label_get(const Evas_Object *obj)
 {
    return _elm_fileselector_button_label_get(obj, NULL);
 }
 
-/**
- * Set the title of the file selector button's window.
- *
- * @param obj The button object
- * @param title The title string
- *
- * Note that it will only take any effect if the fileselector button
- * not at "inwin mode".
- *
- * @ingroup File_Selector_Button
- */
 EAPI void
 elm_fileselector_button_window_title_set(Evas_Object *obj,
                                          const char  *title)
@@ -383,14 +331,6 @@ elm_fileselector_button_window_title_set(Evas_Object *obj,
      elm_win_title_set(wd->fsw, wd->window_title);
 }
 
-/**
- * Get the title of the file selector button's window.
- *
- * @param obj The button object
- * @return Title of the file selector button's window
- *
- * @ingroup File_Selector_Button
- */
 EAPI const char *
 elm_fileselector_button_window_title_get(const Evas_Object *obj)
 {
@@ -401,18 +341,6 @@ elm_fileselector_button_window_title_get(const Evas_Object *obj)
    return wd->window_title;
 }
 
-/**
- * Set the size of the file selector button's window.
- *
- * @param obj The button object
- * @param width The width
- * @param height The height
- *
- * Note that it will only take any effect if the fileselector button not at
- * "inwin mode". Default size for the window (when applicable) is 400x400.
- *
- * @ingroup File_Selector_Button
- */
 EAPI void
 elm_fileselector_button_window_size_set(Evas_Object *obj,
                                         Evas_Coord   width,
@@ -429,15 +357,6 @@ elm_fileselector_button_window_size_set(Evas_Object *obj,
      evas_object_resize(wd->fsw, wd->w, wd->h);
 }
 
-/**
- * Get the size of the file selector button's window.
- *
- * @param obj The button object
- * @param width Pointer into which to store the width value
- * @param height Pointer into which to store the height value
- *
- * @ingroup File_Selector_Button
- */
 EAPI void
 elm_fileselector_button_window_size_get(const Evas_Object *obj,
                                         Evas_Coord        *width,
@@ -451,17 +370,6 @@ elm_fileselector_button_window_size_get(const Evas_Object *obj,
    if (height) *height = wd->h;
 }
 
-/**
- * Set the starting path of the file selector button's window.
- *
- * @param obj The button object
- * @param path The path string
- *
- * It must be a <b>directory</b> path.
- * Default path is "HOME" environment variable's value.
- *
- * @ingroup File_Selector_Button
- */
 EAPI void
 elm_fileselector_button_path_set(Evas_Object *obj,
                                  const char  *path)
@@ -476,13 +384,6 @@ elm_fileselector_button_path_set(Evas_Object *obj,
      elm_fileselector_selected_set(wd->fs, wd->fsd.path);
 }
 
-/**
- * Get the <b>last</b> path of the file selector button's window.
- *
- * @param obj The button object
- *
- * @ingroup File_Selector_Button
- */
 EAPI const char *
 elm_fileselector_button_path_get(const Evas_Object *obj)
 {
@@ -492,17 +393,6 @@ elm_fileselector_button_path_get(const Evas_Object *obj)
    return wd->fsd.path;
 }
 
-/**
- * Set whether the button'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 button object
- * @param value The expandable flag
- *
- * @ingroup File_Selector_Button
- */
 EAPI void
 elm_fileselector_button_expandable_set(Evas_Object *obj,
                                        Eina_Bool    value)
@@ -517,14 +407,6 @@ elm_fileselector_button_expandable_set(Evas_Object *obj,
      elm_fileselector_expandable_set(wd->fs, wd->fsd.expandable);
 }
 
-/**
- * Get the button's file selector expandable flag.
- *
- * @param obj The button object
- * @return value The expandable flag
- *
- * @ingroup File_Selector_Button
- */
 EAPI Eina_Bool
 elm_fileselector_button_expandable_get(const Evas_Object *obj)
 {
@@ -535,15 +417,6 @@ elm_fileselector_button_expandable_get(const Evas_Object *obj)
    return wd->fsd.expandable;
 }
 
-/**
- * Set whether the button's file selector list is to display folders
- * only or the directory contents, as well.
- *
- * @param obj The button object
- * @param value The "folder only" flag
- *
- * @ingroup File_Selector_Button
- */
 EAPI void
 elm_fileselector_button_folder_only_set(Evas_Object *obj,
                                         Eina_Bool    value)
@@ -558,14 +431,6 @@ elm_fileselector_button_folder_only_set(Evas_Object *obj,
      elm_fileselector_folder_only_set(wd->fs, wd->fsd.folder_only);
 }
 
-/**
- * Get the button's file selector "folder only" flag.
- *
- * @param obj The button object
- * @return value The "folder only" flag
- *
- * @ingroup File_Selector_Button
- */
 EAPI Eina_Bool
 elm_fileselector_button_folder_only_get(const Evas_Object *obj)
 {
@@ -576,15 +441,6 @@ elm_fileselector_button_folder_only_get(const Evas_Object *obj)
    return wd->fsd.folder_only;
 }
 
-/**
- * Set whether the button's file selector has an editable text entry
- * which will hold its current selection.
- *
- * @param obj The button object
- * @param value The "is save" flag
- *
- * @ingroup File_Selector_Button
- */
 EAPI void
 elm_fileselector_button_is_save_set(Evas_Object *obj,
                                     Eina_Bool    value)
@@ -599,14 +455,6 @@ elm_fileselector_button_is_save_set(Evas_Object *obj,
      elm_fileselector_is_save_set(wd->fs, wd->fsd.is_save);
 }
 
-/**
- * Get the button's file selector "is save" flag.
- *
- * @param obj The button object
- * @return value The "is save" flag
- *
- * @ingroup File_Selector_Button
- */
 EAPI Eina_Bool
 elm_fileselector_button_is_save_get(const Evas_Object *obj)
 {
@@ -617,16 +465,6 @@ elm_fileselector_button_is_save_get(const Evas_Object *obj)
    return wd->fsd.is_save;
 }
 
-/**
- * Set whether the button's file selector will raise an Elementary
- * Inner Window, instead of a dedicated Elementary Window. By default,
- * it won't.
- *
- * @param obj The button object
- * @param value The "inwin mode" flag
- *
- * @ingroup File_Selector_Button
- */
 EAPI void
 elm_fileselector_button_inwin_mode_set(Evas_Object *obj,
                                        Eina_Bool    value)
@@ -638,14 +476,6 @@ elm_fileselector_button_inwin_mode_set(Evas_Object *obj,
    wd->inwin_mode = value;
 }
 
-/**
- * Get the button's file selector "inwin mode" flag.
- *
- * @param obj The button object
- * @return value The "inwin mode" flag
- *
- * @ingroup File_Selector_Button
- */
 EAPI Eina_Bool
 elm_fileselector_button_inwin_mode_get(const Evas_Object *obj)
 {
@@ -656,18 +486,6 @@ elm_fileselector_button_inwin_mode_get(const Evas_Object *obj)
    return wd->inwin_mode;
 }
 
-/**
- * Set the icon used for the button
- *
- * Once the icon object is set, a previously set one will be deleted.
- * If you want to keep that old content object, use the
- * elm_fileselector_button_icon_unset() function.
- *
- * @param obj The button object
- * @param icon  The icon object for the button
- *
- * @ingroup File_Selector_Button
- */
 EAPI void
 elm_fileselector_button_icon_set(Evas_Object *obj,
                                  Evas_Object *icon)
@@ -682,14 +500,6 @@ elm_fileselector_button_icon_set(Evas_Object *obj,
    elm_button_icon_set(wd->btn, icon);
 }
 
-/**
- * Get the icon used for the button
- *
- * @param obj The button object
- * @return The icon object that is being used
- *
- * @ingroup File_Selector_Button
- */
 EAPI Evas_Object *
 elm_fileselector_button_icon_get(const Evas_Object *obj)
 {
@@ -699,16 +509,6 @@ elm_fileselector_button_icon_get(const Evas_Object *obj)
    return elm_button_icon_get(wd->btn);
 }
 
-/**
- * Unset the icon used for the button
- *
- * Unparent and return the icon object which was set for this widget.
- *
- * @param obj The button object
- * @return The icon object that was being used
- *
- * @ingroup File_Selector_Button
- */
 EAPI Evas_Object *
 elm_fileselector_button_icon_unset(Evas_Object *obj)
 {