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