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