src/lib/elc_fileselector_entry.h

   1 /**
   2  * @defgroup File_Selector_Entry File Selector Entry
   3  *
   4  * @image html img/widget/fileselector_entry/preview-00.png
   5  * @image latex img/widget/fileselector_entry/preview-00.eps
   6  *
   7  * This is an entry made to be filled with or display a <b>file
   8  * system path string</b>. Besides the entry itself, the widget has
   9  * a @ref File_Selector_Button "file selector button" on its side,
  10  * which will raise an internal @ref Fileselector "file selector widget",
  11  * when clicked, for path selection aided by file system
  12  * navigation.
  13  *
  14  * This file selector may appear in an Elementary window or in an
  15  * inner window. When a file is chosen from it, the (inner) window
  16  * is closed and the selected file's path string is exposed both as
  17  * an smart event and as the new text on the entry.
  18  *
  19  * This widget encapsulates operations on its internal file
  20  * selector on its own API. There is less control over its file
  21  * selector than that one would have instatiating one directly.
  22  *
  23  * Smart callbacks one can register to:
  24  * - @c "changed" - The text within the entry was changed
  25  * - @c "activated" - The entry has had editing finished and
  26  *   changes are to be "committed"
  27  * - @c "press" - The entry has been clicked
  28  * - @c "longpressed" - The entry has been clicked (and held) for a
  29  *   couple seconds
  30  * - @c "clicked" - The entry has been clicked
  31  * - @c "clicked,double" - The entry has been double clicked
  32  * - @c "focused" - The entry has received focus
  33  * - @c "unfocused" - The entry has lost focus
  34  * - @c "selection,paste" - A paste action has occurred on the
  35  *   entry
  36  * - @c "selection,copy" - A copy action has occurred on the entry
  37  * - @c "selection,cut" - A cut action has occurred on the entry
  38  * - @c "unpressed" - The file selector entry's button was released
  39  *   after being pressed.
  40  * - @c "file,chosen" - The user has selected a path via the file
  41  *   selector entry's internal file selector, whose string pointer
  42  *   comes as the @c event_info data (a stringshared string)
  43  *
  44  * Here is an example on its usage:
  45  * @li @ref fileselector_entry_example
  46  *
  47  * @see @ref File_Selector_Button for a similar widget.
  48  * @{
  49  */
  50
  51 /**
  52  * Add a new file selector entry widget to the given parent
  53  * Elementary (container) object
  54  *
  55  * @param parent The parent object
  56  * @return a new file selector entry widget handle or @c NULL, on
  57  * errors
  58  */
  59 EAPI Evas_Object *
  60                                  elm_fileselector_entry_add(Evas_Object *parent)
  61 EINA_ARG_NONNULL(1);
  62
  63 /**
  64  * Set the label for a given file selector entry widget's button
  65  *
  66  * @param obj The file selector entry widget
  67  * @param label The text label to be displayed on @p obj widget's
  68  * button
  69  *
  70  * @deprecated use elm_object_text_set() instead.
  71  */
  72 EINA_DEPRECATED EAPI void        elm_fileselector_entry_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
  73
  74 /**
  75  * Get the label set for a given file selector entry widget's button
  76  *
  77  * @param obj The file selector entry widget
  78  * @return The widget button's label
  79  *
  80  * @deprecated use elm_object_text_set() instead.
  81  */
  82 EINA_DEPRECATED EAPI const char *elm_fileselector_entry_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  83
  84 /**
  85  * Set the icon on a given file selector entry widget's button
  86  *
  87  * @param obj The file selector entry widget
  88  * @param icon The icon object for the entry's button
  89  *
  90  * Once the icon object is set, a previously set one will be
  91  * deleted. If you want to keep the latter, use the
  92  * elm_fileselector_entry_button_icon_unset() function.
  93  *
  94  * @see elm_fileselector_entry_button_icon_get()
  95  */
  96 EAPI void                        elm_fileselector_entry_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
  97
  98 /**
  99  * Get the icon set for a given file selector entry widget's button
 100  *
 101  * @param obj The file selector entry widget
 102  * @return The icon object currently set on @p obj widget's button
 103  * or @c NULL, if none is
 104  *
 105  * @see elm_fileselector_entry_button_icon_set()
 106  */
 107 EAPI Evas_Object                *elm_fileselector_entry_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 108
 109 /**
 110  * Unset the icon used in a given file selector entry widget's
 111  * button
 112  *
 113  * @param obj The file selector entry widget
 114  * @return The icon object that was being used on @p obj widget's
 115  * button or @c NULL, on errors
 116  *
 117  * Unparent and return the icon object which was set for this
 118  * widget's button.
 119  *
 120  * @see elm_fileselector_entry_button_icon_set()
 121  */
 122 EAPI Evas_Object                *elm_fileselector_entry_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 123
 124 /**
 125  * Set the title for a given file selector entry widget's window
 126  *
 127  * @param obj The file selector entry widget
 128  * @param title The title string
 129  *
 130  * This will change the window's title, when the file selector pops
 131  * out after a click on the entry's button. Those windows have the
 132  * default (unlocalized) value of @c "Select a file" as titles.
 133  *
 134  * @note It will only take any effect if the file selector
 135  * entry widget is @b not under "inwin mode".
 136  *
 137  * @see elm_fileselector_entry_window_title_get()
 138  */
 139 EAPI void                        elm_fileselector_entry_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
 140
 141 /**
 142  * Get the title set for a given file selector entry widget's
 143  * window
 144  *
 145  * @param obj The file selector entry widget
 146  * @return Title of the file selector entry's window
 147  *
 148  * @see elm_fileselector_entry_window_title_get() for more details
 149  */
 150 EAPI const char                 *elm_fileselector_entry_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 151
 152 /**
 153  * Set the size of a given file selector entry widget's window,
 154  * holding the file selector itself.
 155  *
 156  * @param obj The file selector entry widget
 157  * @param width The window's width
 158  * @param height The window's height
 159  *
 160  * @note it will only take any effect if the file selector entry
 161  * widget is @b not under "inwin mode". The default size for the
 162  * window (when applicable) is 400x400 pixels.
 163  *
 164  * @see elm_fileselector_entry_window_size_get()
 165  */
 166 EAPI void                        elm_fileselector_entry_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
 167
 168 /**
 169  * Get the size of a given file selector entry widget's window,
 170  * holding the file selector itself.
 171  *
 172  * @param obj The file selector entry widget
 173  * @param width Pointer into which to store the width value
 174  * @param height Pointer into which to store the height value
 175  *
 176  * @note Use @c NULL pointers on the size values you're not
 177  * interested in: they'll be ignored by the function.
 178  *
 179  * @see elm_fileselector_entry_window_size_set(), for more details
 180  */
 181 EAPI void                        elm_fileselector_entry_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
 182
 183 /**
 184  * Set the initial file system path and the entry's path string for
 185  * a given file selector entry widget
 186  *
 187  * @param obj The file selector entry widget
 188  * @param path The path string
 189  *
 190  * It must be a <b>directory</b> path, which will have the contents
 191  * displayed initially in the file selector's view, when invoked
 192  * from @p obj. The default initial path is the @c "HOME"
 193  * environment variable's value.
 194  *
 195  * @see elm_fileselector_entry_path_get()
 196  */
 197 EAPI void                        elm_fileselector_entry_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
 198
 199 /**
 200  * Get the entry's path string for a given file selector entry
 201  * widget
 202  *
 203  * @param obj The file selector entry widget
 204  * @return path The path string
 205  *
 206  * @see elm_fileselector_entry_path_set() for more details
 207  */
 208 EAPI const char                 *elm_fileselector_entry_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 209
 210 /**
 211  * Enable/disable a tree view in the given file selector entry
 212  * widget's internal file selector
 213  *
 214  * @param obj The file selector entry widget
 215  * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
 216  * disable
 217  *
 218  * This has the same effect as elm_fileselector_expandable_set(),
 219  * but now applied to a file selector entry's internal file
 220  * selector.
 221  *
 222  * @note There's no way to put a file selector entry's internal
 223  * file selector in "grid mode", as one may do with "pure" file
 224  * selectors.
 225  *
 226  * @see elm_fileselector_expandable_get()
 227  */
 228 EAPI void                        elm_fileselector_entry_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 229
 230 /**
 231  * Get whether tree view is enabled for the given file selector
 232  * entry widget's internal file selector
 233  *
 234  * @param obj The file selector entry widget
 235  * @return @c EINA_TRUE if @p obj widget's internal file selector
 236  * is in tree view, @c EINA_FALSE otherwise (and or errors)
 237  *
 238  * @see elm_fileselector_expandable_set() for more details
 239  */
 240 EAPI Eina_Bool                   elm_fileselector_entry_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 241
 242 /**
 243  * Set whether a given file selector entry widget's internal file
 244  * selector is to display folders only or the directory contents,
 245  * as well.
 246  *
 247  * @param obj The file selector entry widget
 248  * @param only @c EINA_TRUE to make @p obj widget's internal file
 249  * selector only display directories, @c EINA_FALSE to make files
 250  * to be displayed in it too
 251  *
 252  * This has the same effect as elm_fileselector_folder_only_set(),
 253  * but now applied to a file selector entry's internal file
 254  * selector.
 255  *
 256  * @see elm_fileselector_folder_only_get()
 257  */
 258 EAPI void                        elm_fileselector_entry_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 259
 260 /**
 261  * Get whether a given file selector entry widget's internal file
 262  * selector is displaying folders only or the directory contents,
 263  * as well.
 264  *
 265  * @param obj The file selector entry widget
 266  * @return @c EINA_TRUE if @p obj widget's internal file
 267  * selector is only displaying directories, @c EINA_FALSE if files
 268  * are being displayed in it too (and on errors)
 269  *
 270  * @see elm_fileselector_entry_folder_only_set() for more details
 271  */
 272 EAPI Eina_Bool                   elm_fileselector_entry_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 273
 274 /**
 275  * Enable/disable the file name entry box where the user can type
 276  * in a name for a file, in a given file selector entry widget's
 277  * internal file selector.
 278  *
 279  * @param obj The file selector entry widget
 280  * @param is_save @c EINA_TRUE to make @p obj widget's internal
 281  * file selector a "saving dialog", @c EINA_FALSE otherwise
 282  *
 283  * This has the same effect as elm_fileselector_is_save_set(),
 284  * but now applied to a file selector entry's internal file
 285  * selector.
 286  *
 287  * @see elm_fileselector_is_save_get()
 288  */
 289 EAPI void                        elm_fileselector_entry_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 290
 291 /**
 292  * Get whether the given file selector entry widget's internal
 293  * file selector is in "saving dialog" mode
 294  *
 295  * @param obj The file selector entry widget
 296  * @return @c EINA_TRUE, if @p obj widget's internal file selector
 297  * is in "saving dialog" mode, @c EINA_FALSE otherwise (and on
 298  * errors)
 299  *
 300  * @see elm_fileselector_entry_is_save_set() for more details
 301  */
 302 EAPI Eina_Bool                   elm_fileselector_entry_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 303
 304 /**
 305  * Set whether a given file selector entry widget's internal file
 306  * selector will raise an Elementary "inner window", instead of a
 307  * dedicated Elementary window. By default, it won't.
 308  *
 309  * @param obj The file selector entry widget
 310  * @param value @c EINA_TRUE to make it use an inner window, @c
 311  * EINA_TRUE to make it use a dedicated window
 312  *
 313  * @see elm_win_inwin_add() for more information on inner windows
 314  * @see elm_fileselector_entry_inwin_mode_get()
 315  */
 316 EAPI void                        elm_fileselector_entry_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 317
 318 /**
 319  * Get whether a given file selector entry widget's internal file
 320  * selector will raise an Elementary "inner window", instead of a
 321  * dedicated Elementary window.
 322  *
 323  * @param obj The file selector entry widget
 324  * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
 325  * if it will use a dedicated window
 326  *
 327  * @see elm_fileselector_entry_inwin_mode_set() for more details
 328  */
 329 EAPI Eina_Bool                   elm_fileselector_entry_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 330
 331 /**
 332  * Set the initial file system path for a given file selector entry
 333  * widget
 334  *
 335  * @param obj The file selector entry widget
 336  * @param path The path string
 337  *
 338  * It must be a <b>directory</b> path, which will have the contents
 339  * displayed initially in the file selector's view, when invoked
 340  * from @p obj. The default initial path is the @c "HOME"
 341  * environment variable's value.
 342  *
 343  * @see elm_fileselector_entry_path_get()
 344  */
 345 EAPI void                        elm_fileselector_entry_selected_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
 346
 347 /**
 348  * Get the parent directory's path to the latest file selection on
 349  * a given filer selector entry widget
 350  *
 351  * @param obj The file selector object
 352  * @return The (full) path of the directory of the last selection
 353  * on @p obj widget, a @b stringshared string
 354  *
 355  * @see elm_fileselector_entry_path_set()
 356  */
 357 EAPI const char                 *elm_fileselector_entry_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 358
 359 /**
 360  * @}
 361  */