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
  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);
  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);
  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);
 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);
 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);
 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 buttons @c EINA_TRUE to show buttons, @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);
 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);
 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);
 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);
 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);
 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);
 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);
 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);
 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);
 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);
 309
 310 /**
 311  * @}
 312  */