src/lib/elc_fileselector_button.h

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