src/lib/elc_fileselector_button.h

   1    /**
   2     * @defgroup File_Selector_Button File Selector Button
   3     *
   4     * @image html img/widget/fileselector_button/preview-00.png
   5     * @image latex img/widget/fileselector_button/preview-00.eps
   6     * @image html img/widget/fileselector_button/preview-01.png
   7     * @image latex img/widget/fileselector_button/preview-01.eps
   8     * @image html img/widget/fileselector_button/preview-02.png
   9     * @image latex img/widget/fileselector_button/preview-02.eps
  10     *
  11     * This is a button that, when clicked, creates an Elementary
  12     * window (or inner window) <b> with a @ref Fileselector "file
  13     * selector widget" within</b>. When a file is chosen, the (inner)
  14     * window is closed and the button emits a signal having the
  15     * selected file as it's @c event_info.
  16     *
  17     * This widget encapsulates operations on its internal file
  18     * selector on its own API. There is less control over its file
  19     * selector than that one would have instatiating one directly.
  20     *
  21     * The following styles are available for this button:
  22     * @li @c "default"
  23     * @li @c "anchor"
  24     * @li @c "hoversel_vertical"
  25     * @li @c "hoversel_vertical_entry"
  26     *
  27     * Smart callbacks one can register to:
  28     * - @c "file,chosen" - the user has selected a path, whose string
  29     *   pointer comes as the @c event_info data (a stringshared
  30     *   string)
  31     *
  32     * Here is an example on its usage:
  33     * @li @ref fileselector_button_example
  34     *
  35     * @see @ref File_Selector_Entry for a similar widget.
  36     * @{
  37     */
  38
  39    /**
  40     * Add a new file selector button widget to the given parent
  41     * Elementary (container) object
  42     *
  43     * @param parent The parent object
  44     * @return a new file selector button widget handle or @c NULL, on
  45     * errors
  46     */
  47    EAPI Evas_Object *elm_fileselector_button_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  48
  49    /**
  50     * Set the label for a given file selector button widget
  51     *
  52     * @param obj The file selector button widget
  53     * @param label The text label to be displayed on @p obj
  54     *
  55     * @deprecated use elm_object_text_set() instead.
  56     */
  57    EINA_DEPRECATED EAPI void         elm_fileselector_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
  58
  59    /**
  60     * Get the label set for a given file selector button widget
  61     *
  62     * @param obj The file selector button widget
  63     * @return The button label
  64     *
  65     * @deprecated use elm_object_text_set() instead.
  66     */
  67    EINA_DEPRECATED EAPI const char  *elm_fileselector_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  68
  69    /**
  70     * Set the icon on a given file selector button widget
  71     *
  72     * @param obj The file selector button widget
  73     * @param icon The icon object for the button
  74     *
  75     * Once the icon object is set, a previously set one will be
  76     * deleted. If you want to keep the latter, use the
  77     * elm_fileselector_button_icon_unset() function.
  78     *
  79     * @see elm_fileselector_button_icon_get()
  80     */
  81    EAPI void         elm_fileselector_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
  82
  83    /**
  84     * Get the icon set for a given file selector button widget
  85     *
  86     * @param obj The file selector button widget
  87     * @return The icon object currently set on @p obj or @c NULL, if
  88     * none is
  89     *
  90     * @see elm_fileselector_button_icon_set()
  91     */
  92    EAPI Evas_Object *elm_fileselector_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  93
  94    /**
  95     * Unset the icon used in a given file selector button widget
  96     *
  97     * @param obj The file selector button widget
  98     * @return The icon object that was being used on @p obj or @c
  99     * NULL, on errors
 100     *
 101     * Unparent and return the icon object which was set for this
 102     * widget.
 103     *
 104     * @see elm_fileselector_button_icon_set()
 105     */
 106    EAPI Evas_Object *elm_fileselector_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 107
 108    /**
 109     * Set the title for a given file selector button widget's window
 110     *
 111     * @param obj The file selector button widget
 112     * @param title The title string
 113     *
 114     * This will change the window's title, when the file selector pops
 115     * out after a click on the button. Those windows have the default
 116     * (unlocalized) value of @c "Select a file" as titles.
 117     *
 118     * @note It will only take any effect if the file selector
 119     * button widget is @b not under "inwin mode".
 120     *
 121     * @see elm_fileselector_button_window_title_get()
 122     */
 123    EAPI void         elm_fileselector_button_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
 124
 125    /**
 126     * Get the title set for a given file selector button widget's
 127     * window
 128     *
 129     * @param obj The file selector button widget
 130     * @return Title of the file selector button's window
 131     *
 132     * @see elm_fileselector_button_window_title_get() for more details
 133     */
 134    EAPI const char  *elm_fileselector_button_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 135
 136    /**
 137     * Set the size of a given file selector button widget's window,
 138     * holding the file selector itself.
 139     *
 140     * @param obj The file selector button widget
 141     * @param width The window's width
 142     * @param height The window's height
 143     *
 144     * @note it will only take any effect if the file selector button
 145     * widget is @b not under "inwin mode". The default size for the
 146     * window (when applicable) is 400x400 pixels.
 147     *
 148     * @see elm_fileselector_button_window_size_get()
 149     */
 150    EAPI void         elm_fileselector_button_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
 151
 152    /**
 153     * Get the size of a given file selector button widget's window,
 154     * holding the file selector itself.
 155     *
 156     * @param obj The file selector button widget
 157     * @param width Pointer into which to store the width value
 158     * @param height Pointer into which to store the height value
 159     *
 160     * @note Use @c NULL pointers on the size values you're not
 161     * interested in: they'll be ignored by the function.
 162     *
 163     * @see elm_fileselector_button_window_size_set(), for more details
 164     */
 165    EAPI void         elm_fileselector_button_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
 166
 167    /**
 168     * Set the initial file system path for a given file selector
 169     * button widget
 170     *
 171     * @param obj The file selector button widget
 172     * @param path The path string
 173     *
 174     * It must be a <b>directory</b> path, which will have the contents
 175     * displayed initially in the file selector's view, when invoked
 176     * from @p obj. The default initial path is the @c "HOME"
 177     * environment variable's value.
 178     *
 179     * @see elm_fileselector_button_path_get()
 180     */
 181    EAPI void         elm_fileselector_button_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
 182
 183    /**
 184     * Get the initial file system path set for a given file selector
 185     * button widget
 186     *
 187     * @param obj The file selector button widget
 188     * @return path The path string
 189     *
 190     * @see elm_fileselector_button_path_set() for more details
 191     */
 192    EAPI const char  *elm_fileselector_button_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 193
 194    /**
 195     * Enable/disable a tree view in the given file selector button
 196     * widget's internal file selector
 197     *
 198     * @param obj The file selector button widget
 199     * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
 200     * disable
 201     *
 202     * This has the same effect as elm_fileselector_expandable_set(),
 203     * but now applied to a file selector button's internal file
 204     * selector.
 205     *
 206     * @note There's no way to put a file selector button's internal
 207     * file selector in "grid mode", as one may do with "pure" file
 208     * selectors.
 209     *
 210     * @see elm_fileselector_expandable_get()
 211     */
 212    EAPI void         elm_fileselector_button_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 213
 214    /**
 215     * Get whether tree view is enabled for the given file selector
 216     * button widget's internal file selector
 217     *
 218     * @param obj The file selector button widget
 219     * @return @c EINA_TRUE if @p obj widget's internal file selector
 220     * is in tree view, @c EINA_FALSE otherwise (and or errors)
 221     *
 222     * @see elm_fileselector_expandable_set() for more details
 223     */
 224    EAPI Eina_Bool    elm_fileselector_button_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 225
 226    /**
 227     * Set whether a given file selector button widget's internal file
 228     * selector is to display folders only or the directory contents,
 229     * as well.
 230     *
 231     * @param obj The file selector button widget
 232     * @param only @c EINA_TRUE to make @p obj widget's internal file
 233     * selector only display directories, @c EINA_FALSE to make files
 234     * to be displayed in it too
 235     *
 236     * This has the same effect as elm_fileselector_folder_only_set(),
 237     * but now applied to a file selector button's internal file
 238     * selector.
 239     *
 240     * @see elm_fileselector_folder_only_get()
 241     */
 242    EAPI void         elm_fileselector_button_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 243
 244    /**
 245     * Get whether a given file selector button widget's internal file
 246     * selector is displaying folders only or the directory contents,
 247     * as well.
 248     *
 249     * @param obj The file selector button widget
 250     * @return @c EINA_TRUE if @p obj widget's internal file
 251     * selector is only displaying directories, @c EINA_FALSE if files
 252     * are being displayed in it too (and on errors)
 253     *
 254     * @see elm_fileselector_button_folder_only_set() for more details
 255     */
 256    EAPI Eina_Bool    elm_fileselector_button_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 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 button widget's
 261     * internal file selector.
 262     *
 263     * @param obj The file selector button widget
 264     * @param is_save @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 button's internal file
 269     * selector.
 270     *
 271     * @see elm_fileselector_is_save_get()
 272     */
 273    EAPI void         elm_fileselector_button_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 274
 275    /**
 276     * Get whether the given file selector button widget's internal
 277     * file selector is in "saving dialog" mode
 278     *
 279     * @param obj The file selector button 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_button_is_save_set() for more details
 285     */
 286    EAPI Eina_Bool    elm_fileselector_button_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 287
 288    /**
 289     * Set whether a given file selector button widget's internal file
 290     * selector will raise an Elementary "inner window", instead of a
 291     * dedicated Elementary window. By default, it won't.
 292     *
 293     * @param obj The file selector button widget
 294     * @param value @c EINA_TRUE to make it use an inner window, @c
 295     * EINA_TRUE to make it use a dedicated window
 296     *
 297     * @see elm_win_inwin_add() for more information on inner windows
 298     * @see elm_fileselector_button_inwin_mode_get()
 299     */
 300    EAPI void         elm_fileselector_button_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 301
 302    /**
 303     * Get whether a given file selector button widget's internal file
 304     * selector will raise an Elementary "inner window", instead of a
 305     * dedicated Elementary window.
 306     *
 307     * @param obj The file selector button widget
 308     * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
 309     * if it will use a dedicated window
 310     *
 311     * @see elm_fileselector_button_inwin_mode_set() for more details
 312     */
 313    EAPI Eina_Bool    elm_fileselector_button_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 314
 315    /**
 316     * @}
 317     */
 318