src/lib/elc_fileselector_entry.h

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