From 257a0ef611d05f5619557de1d38bab6a731bad5a Mon Sep 17 00:00:00 2001 From: Mike McCormack Date: Fri, 4 Nov 2011 16:26:49 +0900 Subject: [PATCH] [Elementary.h] Add docs for fileselector --- src/lib/Elementary.h.in | 304 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 294 insertions(+), 10 deletions(-) diff --git a/src/lib/Elementary.h.in b/src/lib/Elementary.h.in index cdafd78..0aedbd3 100644 --- a/src/lib/Elementary.h.in +++ b/src/lib/Elementary.h.in @@ -20227,33 +20227,317 @@ extern "C" { * @} */ - /* file selector */ + /** + * @defgroup Fileselector File Selector + * + * @image html img/widget/fileselector/preview-00.png + * @image latex img/widget/fileselector/preview-00.eps + * + * A file selector is a widget that allows a user to navigate + * through a file system, reporting file selections back via its + * API. + * + * It contains shortcut buttons for home directory (@c ~) and to + * jump one directory upwards (..), as well as cancel/ok buttons to + * confirm/cancel a given selection. After either one of those two + * former actions, the file selector will issue its @c "done" smart + * callback. + * + * There's a text entry on it, too, showing the name of the current + * selection. There's the possibility of making it editable, so it + * is useful on file saving dialogs on applications, where one + * gives a file name to save contents to, in a given directory in + * the system. This custom file name will be reported on the @c + * "done" smart callback (explained in sequence). + * + * Finally, it has a view to display file system items into in two + * possible forms: + * - list + * - grid + * + * If Elementary is built with support of the Ethumb thumbnailing + * library, the second form of view will display preview thumbnails + * of files which it supports. + * + * Smart callbacks one can register to: + * + * - @c "selected" - the user has clicked on a file (when not in + * folders-only mode) or directory (when in folders-only mode) + * - @c "directory,open" - the list has been populated with new + * content (@c event_info is a pointer to the directory's + * path, a @b stringshared string) + * - @c "done" - the user has clicked on the "ok" or "cancel" + * buttons (@c event_info is a pointer to the selection's + * path, a @b stringshared string) + * + * Here is an example on its usage: + * @li @ref fileselector_example + */ + + /** + * @addtogroup Fileselector + * @{ + */ + + /** + * Defines how a file selector widget is to layout its contents + * (file system entries). + */ typedef enum _Elm_Fileselector_Mode { - ELM_FILESELECTOR_LIST = 0, - ELM_FILESELECTOR_GRID, - ELM_FILESELECTOR_LAST + ELM_FILESELECTOR_LIST = 0, /**< layout as a list */ + ELM_FILESELECTOR_GRID, /**< layout as a grid */ + ELM_FILESELECTOR_LAST /**< sentinel (helper) value, not used */ } Elm_Fileselector_Mode; + /** + * Add a new file selector widget to the given parent Elementary + * (container) object + * + * @param parent The parent object + * @return a new file selector widget handle or @c NULL, on errors + * + * This function inserts a new file selector widget on the canvas. + * + * @ingroup Fileselector + */ EAPI Evas_Object *elm_fileselector_add(Evas_Object *parent) 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 widget + * + * @param obj The file selector object + * @param is_save @c EINA_TRUE to make the file selector a "saving + * dialog", @c EINA_FALSE otherwise + * + * Having the entry editable is useful on file saving dialogs on + * applications, where one gives a file name to save contents to, + * in a given directory in the system. This custom file name will + * be reported on the @c "done" smart callback. + * + * @see elm_fileselector_is_save_get() + * + * @ingroup Fileselector + */ EAPI void elm_fileselector_is_save_set(Evas_Object *obj, Eina_Bool is_save) EINA_ARG_NONNULL(1); + + /** + * Get whether the given file selector is in "saving dialog" mode + * + * @param obj The file selector object + * @return @c EINA_TRUE, if the file selector is in "saving dialog" + * mode, @c EINA_FALSE otherwise (and on errors) + * + * @see elm_fileselector_is_save_set() for more details + * + * @ingroup Fileselector + */ EAPI Eina_Bool elm_fileselector_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Enable/disable folder-only view for a given file selector widget + * + * @param obj The file selector object + * @param only @c EINA_TRUE to make @p obj only display + * directories, @c EINA_FALSE to make files to be displayed in it + * too + * + * If enabled, the widget's view will only display folder items, + * naturally. + * + * @see elm_fileselector_folder_only_get() + * + * @ingroup Fileselector + */ EAPI void elm_fileselector_folder_only_set(Evas_Object *obj, Eina_Bool only) EINA_ARG_NONNULL(1); + + /** + * Get whether folder-only view is set for a given file selector + * widget + * + * @param obj The file selector object + * @return only @c EINA_TRUE if @p obj is only displaying + * directories, @c EINA_FALSE if files are being displayed in it + * too (and on errors) + * + * @see elm_fileselector_folder_only_get() + * + * @ingroup Fileselector + */ EAPI Eina_Bool elm_fileselector_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Enable/disable the "ok" and "cancel" buttons on a given file + * selector widget + * + * @param obj The file selector object + * @param only @c EINA_TRUE to show them, @c EINA_FALSE to hide. + * + * @note A file selector without those buttons will never emit the + * @c "done" smart event, and is only usable if one is just hooking + * to the other two events. + * + * @see elm_fileselector_buttons_ok_cancel_get() + * + * @ingroup Fileselector + */ EAPI void elm_fileselector_buttons_ok_cancel_set(Evas_Object *obj, Eina_Bool buttons) EINA_ARG_NONNULL(1); + + /** + * Get whether the "ok" and "cancel" buttons on a given file + * selector widget are being shown. + * + * @param obj The file selector object + * @return @c EINA_TRUE if they are being shown, @c EINA_FALSE + * otherwise (and on errors) + * + * @see elm_fileselector_buttons_ok_cancel_set() for more details + * + * @ingroup Fileselector + */ EAPI Eina_Bool elm_fileselector_buttons_ok_cancel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI Eina_Bool elm_fileselector_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Enable/disable a tree view in the given file selector widget, + * if it's in @c #ELM_FILESELECTOR_LIST mode + * + * @param obj The file selector object + * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to + * disable + * + * In a tree view, arrows are created on the sides of directories, + * allowing them to expand in place. + * + * @note If it's in other mode, the changes made by this function + * will only be visible when one switches back to "list" mode. + * + * @see elm_fileselector_expandable_get() + * + * @ingroup Fileselector + */ EAPI void elm_fileselector_expandable_set(Evas_Object *obj, Eina_Bool expand) EINA_ARG_NONNULL(1); + + /** + * Get whether tree view is enabled for the given file selector + * widget + * + * @param obj The file selector object + * @return @c EINA_TRUE if @p obj is in tree view, @c EINA_FALSE + * otherwise (and or errors) + * + * @see elm_fileselector_expandable_set() for more details + * + * @ingroup Fileselector + */ + EAPI Eina_Bool elm_fileselector_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Set, programmatically, the @b directory that a given file + * selector widget will display contents from + * + * @param obj The file selector object + * @param path The path to display in @p obj + * + * This will change the @b directory that @p obj is displaying. It + * will also clear the text entry area on the @p obj object, which + * displays select files' names. + * + * @see elm_fileselector_path_get() + * + * @ingroup Fileselector + */ EAPI void elm_fileselector_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1); + + /** + * Get the parent directory's path that a given file selector + * widget is displaying + * + * @param obj The file selector object + * @return The (full) path of the directory the file selector is + * displaying, a @b stringshared string + * + * @see elm_fileselector_path_set() + * + * @ingroup Fileselector + */ EAPI const char *elm_fileselector_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - EAPI const char *elm_fileselector_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Set, programmatically, the currently selected file/directory in + * the given file selector widget + * + * @param obj The file selector object + * @param path The (full) path to a file or directory + * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. The + * latter case occurs if the directory or file pointed to do not + * exist. + * + * @see elm_fileselector_selected_get() + * + * @ingroup Fileselector + */ EAPI Eina_Bool elm_fileselector_selected_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1); + + /** + * Get the currently selected item's (full) path, in the given file + * selector widget + * + * @param obj The file selector object + * @return The absolute path of the selected item, a @b + * stringshared string + * + * @note Custom editions on @p obj object's text entry, if made, + * will appear on the return string of this function, naturally. + * + * @see elm_fileselector_selected_set() for more details + * + * @ingroup Fileselector + */ + EAPI const char *elm_fileselector_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); + + /** + * Set the mode in which a given file selector widget will display + * (layout) file system entries in its view + * + * @param obj The file selector object + * @param mode The mode of the fileselector, being it one of + * #ELM_FILESELECTOR_LIST (default) or #ELM_FILESELECTOR_GRID. The + * first one, naturally, will display the files in a list. The + * latter will make the widget to display its entries in a grid + * form. + * + * @note By using elm_fileselector_expandable_set(), the user may + * trigger a tree view for that list. + * + * @note If Elementary is built with support of the Ethumb + * thumbnailing library, the second form of view will display + * preview thumbnails of files which it supports. You must have + * elm_need_ethumb() called in your Elementary for thumbnailing to + * work, though. + * + * @see elm_fileselector_expandable_set(). + * @see elm_fileselector_mode_get(). + * + * @ingroup Fileselector + */ EAPI void elm_fileselector_mode_set(Evas_Object *obj, Elm_Fileselector_Mode mode) EINA_ARG_NONNULL(1); + + /** + * Get the mode in which a given file selector widget is displaying + * (layouting) file system entries in its view + * + * @param obj The fileselector object + * @return The mode in which the fileselector is at + * + * @see elm_fileselector_mode_set() for more details + * + * @ingroup Fileselector + */ EAPI Elm_Fileselector_Mode elm_fileselector_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); - /* smart callbacks called: - * "selected" - the user click on a file - * "directory,open" - the list is populate with a new content. event_info is a directory. - * "done" - the user click on the ok or cancel buttons + + /** + * @} */ /* progressbar */ -- 2.7.4