src/lib/elc_fileselector_button.h

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