src/lib/elc_fileselector.h

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