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 *
  48                                  elm_fileselector_button_add(Evas_Object *parent)
  49 EINA_ARG_NONNULL(1);
  50
  51 /**
  52  * Set the label for a given file selector button widget
  53  *
  54  * @param obj The file selector button widget
  55  * @param label The text label to be displayed on @p obj
  56  *
  57  * @deprecated use elm_object_text_set() instead.
  58  */
  59 EINA_DEPRECATED EAPI void        elm_fileselector_button_label_set(Evas_Object *obj, const char *label) EINA_ARG_NONNULL(1);
  60
  61 /**
  62  * Get the label set for a given file selector button widget
  63  *
  64  * @param obj The file selector button widget
  65  * @return The button label
  66  *
  67  * @deprecated use elm_object_text_set() instead.
  68  */
  69 EINA_DEPRECATED EAPI const char *elm_fileselector_button_label_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  70
  71 /**
  72  * Set the icon on a given file selector button widget
  73  *
  74  * @param obj The file selector button widget
  75  * @param icon The icon object for the button
  76  *
  77  * Once the icon object is set, a previously set one will be
  78  * deleted. If you want to keep the latter, use the
  79  * elm_fileselector_button_icon_unset() function.
  80  *
  81  * @see elm_fileselector_button_icon_get()
  82  */
  83 EAPI void                        elm_fileselector_button_icon_set(Evas_Object *obj, Evas_Object *icon) EINA_ARG_NONNULL(1);
  84
  85 /**
  86  * Get the icon set for a given file selector button widget
  87  *
  88  * @param obj The file selector button widget
  89  * @return The icon object currently set on @p obj or @c NULL, if
  90  * none is
  91  *
  92  * @see elm_fileselector_button_icon_set()
  93  */
  94 EAPI Evas_Object                *elm_fileselector_button_icon_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  95
  96 /**
  97  * Unset the icon used in a given file selector button widget
  98  *
  99  * @param obj The file selector button widget
 100  * @return The icon object that was being used on @p obj or @c
 101  * NULL, on errors
 102  *
 103  * Unparent and return the icon object which was set for this
 104  * widget.
 105  *
 106  * @see elm_fileselector_button_icon_set()
 107  */
 108 EAPI Evas_Object                *elm_fileselector_button_icon_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 109
 110 /**
 111  * Set the title for a given file selector button widget's window
 112  *
 113  * @param obj The file selector button widget
 114  * @param title The title string
 115  *
 116  * This will change the window's title, when the file selector pops
 117  * out after a click on the button. Those windows have the default
 118  * (unlocalized) value of @c "Select a file" as titles.
 119  *
 120  * @note It will only take any effect if the file selector
 121  * button widget is @b not under "inwin mode".
 122  *
 123  * @see elm_fileselector_button_window_title_get()
 124  */
 125 EAPI void                        elm_fileselector_button_window_title_set(Evas_Object *obj, const char *title) EINA_ARG_NONNULL(1);
 126
 127 /**
 128  * Get the title set for a given file selector button widget's
 129  * window
 130  *
 131  * @param obj The file selector button widget
 132  * @return Title of the file selector button's window
 133  *
 134  * @see elm_fileselector_button_window_title_get() for more details
 135  */
 136 EAPI const char                 *elm_fileselector_button_window_title_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 137
 138 /**
 139  * Set the size of a given file selector button widget's window,
 140  * holding the file selector itself.
 141  *
 142  * @param obj The file selector button widget
 143  * @param width The window's width
 144  * @param height The window's height
 145  *
 146  * @note it will only take any effect if the file selector button
 147  * widget is @b not under "inwin mode". The default size for the
 148  * window (when applicable) is 400x400 pixels.
 149  *
 150  * @see elm_fileselector_button_window_size_get()
 151  */
 152 EAPI void                        elm_fileselector_button_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height) EINA_ARG_NONNULL(1);
 153
 154 /**
 155  * Get the size of a given file selector button widget's window,
 156  * holding the file selector itself.
 157  *
 158  * @param obj The file selector button widget
 159  * @param width Pointer into which to store the width value
 160  * @param height Pointer into which to store the height value
 161  *
 162  * @note Use @c NULL pointers on the size values you're not
 163  * interested in: they'll be ignored by the function.
 164  *
 165  * @see elm_fileselector_button_window_size_set(), for more details
 166  */
 167 EAPI void                        elm_fileselector_button_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height) EINA_ARG_NONNULL(1);
 168
 169 /**
 170  * Set the initial file system path for a given file selector
 171  * button widget
 172  *
 173  * @param obj The file selector button widget
 174  * @param path The path string
 175  *
 176  * It must be a <b>directory</b> path, which will have the contents
 177  * displayed initially in the file selector's view, when invoked
 178  * from @p obj. The default initial path is the @c "HOME"
 179  * environment variable's value.
 180  *
 181  * @see elm_fileselector_button_path_get()
 182  */
 183 EAPI void                        elm_fileselector_button_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
 184
 185 /**
 186  * Get the initial file system path set for a given file selector
 187  * button widget
 188  *
 189  * @param obj The file selector button widget
 190  * @return path The path string
 191  *
 192  * @see elm_fileselector_button_path_set() for more details
 193  */
 194 EAPI const char                 *elm_fileselector_button_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 195
 196 /**
 197  * Enable/disable a tree view in the given file selector button
 198  * widget's internal file selector
 199  *
 200  * @param obj The file selector button widget
 201  * @param value @c EINA_TRUE to enable tree view, @c EINA_FALSE to
 202  * disable
 203  *
 204  * This has the same effect as elm_fileselector_expandable_set(),
 205  * but now applied to a file selector button's internal file
 206  * selector.
 207  *
 208  * @note There's no way to put a file selector button's internal
 209  * file selector in "grid mode", as one may do with "pure" file
 210  * selectors.
 211  *
 212  * @see elm_fileselector_expandable_get()
 213  */
 214 EAPI void                        elm_fileselector_button_expandable_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 215
 216 /**
 217  * Get whether tree view is enabled for the given file selector
 218  * button widget's internal file selector
 219  *
 220  * @param obj The file selector button widget
 221  * @return @c EINA_TRUE if @p obj widget's internal file selector
 222  * is in tree view, @c EINA_FALSE otherwise (and or errors)
 223  *
 224  * @see elm_fileselector_expandable_set() for more details
 225  */
 226 EAPI Eina_Bool                   elm_fileselector_button_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 227
 228 /**
 229  * Set whether a given file selector button widget's internal file
 230  * selector is to display folders only or the directory contents,
 231  * as well.
 232  *
 233  * @param obj The file selector button widget
 234  * @param value @c EINA_TRUE to make @p obj widget's internal file
 235  * selector only display directories, @c EINA_FALSE to make files
 236  * to be displayed in it too
 237  *
 238  * This has the same effect as elm_fileselector_folder_only_set(),
 239  * but now applied to a file selector button's internal file
 240  * selector.
 241  *
 242  * @see elm_fileselector_folder_only_get()
 243  */
 244 EAPI void                        elm_fileselector_button_folder_only_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 245
 246 /**
 247  * Get whether a given file selector button widget's internal file
 248  * selector is displaying folders only or the directory contents,
 249  * as well.
 250  *
 251  * @param obj The file selector button widget
 252  * @return @c EINA_TRUE if @p obj widget's internal file
 253  * selector is only displaying directories, @c EINA_FALSE if files
 254  * are being displayed in it too (and on errors)
 255  *
 256  * @see elm_fileselector_button_folder_only_set() for more details
 257  */
 258 EAPI Eina_Bool                   elm_fileselector_button_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 259
 260 /**
 261  * Enable/disable the file name entry box where the user can type
 262  * in a name for a file, in a given file selector button widget's
 263  * internal file selector.
 264  *
 265  * @param obj The file selector button widget
 266  * @param value @c EINA_TRUE to make @p obj widget's internal
 267  * file selector a "saving dialog", @c EINA_FALSE otherwise
 268  *
 269  * This has the same effect as elm_fileselector_is_save_set(),
 270  * but now applied to a file selector button's internal file
 271  * selector.
 272  *
 273  * @see elm_fileselector_is_save_get()
 274  */
 275 EAPI void                        elm_fileselector_button_is_save_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 276
 277 /**
 278  * Get whether the given file selector button widget's internal
 279  * file selector is in "saving dialog" mode
 280  *
 281  * @param obj The file selector button 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_button_is_save_set() for more details
 287  */
 288 EAPI Eina_Bool                   elm_fileselector_button_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 289
 290 /**
 291  * Set whether a given file selector button 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 obj The file selector button widget
 296  * @param 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_button_inwin_mode_get()
 301  */
 302 EAPI void                        elm_fileselector_button_inwin_mode_set(Evas_Object *obj, Eina_Bool value) EINA_ARG_NONNULL(1);
 303
 304 /**
 305  * Get whether a given file selector button widget's internal file
 306  * selector will raise an Elementary "inner window", instead of a
 307  * dedicated Elementary window.
 308  *
 309  * @param obj The file selector button widget
 310  * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
 311  * if it will use a dedicated window
 312  *
 313  * @see elm_fileselector_button_inwin_mode_set() for more details
 314  */
 315 EAPI Eina_Bool                   elm_fileselector_button_inwin_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 316
 317 /**
 318  * @}
 319  */