mobile/src/lib/elc_fileselector_entry.h

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