src/lib/elc_fileselector.h

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