summaryrefslogtreecommitdiff
path: root/legacy/elementary/src/lib/elc_fileselector.h
diff options
context:
space:
mode:
authorCarsten Haitzler <raster@rasterman.com>2011-12-30 07:20:48 +0000
committerCarsten Haitzler <raster@rasterman.com>2011-12-30 07:20:48 +0000
commit0930fdcd527197fa0973922a041d43482a9eaf38 (patch)
tree29409575029b4fb3767e31cfb80cfd6addaa4edf /legacy/elementary/src/lib/elc_fileselector.h
parent39f63f3bf617c41e890c0f528581da43437fc593 (diff)
fomatting of headers -> fixup. and documentation fixing.
SVN revision: 66667
Diffstat (limited to 'legacy/elementary/src/lib/elc_fileselector.h')
-rw-r--r--legacy/elementary/src/lib/elc_fileselector.h591
1 files changed, 296 insertions, 295 deletions
diff --git a/legacy/elementary/src/lib/elc_fileselector.h b/legacy/elementary/src/lib/elc_fileselector.h
index 24048b6..eafcbea 100644
--- a/legacy/elementary/src/lib/elc_fileselector.h
+++ b/legacy/elementary/src/lib/elc_fileselector.h
@@ -1,313 +1,314 @@
1 /** 1/**
2 * @defgroup Fileselector File Selector 2 * @defgroup Fileselector File Selector
3 * 3 *
4 * @image html img/widget/fileselector/preview-00.png 4 * @image html img/widget/fileselector/preview-00.png
5 * @image latex img/widget/fileselector/preview-00.eps 5 * @image latex img/widget/fileselector/preview-00.eps
6 * 6 *
7 * A file selector is a widget that allows a user to navigate 7 * A file selector is a widget that allows a user to navigate
8 * through a file system, reporting file selections back via its 8 * through a file system, reporting file selections back via its
9 * API. 9 * API.
10 * 10 *
11 * It contains shortcut buttons for home directory (@c ~) and to 11 * It contains shortcut buttons for home directory (@c ~) and to
12 * jump one directory upwards (..), as well as cancel/ok buttons to 12 * jump one directory upwards (..), as well as cancel/ok buttons to
13 * confirm/cancel a given selection. After either one of those two 13 * confirm/cancel a given selection. After either one of those two
14 * former actions, the file selector will issue its @c "done" smart 14 * former actions, the file selector will issue its @c "done" smart
15 * callback. 15 * callback.
16 * 16 *
17 * There's a text entry on it, too, showing the name of the current 17 * There's a text entry on it, too, showing the name of the current
18 * selection. There's the possibility of making it editable, so it 18 * selection. There's the possibility of making it editable, so it
19 * is useful on file saving dialogs on applications, where one 19 * is useful on file saving dialogs on applications, where one
20 * gives a file name to save contents to, in a given directory in 20 * gives a file name to save contents to, in a given directory in
21 * the system. This custom file name will be reported on the @c 21 * the system. This custom file name will be reported on the @c
22 * "done" smart callback (explained in sequence). 22 * "done" smart callback (explained in sequence).
23 * 23 *
24 * Finally, it has a view to display file system items into in two 24 * Finally, it has a view to display file system items into in two
25 * possible forms: 25 * possible forms:
26 * - list 26 * - list
27 * - grid 27 * - grid
28 * 28 *
29 * If Elementary is built with support of the Ethumb thumbnailing 29 * If Elementary is built with support of the Ethumb thumbnailing
30 * library, the second form of view will display preview thumbnails 30 * library, the second form of view will display preview thumbnails
31 * of files which it supports. 31 * of files which it supports.
32 * 32 *
33 * Smart callbacks one can register to: 33 * Smart callbacks one can register to:
34 * 34 *
35 * - @c "selected" - the user has clicked on a file (when not in 35 * - @c "selected" - the user has clicked on a file (when not in
36 * folders-only mode) or directory (when in folders-only mode) 36 * folders-only mode) or directory (when in folders-only mode)
37 * - @c "directory,open" - the list has been populated with new 37 * - @c "directory,open" - the list has been populated with new
38 * content (@c event_info is a pointer to the directory's 38 * content (@c event_info is a pointer to the directory's
39 * path, a @b stringshared string) 39 * path, a @b stringshared string)
40 * - @c "done" - the user has clicked on the "ok" or "cancel" 40 * - @c "done" - the user has clicked on the "ok" or "cancel"
41 * buttons (@c event_info is a pointer to the selection's 41 * buttons (@c event_info is a pointer to the selection's
42 * path, a @b stringshared string) 42 * path, a @b stringshared string)
43 * 43 *
44 * Here is an example on its usage: 44 * Here is an example on its usage:
45 * @li @ref fileselector_example 45 * @li @ref fileselector_example
46 */ 46 */
47 47
48 /** 48/**
49 * @addtogroup Fileselector 49 * @addtogroup Fileselector
50 * @{ 50 * @{
51 */ 51 */
52 52
53 /** 53/**
54 * Defines how a file selector widget is to layout its contents 54 * Defines how a file selector widget is to layout its contents
55 * (file system entries). 55 * (file system entries).
56 */ 56 */
57 typedef enum _Elm_Fileselector_Mode 57typedef enum _Elm_Fileselector_Mode
58 { 58{
59 ELM_FILESELECTOR_LIST = 0, /**< layout as a list */ 59 ELM_FILESELECTOR_LIST = 0, /**< layout as a list */
60 ELM_FILESELECTOR_GRID, /**< layout as a grid */ 60 ELM_FILESELECTOR_GRID, /**< layout as a grid */
61 ELM_FILESELECTOR_LAST /**< sentinel (helper) value, not used */ 61 ELM_FILESELECTOR_LAST /**< sentinel (helper) value, not used */
62 } Elm_Fileselector_Mode; 62} Elm_Fileselector_Mode;
63 63
64 /** 64/**
65 * Add a new file selector widget to the given parent Elementary 65 * Add a new file selector widget to the given parent Elementary
66 * (container) object 66 * (container) object
67 * 67 *
68 * @param parent The parent object 68 * @param parent The parent object
69 * @return a new file selector widget handle or @c NULL, on errors 69 * @return a new file selector widget handle or @c NULL, on errors
70 * 70 *
71 * This function inserts a new file selector widget on the canvas. 71 * This function inserts a new file selector widget on the canvas.
72 * 72 *
73 * @ingroup Fileselector 73 * @ingroup Fileselector
74 */ 74 */
75 EAPI Evas_Object *elm_fileselector_add(Evas_Object *parent) EINA_ARG_NONNULL(1); 75EAPI Evas_Object *
76 elm_fileselector_add(Evas_Object *parent)
77EINA_ARG_NONNULL(1);
76 78
77 /** 79/**
78 * Enable/disable the file name entry box where the user can type 80 * Enable/disable the file name entry box where the user can type
79 * in a name for a file, in a given file selector widget 81 * in a name for a file, in a given file selector widget
80 * 82 *
81 * @param obj The file selector object 83 * @param obj The file selector object
82 * @param is_save @c EINA_TRUE to make the file selector a "saving 84 * @param is_save @c EINA_TRUE to make the file selector a "saving
83 * dialog", @c EINA_FALSE otherwise 85 * dialog", @c EINA_FALSE otherwise
84 * 86 *
85 * Having the entry editable is useful on file saving dialogs on 87 * Having the entry editable is useful on file saving dialogs on
86 * applications, where one gives a file name to save contents to, 88 * applications, where one gives a file name to save contents to,
87 * in a given directory in the system. This custom file name will 89 * in a given directory in the system. This custom file name will
88 * be reported on the @c "done" smart callback. 90 * be reported on the @c "done" smart callback.
89 * 91 *
90 * @see elm_fileselector_is_save_get() 92 * @see elm_fileselector_is_save_get()
91 * 93 *
92 * @ingroup Fileselector 94 * @ingroup Fileselector
93 */ 95 */
94 EAPI void elm_fileselector_is_save_set(Evas_Object *obj, Eina_Bool is_save) EINA_ARG_NONNULL(1); 96EAPI void elm_fileselector_is_save_set(Evas_Object *obj, Eina_Bool is_save) EINA_ARG_NONNULL(1);
95 97
96 /** 98/**
97 * Get whether the given file selector is in "saving dialog" mode 99 * Get whether the given file selector is in "saving dialog" mode
98 * 100 *
99 * @param obj The file selector object 101 * @param obj The file selector object
100 * @return @c EINA_TRUE, if the file selector is in "saving dialog" 102 * @return @c EINA_TRUE, if the file selector is in "saving dialog"
101 * mode, @c EINA_FALSE otherwise (and on errors) 103 * mode, @c EINA_FALSE otherwise (and on errors)
102 * 104 *
103 * @see elm_fileselector_is_save_set() for more details 105 * @see elm_fileselector_is_save_set() for more details
104 * 106 *
105 * @ingroup Fileselector 107 * @ingroup Fileselector
106 */ 108 */
107 EAPI Eina_Bool elm_fileselector_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 109EAPI Eina_Bool elm_fileselector_is_save_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
108 110
109 /** 111/**
110 * Enable/disable folder-only view for a given file selector widget 112 * Enable/disable folder-only view for a given file selector widget
111 * 113 *
112 * @param obj The file selector object 114 * @param obj The file selector object
113 * @param only @c EINA_TRUE to make @p obj only display 115 * @param only @c EINA_TRUE to make @p obj only display
114 * directories, @c EINA_FALSE to make files to be displayed in it 116 * directories, @c EINA_FALSE to make files to be displayed in it
115 * too 117 * too
116 * 118 *
117 * If enabled, the widget's view will only display folder items, 119 * If enabled, the widget's view will only display folder items,
118 * naturally. 120 * naturally.
119 * 121 *
120 * @see elm_fileselector_folder_only_get() 122 * @see elm_fileselector_folder_only_get()
121 * 123 *
122 * @ingroup Fileselector 124 * @ingroup Fileselector
123 */ 125 */
124 EAPI void elm_fileselector_folder_only_set(Evas_Object *obj, Eina_Bool only) EINA_ARG_NONNULL(1); 126EAPI void elm_fileselector_folder_only_set(Evas_Object *obj, Eina_Bool only) EINA_ARG_NONNULL(1);
125 127
126 /** 128/**
127 * Get whether folder-only view is set for a given file selector 129 * Get whether folder-only view is set for a given file selector
128 * widget 130 * widget
129 * 131 *
130 * @param obj The file selector object 132 * @param obj The file selector object
131 * @return only @c EINA_TRUE if @p obj is only displaying 133 * @return only @c EINA_TRUE if @p obj is only displaying
132 * directories, @c EINA_FALSE if files are being displayed in it 134 * directories, @c EINA_FALSE if files are being displayed in it
133 * too (and on errors) 135 * too (and on errors)
134 * 136 *
135 * @see elm_fileselector_folder_only_get() 137 * @see elm_fileselector_folder_only_get()
136 * 138 *
137 * @ingroup Fileselector 139 * @ingroup Fileselector
138 */ 140 */
139 EAPI Eina_Bool elm_fileselector_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 141EAPI Eina_Bool elm_fileselector_folder_only_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
140 142
141 /** 143/**
142 * Enable/disable the "ok" and "cancel" buttons on a given file 144 * Enable/disable the "ok" and "cancel" buttons on a given file
143 * selector widget 145 * selector widget
144 * 146 *
145 * @param obj The file selector object 147 * @param obj The file selector object
146 * @param only @c EINA_TRUE to show them, @c EINA_FALSE to hide. 148 * @param buttons @c EINA_TRUE to show buttons, @c EINA_FALSE to hide.
147 * 149 *
148 * @note A file selector without those buttons will never emit the 150 * @note A file selector without those buttons will never emit the
149 * @c "done" smart event, and is only usable if one is just hooking 151 * @c "done" smart event, and is only usable if one is just hooking
150 * to the other two events. 152 * to the other two events.
151 * 153 *
152 * @see elm_fileselector_buttons_ok_cancel_get() 154 * @see elm_fileselector_buttons_ok_cancel_get()
153 * 155 *
154 * @ingroup Fileselector 156 * @ingroup Fileselector
155 */ 157 */
156 EAPI void elm_fileselector_buttons_ok_cancel_set(Evas_Object *obj, Eina_Bool buttons) EINA_ARG_NONNULL(1); 158EAPI void elm_fileselector_buttons_ok_cancel_set(Evas_Object *obj, Eina_Bool buttons) EINA_ARG_NONNULL(1);
157 159
158 /** 160/**
159 * Get whether the "ok" and "cancel" buttons on a given file 161 * Get whether the "ok" and "cancel" buttons on a given file
160 * selector widget are being shown. 162 * selector widget are being shown.
161 * 163 *
162 * @param obj The file selector object 164 * @param obj The file selector object
163 * @return @c EINA_TRUE if they are being shown, @c EINA_FALSE 165 * @return @c EINA_TRUE if they are being shown, @c EINA_FALSE
164 * otherwise (and on errors) 166 * otherwise (and on errors)
165 * 167 *
166 * @see elm_fileselector_buttons_ok_cancel_set() for more details 168 * @see elm_fileselector_buttons_ok_cancel_set() for more details
167 * 169 *
168 * @ingroup Fileselector 170 * @ingroup Fileselector
169 */ 171 */
170 EAPI Eina_Bool elm_fileselector_buttons_ok_cancel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 172EAPI Eina_Bool elm_fileselector_buttons_ok_cancel_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
171 173
172 /** 174/**
173 * Enable/disable a tree view in the given file selector widget, 175 * Enable/disable a tree view in the given file selector widget,
174 * <b>if it's in @c #ELM_FILESELECTOR_LIST mode</b> 176 * <b>if it's in @c #ELM_FILESELECTOR_LIST mode</b>
175 * 177 *
176 * @param obj The file selector object 178 * @param obj The file selector object
177 * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to 179 * @param expand @c EINA_TRUE to enable tree view, @c EINA_FALSE to
178 * disable 180 * disable
179 * 181 *
180 * In a tree view, arrows are created on the sides of directories, 182 * In a tree view, arrows are created on the sides of directories,
181 * allowing them to expand in place. 183 * allowing them to expand in place.
182 * 184 *
183 * @note If it's in other mode, the changes made by this function 185 * @note If it's in other mode, the changes made by this function
184 * will only be visible when one switches back to "list" mode. 186 * will only be visible when one switches back to "list" mode.
185 * 187 *
186 * @see elm_fileselector_expandable_get() 188 * @see elm_fileselector_expandable_get()
187 * 189 *
188 * @ingroup Fileselector 190 * @ingroup Fileselector
189 */ 191 */
190 EAPI void elm_fileselector_expandable_set(Evas_Object *obj, Eina_Bool expand) EINA_ARG_NONNULL(1); 192EAPI void elm_fileselector_expandable_set(Evas_Object *obj, Eina_Bool expand) EINA_ARG_NONNULL(1);
191 193
192 /** 194/**
193 * Get whether tree view is enabled for the given file selector 195 * Get whether tree view is enabled for the given file selector
194 * widget 196 * widget
195 * 197 *
196 * @param obj The file selector object 198 * @param obj The file selector object
197 * @return @c EINA_TRUE if @p obj is in tree view, @c EINA_FALSE 199 * @return @c EINA_TRUE if @p obj is in tree view, @c EINA_FALSE
198 * otherwise (and or errors) 200 * otherwise (and or errors)
199 * 201 *
200 * @see elm_fileselector_expandable_set() for more details 202 * @see elm_fileselector_expandable_set() for more details
201 * 203 *
202 * @ingroup Fileselector 204 * @ingroup Fileselector
203 */ 205 */
204 EAPI Eina_Bool elm_fileselector_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 206EAPI Eina_Bool elm_fileselector_expandable_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
205 207
206 /** 208/**
207 * Set, programmatically, the @b directory that a given file 209 * Set, programmatically, the @b directory that a given file
208 * selector widget will display contents from 210 * selector widget will display contents from
209 * 211 *
210 * @param obj The file selector object 212 * @param obj The file selector object
211 * @param path The path to display in @p obj 213 * @param path The path to display in @p obj
212 * 214 *
213 * This will change the @b directory that @p obj is displaying. It 215 * This will change the @b directory that @p obj is displaying. It
214 * will also clear the text entry area on the @p obj object, which 216 * will also clear the text entry area on the @p obj object, which
215 * displays select files' names. 217 * displays select files' names.
216 * 218 *
217 * @see elm_fileselector_path_get() 219 * @see elm_fileselector_path_get()
218 * 220 *
219 * @ingroup Fileselector 221 * @ingroup Fileselector
220 */ 222 */
221 EAPI void elm_fileselector_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1); 223EAPI void elm_fileselector_path_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
222 224
223 /** 225/**
224 * Get the parent directory's path that a given file selector 226 * Get the parent directory's path that a given file selector
225 * widget is displaying 227 * widget is displaying
226 * 228 *
227 * @param obj The file selector object 229 * @param obj The file selector object
228 * @return The (full) path of the directory the file selector is 230 * @return The (full) path of the directory the file selector is
229 * displaying, a @b stringshared string 231 * displaying, a @b stringshared string
230 * 232 *
231 * @see elm_fileselector_path_set() 233 * @see elm_fileselector_path_set()
232 * 234 *
233 * @ingroup Fileselector 235 * @ingroup Fileselector
234 */ 236 */
235 EAPI const char *elm_fileselector_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 237EAPI const char *elm_fileselector_path_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
236 238
237 /** 239/**
238 * Set, programmatically, the currently selected file/directory in 240 * Set, programmatically, the currently selected file/directory in
239 * the given file selector widget 241 * the given file selector widget
240 * 242 *
241 * @param obj The file selector object 243 * @param obj The file selector object
242 * @param path The (full) path to a file or directory 244 * @param path The (full) path to a file or directory
243 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. The 245 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. The
244 * latter case occurs if the directory or file pointed to do not 246 * latter case occurs if the directory or file pointed to do not
245 * exist. 247 * exist.
246 * 248 *
247 * @see elm_fileselector_selected_get() 249 * @see elm_fileselector_selected_get()
248 * 250 *
249 * @ingroup Fileselector 251 * @ingroup Fileselector
250 */ 252 */
251 EAPI Eina_Bool elm_fileselector_selected_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1); 253EAPI Eina_Bool elm_fileselector_selected_set(Evas_Object *obj, const char *path) EINA_ARG_NONNULL(1);
252 254
253 /** 255/**
254 * Get the currently selected item's (full) path, in the given file 256 * Get the currently selected item's (full) path, in the given file
255 * selector widget 257 * selector widget
256 * 258 *
257 * @param obj The file selector object 259 * @param obj The file selector object
258 * @return The absolute path of the selected item, a @b 260 * @return The absolute path of the selected item, a @b
259 * stringshared string 261 * stringshared string
260 * 262 *
261 * @note Custom editions on @p obj object's text entry, if made, 263 * @note Custom editions on @p obj object's text entry, if made,
262 * will appear on the return string of this function, naturally. 264 * will appear on the return string of this function, naturally.
263 * 265 *
264 * @see elm_fileselector_selected_set() for more details 266 * @see elm_fileselector_selected_set() for more details
265 * 267 *
266 * @ingroup Fileselector 268 * @ingroup Fileselector
267 */ 269 */
268 EAPI const char *elm_fileselector_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 270EAPI const char *elm_fileselector_selected_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
269 271
270 /** 272/**
271 * Set the mode in which a given file selector widget will display 273 * Set the mode in which a given file selector widget will display
272 * (layout) file system entries in its view 274 * (layout) file system entries in its view
273 * 275 *
274 * @param obj The file selector object 276 * @param obj The file selector object
275 * @param mode The mode of the fileselector, being it one of 277 * @param mode The mode of the fileselector, being it one of
276 * #ELM_FILESELECTOR_LIST (default) or #ELM_FILESELECTOR_GRID. The 278 * #ELM_FILESELECTOR_LIST (default) or #ELM_FILESELECTOR_GRID. The
277 * first one, naturally, will display the files in a list. The 279 * first one, naturally, will display the files in a list. The
278 * latter will make the widget to display its entries in a grid 280 * latter will make the widget to display its entries in a grid
279 * form. 281 * form.
280 * 282 *
281 * @note By using elm_fileselector_expandable_set(), the user may 283 * @note By using elm_fileselector_expandable_set(), the user may
282 * trigger a tree view for that list. 284 * trigger a tree view for that list.
283 * 285 *
284 * @note If Elementary is built with support of the Ethumb 286 * @note If Elementary is built with support of the Ethumb
285 * thumbnailing library, the second form of view will display 287 * thumbnailing library, the second form of view will display
286 * preview thumbnails of files which it supports. You must have 288 * preview thumbnails of files which it supports. You must have
287 * elm_need_ethumb() called in your Elementary for thumbnailing to 289 * elm_need_ethumb() called in your Elementary for thumbnailing to
288 * work, though. 290 * work, though.
289 * 291 *
290 * @see elm_fileselector_expandable_set(). 292 * @see elm_fileselector_expandable_set().
291 * @see elm_fileselector_mode_get(). 293 * @see elm_fileselector_mode_get().
292 * 294 *
293 * @ingroup Fileselector 295 * @ingroup Fileselector
294 */ 296 */
295 EAPI void elm_fileselector_mode_set(Evas_Object *obj, Elm_Fileselector_Mode mode) EINA_ARG_NONNULL(1); 297EAPI void elm_fileselector_mode_set(Evas_Object *obj, Elm_Fileselector_Mode mode) EINA_ARG_NONNULL(1);
296 298
297 /** 299/**
298 * Get the mode in which a given file selector widget is displaying 300 * Get the mode in which a given file selector widget is displaying
299 * (layouting) file system entries in its view 301 * (layouting) file system entries in its view
300 * 302 *
301 * @param obj The fileselector object 303 * @param obj The fileselector object
302 * @return The mode in which the fileselector is at 304 * @return The mode in which the fileselector is at
303 * 305 *
304 * @see elm_fileselector_mode_set() for more details 306 * @see elm_fileselector_mode_set() for more details
305 * 307 *
306 * @ingroup Fileselector 308 * @ingroup Fileselector
307 */ 309 */
308 EAPI Elm_Fileselector_Mode elm_fileselector_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1); 310EAPI Elm_Fileselector_Mode elm_fileselector_mode_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
309
310 /**
311 * @}
312 */
313 311
312/**
313 * @}
314 */