src/lib/elc_fileselector.h

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