src/lib/elc_fileselector_entry.h

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