src/lib/elc_fileselector.h

   1    /**
   2     * @defgroup Fileselector File Selector
   3     *
   4     * @image html img/widget/fileselector/preview-00.png
   5     * @image latex img/widget/fileselector/preview-00.eps
   6     *
   7     * A file selector is a widget that allows a user to navigate
   8     * through a file system, reporting file selections back via its
   9     * API.
  10     *
  11     * It contains shortcut buttons for home directory (@c ~) and to
  12     * jump one directory upwards (..), as well as cancel/ok buttons to
  13     * confirm/cancel a given selection. After either one of those two
  14     * former actions, the file selector will issue its @c "done" smart
  15     * callback.
  16     *
  17     * There's a text entry on it, too, showing the name of the current
  18     * selection. There's the possibility of making it editable, so it
  19     * is useful on file saving dialogs on applications, where one
  20     * gives a file name to save contents to, in a given directory in
  21     * the system. This custom file name will be reported on the @c
  22     * "done" smart callback (explained in sequence).
  23     *
  24     * Finally, it has a view to display file system items into in two
  25     * possible forms:
  26     * - list
  27     * - grid
  28     *
  29     * If Elementary is built with support of the Ethumb thumbnailing
  30     * library, the second form of view will display preview thumbnails
  31     * of files which it supports.
  32     *
  33     * Smart callbacks one can register to:
  34     *
  35     * - @c "selected" - the user has clicked on a file (when not in
  36     *      folders-only mode) or directory (when in folders-only mode)
  37     * - @c "directory,open" - the list has been populated with new
  38     *      content (@c event_info is a pointer to the directory's
  39     *      path, a @b stringshared string)
  40     * - @c "done" - the user has clicked on the "ok" or "cancel"
  41     *      buttons (@c event_info is a pointer to the selection's
  42     *      path, a @b stringshared string)
  43     *
  44     * Here is an example on its usage:
  45     * @li @ref fileselector_example
  46     */
  47
  48    /**
  49     * @addtogroup Fileselector
  50     * @{
  51     */
  52
  53    /**
  54     * Defines how a file selector widget is to layout its contents
  55     * (file system entries).
  56     */
  57    typedef enum _Elm_Fileselector_Mode
  58      {
  59         ELM_FILESELECTOR_LIST = 0, /**< layout as a list */
  60         ELM_FILESELECTOR_GRID, /**< layout as a grid */
  61         ELM_FILESELECTOR_LAST /**< sentinel (helper) value, not used */
  62      } Elm_Fileselector_Mode;
  63
  64    /**
  65     * Add a new file selector widget to the given parent Elementary
  66     * (container) object
  67     *
  68     * @param parent The parent object
  69     * @return a new file selector widget handle or @c NULL, on errors
  70     *
  71     * This function inserts a new file selector widget on the canvas.
  72     *
  73     * @ingroup Fileselector
  74     */
  75    EAPI Evas_Object          *elm_fileselector_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  76
  77    /**
  78     * Enable/disable the file name entry box where the user can type
  79     * in a name for a file, in a given file selector widget
  80     *
  81     * @param obj The file selector object
  82     * @param is_save @c EINA_TRUE to make the file selector a "saving
  83     * dialog", @c EINA_FALSE otherwise
  84     *
  85     * Having the entry editable is useful on file saving dialogs on
  86     * applications, where one gives a file name to save contents to,
  87     * in a given directory in the system. This custom file name will
  88     * be reported on the @c "done" smart callback.
  89     *
  90     * @see elm_fileselector_is_save_get()
  91     *
  92     * @ingroup Fileselector
  93     */
  94    EAPI void                  elm_fileselector_is_save_set(Evas_Object *obj, Eina_Bool is_save) EINA_ARG_NONNULL(1);
  95
  96    /**
  97     * Get whether the given file selector is in "saving dialog" mode
  98     *
  99     * @param obj The file selector object
 100     * @return @c EINA_TRUE, if the file selector is in "saving dialog"
 101     * mode, @c EINA_FALSE otherwise (and on errors)
 102     *
 103     * @see elm_fileselector_is_save_set() for more details
 104     *
 105     * @ingroup Fileselector
 106     */
 107    EAPI Eina_Bool             elm_fileselector_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 108
 109    /**
 110     * Enable/disable folder-only view for a given file selector widget
 111     *
 112     * @param obj The file selector object
 113     * @param only @c EINA_TRUE to make @p obj only display
 114     * directories, @c EINA_FALSE to make files to be displayed in it
 115     * too
 116     *
 117     * If enabled, the widget's view will only display folder items,
 118     * naturally.
 119     *
 120     * @see elm_fileselector_folder_only_get()
 121     *
 122     * @ingroup Fileselector
 123     */
 124    EAPI void                  elm_fileselector_folder_only_set(Evas_Object *obj, Eina_Bool only) EINA_ARG_NONNULL(1);
 125
 126    /**
 127     * Get whether folder-only view is set for a given file selector
 128     * widget
 129     *
 130     * @param obj The file selector object
 131     * @return only @c EINA_TRUE if @p obj is only displaying
 132     * directories, @c EINA_FALSE if files are being displayed in it
 133     * too (and on errors)
 134     *
 135     * @see elm_fileselector_folder_only_get()
 136     *
 137     * @ingroup Fileselector
 138     */
 139    EAPI Eina_Bool             elm_fileselector_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 140
 141    /**
 142     * Enable/disable the "ok" and "cancel" buttons on a given file
 143     * selector widget
 144     *
 145     * @param obj The file selector object
 146     * @param only @c EINA_TRUE to show them, @c EINA_FALSE to hide.
 147     *
 148     * @note A file selector without those buttons will never emit the
 149     * @c "done" smart event, and is only usable if one is just hooking
 150     * to the other two events.
 151     *
 152     * @see elm_fileselector_buttons_ok_cancel_get()
 153     *
 154     * @ingroup Fileselector
 155     */
 156    EAPI void                  elm_fileselector_buttons_ok_cancel_set(Evas_Object *obj, Eina_Bool buttons) EINA_ARG_NONNULL(1);
 157
 158    /**
 159     * Get whether the "ok" and "cancel" buttons on a given file
 160     * selector widget are being shown.
 161     *
 162     * @param obj The file selector object
 163     * @return @c EINA_TRUE if they are being shown, @c EINA_FALSE
 164     * otherwise (and on errors)
 165     *
 166     * @see elm_fileselector_buttons_ok_cancel_set() for more details
 167     *
 168     * @ingroup Fileselector
 169     */
 170    EAPI Eina_Bool             elm_fileselector_buttons_ok_cancel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 171
 172    /**
 173     * Enable/disable a tree view in the given file selector widget,
 174     * <b>if it's in @c #ELM_FILESELECTOR_LIST mode</b>
 175     *
 176     * @param obj The file selector object
 177     * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
 178     * disable
 179     *
 180     * In a tree view, arrows are created on the sides of directories,
 181     * allowing them to expand in place.
 182     *
 183     * @note If it's in other mode, the changes made by this function
 184     * will only be visible when one switches back to "list" mode.
 185     *
 186     * @see elm_fileselector_expandable_get()
 187     *
 188     * @ingroup Fileselector
 189     */
 190    EAPI void                  elm_fileselector_expandable_set(Evas_Object *obj, Eina_Bool expand) EINA_ARG_NONNULL(1);
 191
 192    /**
 193     * Get whether tree view is enabled for the given file selector
 194     * widget
 195     *
 196     * @param obj The file selector object
 197     * @return @c EINA_TRUE if @p obj is in tree view, @c EINA_FALSE
 198     * otherwise (and or errors)
 199     *
 200     * @see elm_fileselector_expandable_set() for more details
 201     *
 202     * @ingroup Fileselector
 203     */
 204    EAPI Eina_Bool             elm_fileselector_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 205
 206    /**
 207     * Set, programmatically, the @b directory that a given file
 208     * selector widget will display contents from
 209     *
 210     * @param obj The file selector object
 211     * @param path The path to display in @p obj
 212     *
 213     * This will change the @b directory that @p obj is displaying. It
 214     * will also clear the text entry area on the @p obj object, which
 215     * displays select files' names.
 216     *
 217     * @see elm_fileselector_path_get()
 218     *
 219     * @ingroup Fileselector
 220     */
 221    EAPI void                  elm_fileselector_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
 222
 223    /**
 224     * Get the parent directory's path that a given file selector
 225     * widget is displaying
 226     *
 227     * @param obj The file selector object
 228     * @return The (full) path of the directory the file selector is
 229     * displaying, a @b stringshared string
 230     *
 231     * @see elm_fileselector_path_set()
 232     *
 233     * @ingroup Fileselector
 234     */
 235    EAPI const char           *elm_fileselector_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 236
 237    /**
 238     * Set, programmatically, the currently selected file/directory in
 239     * the given file selector widget
 240     *
 241     * @param obj The file selector object
 242     * @param path The (full) path to a file or directory
 243     * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. The
 244     * latter case occurs if the directory or file pointed to do not
 245     * exist.
 246     *
 247     * @see elm_fileselector_selected_get()
 248     *
 249     * @ingroup Fileselector
 250     */
 251    EAPI Eina_Bool             elm_fileselector_selected_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
 252
 253    /**
 254     * Get the currently selected item's (full) path, in the given file
 255     * selector widget
 256     *
 257     * @param obj The file selector object
 258     * @return The absolute path of the selected item, a @b
 259     * stringshared string
 260     *
 261     * @note Custom editions on @p obj object's text entry, if made,
 262     * will appear on the return string of this function, naturally.
 263     *
 264     * @see elm_fileselector_selected_set() for more details
 265     *
 266     * @ingroup Fileselector
 267     */
 268    EAPI const char           *elm_fileselector_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 269
 270    /**
 271     * Set the mode in which a given file selector widget will display
 272     * (layout) file system entries in its view
 273     *
 274     * @param obj The file selector object
 275     * @param mode The mode of the fileselector, being it one of
 276     * #ELM_FILESELECTOR_LIST (default) or #ELM_FILESELECTOR_GRID. The
 277     * first one, naturally, will display the files in a list. The
 278     * latter will make the widget to display its entries in a grid
 279     * form.
 280     *
 281     * @note By using elm_fileselector_expandable_set(), the user may
 282     * trigger a tree view for that list.
 283     *
 284     * @note If Elementary is built with support of the Ethumb
 285     * thumbnailing library, the second form of view will display
 286     * preview thumbnails of files which it supports. You must have
 287     * elm_need_ethumb() called in your Elementary for thumbnailing to
 288     * work, though.
 289     *
 290     * @see elm_fileselector_expandable_set().
 291     * @see elm_fileselector_mode_get().
 292     *
 293     * @ingroup Fileselector
 294     */
 295    EAPI void                  elm_fileselector_mode_set(Evas_Object *obj, Elm_Fileselector_Mode mode) EINA_ARG_NONNULL(1);
 296
 297    /**
 298     * Get the mode in which a given file selector widget is displaying
 299     * (layouting) file system entries in its view
 300     *
 301     * @param obj The fileselector object
 302     * @return The mode in which the fileselector is at
 303     *
 304     * @see elm_fileselector_mode_set() for more details
 305     *
 306     * @ingroup Fileselector
 307     */
 308    EAPI Elm_Fileselector_Mode elm_fileselector_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 309
 310    /**
 311     * @}
 312     */
 313