aboutsummaryrefslogtreecommitdiffstats
path: root/legacy/elementary/src/lib/elc_fileselector_button.h
blob: dde42847050fa7d6fcead5dcbb7d78092ecf7f81 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
/**
 * @defgroup File_Selector_Button File Selector Button
 *
 * @image html img/widget/fileselector_button/preview-00.png
 * @image latex img/widget/fileselector_button/preview-00.eps
 * @image html img/widget/fileselector_button/preview-01.png
 * @image latex img/widget/fileselector_button/preview-01.eps
 * @image html img/widget/fileselector_button/preview-02.png
 * @image latex img/widget/fileselector_button/preview-02.eps
 *
 * This is a button that, when clicked, creates an Elementary
 * window (or inner window) <b> with a @ref Fileselector "file
 * selector widget" within</b>. When a file is chosen, the (inner)
 * window is closed and the button emits a signal having the
 * selected file as it's @c event_info.
 *
 * This widget encapsulates operations on its internal file
 * selector on its own API. There is less control over its file
 * selector than that one would have instantiating one directly.
 *
 * The following styles are available for this button:
 * @li @c "default"
 * @li @c "anchor"
 * @li @c "hoversel_vertical"
 * @li @c "hoversel_vertical_entry"
 *
 * Smart callbacks one can register to:
 * - @c "file,chosen" - the user has selected a path, whose string
 *   pointer comes as the @c event_info data (a stringshared
 *   string)
 *
 * Default text parts of the fileselector_button widget that you can use for
 * are:
 * @li "default" - Label of the fileselector_button
 *
 * Default content parts of the fileselector_button widget that you can use for
 * are:
 * @li "icon" - Icon of the fileselector_button
 *
 * Supported elm_object common APIs.
 * @li elm_object_part_text_set
 * @li elm_object_part_text_get
 * @li elm_object_part_content_set
 * @li elm_object_part_content_get
 * @li elm_object_part_content_unset
 * @li elm_object_disabled_set
 * @li elm_object_disabled_get
 *
 * Here is an example on its usage:
 * @li @ref fileselector_button_example
 *
 * @see @ref File_Selector_Entry for a similar widget.
 * @{
 */

/**
 * Add a new file selector button widget to the given parent
 * Elementary (container) object
 *
 * @param parent The parent object
 * @return a new file selector button widget handle or @c NULL, on
 * errors
 */
EAPI Evas_Object                *elm_fileselector_button_add(Evas_Object *parent);

/**
 * Set the title for a given file selector button widget's window
 *
 * @param obj The file selector button widget
 * @param title The title string
 *
 * This will change the window's title, when the file selector pops
 * out after a click on the button. Those windows have the default
 * (unlocalized) value of @c "Select a file" as titles.
 *
 * @note It will only take any effect if the file selector
 * button widget is @b not under "inwin mode".
 *
 * @see elm_fileselector_button_window_title_get()
 */
EAPI void                        elm_fileselector_button_window_title_set(Evas_Object *obj, const char *title);

/**
 * Get the title set for a given file selector button widget's
 * window
 *
 * @param obj The file selector button widget
 * @return Title of the file selector button's window
 *
 * @see elm_fileselector_button_window_title_get() for more details
 */
EAPI const char                 *elm_fileselector_button_window_title_get(const Evas_Object *obj);

/**
 * Set the size of a given file selector button widget's window,
 * holding the file selector itself.
 *
 * @param obj The file selector button widget
 * @param width The window's width
 * @param height The window's height
 *
 * @note it will only take any effect if the file selector button
 * widget is @b not under "inwin mode". The default size for the
 * window (when applicable) is 400x400 pixels.
 *
 * @see elm_fileselector_button_window_size_get()
 */
EAPI void                        elm_fileselector_button_window_size_set(Evas_Object *obj, Evas_Coord width, Evas_Coord height);

/**
 * Get the size of a given file selector button widget's window,
 * holding the file selector itself.
 *
 * @param obj The file selector button widget
 * @param width Pointer into which to store the width value
 * @param height Pointer into which to store the height value
 *
 * @note Use @c NULL pointers on the size values you're not
 * interested in: they'll be ignored by the function.
 *
 * @see elm_fileselector_button_window_size_set(), for more details
 */
EAPI void                        elm_fileselector_button_window_size_get(const Evas_Object *obj, Evas_Coord *width, Evas_Coord *height);

/**
 * Set the initial file system path for a given file selector
 * button widget
 *
 * @param obj The file selector button widget
 * @param path The path string
 *
 * It must be a <b>directory</b> path, which will have the contents
 * displayed initially in the file selector's view, when invoked
 * from @p obj. The default initial path is the @c "HOME"
 * environment variable's value.
 *
 * @see elm_fileselector_button_path_get()
 */
EAPI void                        elm_fileselector_button_path_set(Evas_Object *obj, const char *path);

/**
 * Get the initial file system path set for a given file selector
 * button widget
 *
 * @param obj The file selector button widget
 * @return path The path string
 *
 * @see elm_fileselector_button_path_set() for more details
 */
EAPI const char                 *elm_fileselector_button_path_get(const Evas_Object *obj);

/**
 * Enable/disable a tree view in the given file selector button
 * widget's internal file selector
 *
 * @param obj The file selector button widget
 * @param value @c EINA_TRUE to enable tree view, @c EINA_FALSE to
 * disable
 *
 * This has the same effect as elm_fileselector_expandable_set(),
 * but now applied to a file selector button's internal file
 * selector.
 *
 * @note There's no way to put a file selector button's internal
 * file selector in "grid mode", as one may do with "pure" file
 * selectors.
 *
 * @see elm_fileselector_expandable_get()
 */
EAPI void                        elm_fileselector_button_expandable_set(Evas_Object *obj, Eina_Bool value);

/**
 * Get whether tree view is enabled for the given file selector
 * button widget's internal file selector
 *
 * @param obj The file selector button widget
 * @return @c EINA_TRUE if @p obj widget's internal file selector
 * is in tree view, @c EINA_FALSE otherwise (and or errors)
 *
 * @see elm_fileselector_expandable_set() for more details
 */
EAPI Eina_Bool                   elm_fileselector_button_expandable_get(const Evas_Object *obj);

/**
 * Set whether a given file selector button widget's internal file
 * selector is to display folders only or the directory contents,
 * as well.
 *
 * @param obj The file selector button widget
 * @param value @c EINA_TRUE to make @p obj widget's internal file
 * selector only display directories, @c EINA_FALSE to make files
 * to be displayed in it too
 *
 * This has the same effect as elm_fileselector_folder_only_set(),
 * but now applied to a file selector button's internal file
 * selector.
 *
 * @see elm_fileselector_folder_only_get()
 */
EAPI void                        elm_fileselector_button_folder_only_set(Evas_Object *obj, Eina_Bool value);

/**
 * Get whether a given file selector button widget's internal file
 * selector is displaying folders only or the directory contents,
 * as well.
 *
 * @param obj The file selector button widget
 * @return @c EINA_TRUE if @p obj widget's internal file
 * selector is only displaying directories, @c EINA_FALSE if files
 * are being displayed in it too (and on errors)
 *
 * @see elm_fileselector_button_folder_only_set() for more details
 */
EAPI Eina_Bool                   elm_fileselector_button_folder_only_get(const Evas_Object *obj);

/**
 * Enable/disable the file name entry box where the user can type
 * in a name for a file, in a given file selector button widget's
 * internal file selector.
 *
 * @param obj The file selector button widget
 * @param value @c EINA_TRUE to make @p obj widget's internal
 * file selector a "saving dialog", @c EINA_FALSE otherwise
 *
 * This has the same effect as elm_fileselector_is_save_set(),
 * but now applied to a file selector button's internal file
 * selector.
 *
 * @see elm_fileselector_is_save_get()
 */
EAPI void                        elm_fileselector_button_is_save_set(Evas_Object *obj, Eina_Bool value);

/**
 * Get whether the given file selector button widget's internal
 * file selector is in "saving dialog" mode
 *
 * @param obj The file selector button widget
 * @return @c EINA_TRUE, if @p obj widget's internal file selector
 * is in "saving dialog" mode, @c EINA_FALSE otherwise (and on
 * errors)
 *
 * @see elm_fileselector_button_is_save_set() for more details
 */
EAPI Eina_Bool                   elm_fileselector_button_is_save_get(const Evas_Object *obj);

/**
 * Set whether a given file selector button widget's internal file
 * selector will raise an Elementary "inner window", instead of a
 * dedicated Elementary window. By default, it won't.
 *
 * @param obj The file selector button widget
 * @param value @c EINA_TRUE to make it use an inner window, @c
 * EINA_TRUE to make it use a dedicated window
 *
 * @see elm_win_inwin_add() for more information on inner windows
 * @see elm_fileselector_button_inwin_mode_get()
 */
EAPI void                        elm_fileselector_button_inwin_mode_set(Evas_Object *obj, Eina_Bool value);

/**
 * Get whether a given file selector button widget's internal file
 * selector will raise an Elementary "inner window", instead of a
 * dedicated Elementary window.
 *
 * @param obj The file selector button widget
 * @return @c EINA_TRUE if will use an inner window, @c EINA_TRUE
 * if it will use a dedicated window
 *
 * @see elm_fileselector_button_inwin_mode_set() for more details
 */
EAPI Eina_Bool                   elm_fileselector_button_inwin_mode_get(const Evas_Object *obj);

/**
 * @}
 */