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  * Default text parts of the fileselector_button widget that you can use for
  45  * are:
  46  * @li "default" - Label of the fileselector_button
  47  *
  48  * Default contents parts of the fileselector_entry widget that you can use for
  49  * are:
  50  * @li "button icon" - Button icon of the fileselector_entry
  51  *
  52  * Supported elm_object common APIs.
  53  * @li elm_object_part_text_set
  54  * @li elm_object_part_text_get
  55  * @li elm_object_part_content_set
  56  * @li elm_object_part_content_get
  57  * @li elm_object_part_content_unset
  58  * @li elm_object_disabled_set
  59  * @li elm_object_disabled_get
  60  *
  61  * Here is an example on its usage:
  62  * @li @ref fileselector_entry_example
  63  *
  64  * @see @ref File_Selector_Button for a similar widget.
  65  * @{
  66  */
  67
  68 /**
  69  * Add a new file selector entry widget to the given parent
  70  * Elementary (container) object
  71  *
  72  * @param parent The parent object
  73  * @return a new file selector entry widget handle or @c NULL, on
  74  * errors
  75  */
  76 EAPI Evas_Object                *elm_fileselector_entry_add(Evas_Object *parent);
  77
  78 /**
  79  * Set the title for a given file selector entry widget's window
  80  *
  81  * @param obj The file selector entry widget
  82  * @param title The title string
  83  *
  84  * This will change the window's title, when the file selector pops
  85  * out after a click on the entry's button. Those windows have the
  86  * default (unlocalized) value of @c "Select a file" as titles.
  87  *
  88  * @note It will only take any effect if the file selector
  89  * entry widget is @b not under "inwin mode".
  90  *
  91  * @see elm_fileselector_entry_window_title_get()
  92  */
  93 EAPI void                        elm_fileselector_entry_window_title_set(Evas_Object *obj, const char *title);
  94
  95 /**
  96  * Get the title set for a given file selector entry widget's
  97  * window
  98  *
  99  * @param obj The file selector entry widget
 100  * @return Title of the file selector entry's window
 101  *
 102  * @see elm_fileselector_entry_window_title_get() for more details
 103  */
 104 EAPI const char                 *elm_fileselector_entry_window_title_get(const Evas_Object *obj);
 105
 106 /**
 107  * Set the size of a given file selector entry widget's window,
 108  * holding the file selector itself.
 109  *
 110  * @param obj The file selector entry widget
 111  * @param width The window's width
 112  * @param height The window's height
 113  *
 114  * @note it will only take any effect if the file selector entry
 115  * widget is @b not under "inwin mode". The default size for the
 116  * window (when applicable) is 400x400 pixels.
 117  *
 118  * @see elm_fileselector_entry_window_size_get()
 119  */
 120 EAPI void                        elm_fileselector_entry_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height);
 121
 122 /**
 123  * Get the size of a given file selector entry widget's window,
 124  * holding the file selector itself.
 125  *
 126  * @param obj The file selector entry widget
 127  * @param width Pointer into which to store the width value
 128  * @param height Pointer into which to store the height value
 129  *
 130  * @note Use @c NULL pointers on the size values you're not
 131  * interested in: they'll be ignored by the function.
 132  *
 133  * @see elm_fileselector_entry_window_size_set(), for more details
 134  */
 135 EAPI void                        elm_fileselector_entry_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height);
 136
 137 /**
 138  * Set the initial file system path and the entry's path string for
 139  * a given file selector entry widget
 140  *
 141  * @param obj The file selector entry widget
 142  * @param path The path string
 143  *
 144  * It must be a <b>directory</b> path, which will have the contents
 145  * displayed initially in the file selector's view, when invoked
 146  * from @p obj. The default initial path is the @c "HOME"
 147  * environment variable's value.
 148  *
 149  * @see elm_fileselector_entry_path_get()
 150  */
 151 EAPI void                        elm_fileselector_entry_path_set(Evas_Object *obj, const char *path);
 152
 153 /**
 154  * Get the entry's path string for a given file selector entry
 155  * widget
 156  *
 157  * @param obj The file selector entry widget
 158  * @return path The path string
 159  *
 160  * @see elm_fileselector_entry_path_set() for more details
 161  */
 162 EAPI const char                 *elm_fileselector_entry_path_get(const Evas_Object *obj);
 163
 164 /**
 165  * Enable/disable a tree view in the given file selector entry
 166  * widget's internal file selector
 167  *
 168  * @param obj The file selector entry widget
 169  * @param value @c EINA_TRUE to enable tree view, @c EINA_FALSE to disable
 170  *
 171  * This has the same effect as elm_fileselector_expandable_set(),
 172  * but now applied to a file selector entry's internal file
 173  * selector.
 174  *
 175  * @note There's no way to put a file selector entry's internal
 176  * file selector in "grid mode", as one may do with "pure" file
 177  * selectors.
 178  *
 179  * @see elm_fileselector_expandable_get()
 180  */
 181 EAPI void                        elm_fileselector_entry_expandable_set(Evas_Object *obj, Eina_Bool value);
 182
 183 /**
 184  * Get whether tree view is enabled for the given file selector
 185  * entry widget's internal file selector
 186  *
 187  * @param obj The file selector entry widget
 188  * @return @c EINA_TRUE if @p obj widget's internal file selector
 189  * is in tree view, @c EINA_FALSE otherwise (and or errors)
 190  *
 191  * @see elm_fileselector_expandable_set() for more details
 192  */
 193 EAPI Eina_Bool                   elm_fileselector_entry_expandable_get(const Evas_Object *obj);
 194
 195 /**
 196  * Set whether a given file selector entry widget's internal file
 197  * selector is to display folders only or the directory contents,
 198  * as well.
 199  *
 200  * @param obj The file selector entry widget
 201  * @param value @c EINA_TRUE to make @p obj widget's internal file
 202  * selector only display directories, @c EINA_FALSE to make files
 203  * to be displayed in it too
 204  *
 205  * This has the same effect as elm_fileselector_folder_only_set(),
 206  * but now applied to a file selector entry's internal file
 207  * selector.
 208  *
 209  * @see elm_fileselector_folder_only_get()
 210  */
 211 EAPI void                        elm_fileselector_entry_folder_only_set(Evas_Object *obj, Eina_Bool value);
 212
 213 /**
 214  * Get whether a given file selector entry widget's internal file
 215  * selector is displaying folders only or the directory contents,
 216  * as well.
 217  *
 218  * @param obj The file selector entry widget
 219  * @return @c EINA_TRUE if @p obj widget's internal file
 220  * selector is only displaying directories, @c EINA_FALSE if files
 221  * are being displayed in it too (and on errors)
 222  *
 223  * @see elm_fileselector_entry_folder_only_set() for more details
 224  */
 225 EAPI Eina_Bool                   elm_fileselector_entry_folder_only_get(const Evas_Object *obj);
 226
 227 /**
 228  * Enable/disable the file name entry box where the user can type
 229  * in a name for a file, in a given file selector entry widget's
 230  * internal file selector.
 231  *
 232  * @param obj The file selector entry widget
 233  * @param value @c EINA_TRUE to make @p obj widget's internal
 234  * file selector a "saving dialog", @c EINA_FALSE otherwise
 235  *
 236  * This has the same effect as elm_fileselector_is_save_set(),
 237  * but now applied to a file selector entry's internal file
 238  * selector.
 239  *
 240  * @see elm_fileselector_is_save_get()
 241  */
 242 EAPI void                        elm_fileselector_entry_is_save_set(Evas_Object *obj, Eina_Bool value);
 243
 244 /**
 245  * Get whether the given file selector entry widget's internal
 246  * file selector is in "saving dialog" mode
 247  *
 248  * @param obj The file selector entry widget
 249  * @return @c EINA_TRUE, if @p obj widget's internal file selector
 250  * is in "saving dialog" mode, @c EINA_FALSE otherwise (and on
 251  * errors)
 252  *
 253  * @see elm_fileselector_entry_is_save_set() for more details
 254  */
 255 EAPI Eina_Bool                   elm_fileselector_entry_is_save_get(const Evas_Object *obj);
 256
 257 /**
 258  * Set whether a given file selector entry widget's internal file
 259  * selector will raise an Elementary "inner window", instead of a
 260  * dedicated Elementary window. By default, it won't.
 261  *
 262  * @param obj The file selector entry widget
 263  * @param value @c EINA_TRUE to make it use an inner window, @c
 264  * EINA_TRUE to make it use a dedicated window
 265  *
 266  * @see elm_win_inwin_add() for more information on inner windows
 267  * @see elm_fileselector_entry_inwin_mode_get()
 268  */
 269 EAPI void                        elm_fileselector_entry_inwin_mode_set(Evas_Object *obj, Eina_Bool value);
 270
 271 /**
 272  * Get whether a given file selector entry widget's internal file
 273  * selector will raise an Elementary "inner window", instead of a
 274  * dedicated Elementary window.
 275  *
 276  * @param obj The file selector entry widget
 277  * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
 278  * if it will use a dedicated window
 279  *
 280  * @see elm_fileselector_entry_inwin_mode_set() for more details
 281  */
 282 EAPI Eina_Bool                   elm_fileselector_entry_inwin_mode_get(const Evas_Object *obj);
 283
 284 /**
 285  * Set the initial file system path for a given file selector entry
 286  * widget
 287  *
 288  * @param obj The file selector entry widget
 289  * @param path The path string
 290  *
 291  * It must be a <b>directory</b> path, which will have the contents
 292  * displayed initially in the file selector's view, when invoked
 293  * from @p obj. The default initial path is the @c "HOME"
 294  * environment variable's value.
 295  *
 296  * @see elm_fileselector_entry_path_get()
 297  */
 298 EAPI void                        elm_fileselector_entry_selected_set(Evas_Object *obj, const char *path);
 299
 300 /**
 301  * Get the parent directory's path to the latest file selection on
 302  * a given filer selector entry widget
 303  *
 304  * @param obj The file selector object
 305  * @return The (full) path of the directory of the last selection
 306  * on @p obj widget, a @b stringshared string
 307  *
 308  * @see elm_fileselector_entry_path_set()
 309  */
 310 EAPI const char                 *elm_fileselector_entry_selected_get(const Evas_Object *obj);
 311
 312 /**
 313  * @}
 314  */