568fb2876ec2f39007839e1f965f960b130e4c19
[vlc.git] / include / vlc_dialog.h
1 /*****************************************************************************
2  * vlc_dialog.h: user interaction dialogs
3  *****************************************************************************
4  * Copyright (C) 2009 RĂ©mi Denis-Courmont
5  * Copyright (C) 2016 VLC authors and VideoLAN
6  *
7  * This program is free software; you can redistribute it and/or modify it
8  * under the terms of the GNU Lesser General Public License as published by
9  * the Free Software Foundation; either version 2.1 of the License, or
10  * (at your option) any later version.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public License
18  * along with this program; if not, write to the Free Software Foundation,
19  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
20  *****************************************************************************/
21
22 #ifndef VLC_DIALOG_H_
23 #define VLC_DIALOG_H_
24 # include <stdarg.h>
25
26 typedef struct vlc_dialog_provider vlc_dialog_provider;
27 typedef struct vlc_dialog_id vlc_dialog_id;
28 typedef struct extension_dialog_t extension_dialog_t;
29
30 /* Called from src/libvlc.c */
31 int
32 libvlc_InternalDialogInit(libvlc_int_t *p_libvlc);
33
34 /* Called from src/libvlc.c */
35 void
36 libvlc_InternalDialogClean(libvlc_int_t *p_libvlc);
37
38 /**
39  * @defgroup vlc_dialog VLC dialog
40  * @ingroup interface
41  * @{
42  * @file
43  * This file declares VLC dialog functions
44  * @defgroup vlc_dialog_api VLC dialog functions
45  * In order to interact with the user
46  * @{
47  */
48
49 /**
50  * Dialog question type, see vlc_dialog_wait_question()
51  */
52 typedef enum vlc_dialog_question_type
53 {
54     VLC_DIALOG_QUESTION_NORMAL,
55     VLC_DIALOG_QUESTION_WARNING,
56     VLC_DIALOG_QUESTION_CRITICAL,
57 } vlc_dialog_question_type;
58
59 /**
60  * Sends an error message
61  *
62  * This function returns immediately
63  *
64  * @param p_obj the VLC object emitting the error
65  * @param psz_title title of the error dialog
66  * @param psz_fmt format string for the error message
67  * @return VLC_SUCCESS on success, or a VLC error code on error
68  */
69 VLC_API int
70 vlc_dialog_display_error(vlc_object_t *p_obj, const char *psz_title,
71                          const char *psz_fmt, ...) VLC_FORMAT(3,4);
72 #define vlc_dialog_display_error(a, b, c, ...) \
73     vlc_dialog_display_error(VLC_OBJECT(a), b, c, ##__VA_ARGS__)
74
75 /**
76  * Sends an error message
77  *
78  * Equivalent to vlc_dialog_display_error() expect that it's called with a
79  * va_list.
80  */
81 VLC_API int
82 vlc_dialog_display_error_va(vlc_object_t *p_obj, const char *psz_title,
83                             const char *psz_fmt, va_list ap);
84
85 /**
86  * Requests an user name and a password
87  *
88  * This function waits until the user dismisses the dialog or responds. It's
89  * interruptible via vlc_interrupt. In that case, vlc_dialog_cbs.pf_cancel()
90  * will be invoked. If p_store is not NULL, the user will be asked to store the
91  * password or not.
92  *
93  * @param p_obj the VLC object emitting the dialog
94  * @param ppsz_username a pointer to the user name provided by the user, it
95  * must be freed with free() on success
96  * @param ppsz_password a pointer to the password provided by the user, it must
97  * be freed with free() on success
98  * @param p_store a pointer to the store answer provided by the user (optional)
99  * @param psz_default_username default user name proposed
100  * @param psz_title title of the login dialog
101  * @param psz_fmt format string for the login message
102  * @return < 0 on error, 0 if the user cancelled it, and 1 if ppsz_username and
103  * ppsz_password are valid.
104  */
105 VLC_API int
106 vlc_dialog_wait_login(vlc_object_t *p_obj, char **ppsz_username,
107                       char **ppsz_password, bool *p_store,
108                       const char *psz_default_username,
109                       const char *psz_title, const char *psz_fmt, ...)
110                       VLC_FORMAT(7,8);
111 #define vlc_dialog_wait_login(a, b, c, d, e, f, g, ...) \
112     vlc_dialog_wait_login(VLC_OBJECT(a), b, c, d, e, f, g, ##__VA_ARGS__)
113
114 /**
115  * Requests an user name and a password
116  *
117  * Equivalent to vlc_dialog_wait_login() expect that it's called with a
118  * va_list.
119  */
120 VLC_API int
121 vlc_dialog_wait_login_va(vlc_object_t *p_obj, char **ppsz_username,
122                          char **ppsz_password, bool *p_store,
123                          const char *psz_default_username,
124                          const char *psz_title, const char *psz_fmt, va_list ap);
125
126 /**
127  * Asks a total (Yes/No/Cancel) question
128  *
129  * This function waits until the user dismisses the dialog or responds. It's
130  * interruptible via vlc_interrupt. In that case, vlc_dialog_cbs.pf_cancel()
131  * will be invoked. The psz_cancel is mandatory since this dialog is always
132  * cancellable by the user.
133  *
134  * @param p_obj the VLC object emitting the dialog
135  * @param i_type question type (severity of the question)
136  * @param psz_cancel text of the cancel button
137  * @param psz_action1 first choice/button text (optional)
138  * @param psz_action2 second choice/button text (optional)
139  * @param psz_title title of the question dialog
140  * @param psz_fmt format string for the question message
141  * @return < 0 on error, 0 if the user cancelled it, 1 on action1, 2 on action2
142  */
143 VLC_API int
144 vlc_dialog_wait_question(vlc_object_t *p_obj,
145                          vlc_dialog_question_type i_type,
146                          const char *psz_cancel, const char *psz_action1,
147                          const char *psz_action2, const char *psz_title,
148                          const char *psz_fmt, ...) VLC_FORMAT(7,8);
149 #define vlc_dialog_wait_question(a, b, c, d, e, f, g, ...) \
150     vlc_dialog_wait_question(VLC_OBJECT(a), b, c, d, e, f, g, ##__VA_ARGS__)
151
152 /**
153  * Asks a total (Yes/No/Cancel) question
154  *
155  * Equivalent to vlc_dialog_wait_question() expect that it's called with a
156  * va_list.
157  */
158 VLC_API int
159 vlc_dialog_wait_question_va(vlc_object_t *p_obj,
160                             vlc_dialog_question_type i_type,
161                             const char *psz_cancel, const char *psz_action1,
162                             const char *psz_action2, const char *psz_title,
163                             const char *psz_fmt, va_list ap);
164
165 /**
166  * Display a progress dialog
167  *
168  * This function returns immediately
169  *
170  * @param p_obj the VLC object emitting the dialog
171  * @param b_indeterminate true if the progress dialog is indeterminate
172  * @param f_position initial position of the progress bar (between 0.0 and 1.0)
173  * @param psz_cancel text of the cancel button, if NULL the dialog is not
174  * cancellable (optional)
175  * @param psz_title title of the progress dialog
176  * @param psz_fmt format string for the progress message
177  * @return a valid vlc_dialog_id on success, must be released with
178  * vlc_dialog_id_release()
179  */
180 VLC_API vlc_dialog_id *
181 vlc_dialog_display_progress(vlc_object_t *p_obj, bool b_indeterminate,
182                             float f_position, const char *psz_cancel,
183                             const char *psz_title, const char *psz_fmt, ...)
184                             VLC_FORMAT(6,7);
185 #define vlc_dialog_display_progress(a, b, c, d, e, f, ...) \
186     vlc_dialog_display_progress(VLC_OBJECT(a), b, c, d, e, f, ##__VA_ARGS__)
187
188 /**
189  * Display a progress dialog
190  *
191  * Equivalent to vlc_dialog_display_progress() expect that it's called with a
192  * va_list.
193  */
194 VLC_API vlc_dialog_id *
195 vlc_dialog_display_progress_va(vlc_object_t *p_obj, bool b_indeterminate,
196                                float f_position, const char *psz_cancel,
197                                const char *psz_title, const char *psz_fmt,
198                                va_list ap);
199
200 /**
201  * Update the position of the progress dialog
202  *
203  * @param p_obj the VLC object emitting the dialog
204  * @param p_id id of the dialog to update
205  * @param f_position position of the progress bar (between 0.0 and 1.0)
206  * @return VLC_SUCCESS on success, or a VLC error code on error
207  */
208 VLC_API int
209 vlc_dialog_update_progress(vlc_object_t *p_obj, vlc_dialog_id *p_id,
210                            float f_position);
211 #define vlc_dialog_update_progress(a, b, c) \
212     vlc_dialog_update_progress(VLC_OBJECT(a), b, c)
213
214 /**
215  * Update the position and the message of the progress dialog
216  *
217  * @param p_obj the VLC object emitting the dialog
218  * @param p_id id of the dialog to update
219  * @param f_position position of the progress bar (between 0.0 and 1.0)
220  * @param psz_fmt format string for the progress message
221  * @return VLC_SUCCESS on success, or a VLC error code on error
222  */
223 VLC_API int
224 vlc_dialog_update_progress_text(vlc_object_t *p_obj, vlc_dialog_id *p_id,
225                                 float f_position, const char *psz_fmt, ...)
226                                 VLC_FORMAT(4, 5);
227 #define vlc_dialog_update_progress_text(a, b, c, d, ...) \
228     vlc_dialog_update_progress_text(VLC_OBJECT(a), b, c, d, ##__VA_ARGS__)
229
230 /**
231  * Update the position and the message of the progress dialog
232  *
233  * Equivalent to vlc_dialog_update_progress_text() expect that it's called
234  * with a va_list.
235  */
236 VLC_API int
237 vlc_dialog_update_progress_text_va(vlc_object_t *p_obj, vlc_dialog_id *p_id,
238                                    float f_position, const char *psz_fmt,
239                                    va_list ap);
240
241 /**
242  * Release the dialog id returned by vlc_dialog_display_progress()
243  *
244  * It causes the vlc_dialog_cbs.pf_cancel() callback to be invoked.
245  *
246  * @param p_obj the VLC object emitting the dialog
247  * @param p_id id of the dialog to release
248  */
249 VLC_API void
250 vlc_dialog_release(vlc_object_t *p_obj, vlc_dialog_id *p_id);
251 #define vlc_dialog_release(a, b) \
252     vlc_dialog_release(VLC_OBJECT(a), b)
253
254 /**
255  * Return true if the dialog id is cancelled
256  *
257  * @param p_obj the VLC object emitting the dialog
258  * @param p_id id of the dialog
259  */
260 VLC_API bool
261 vlc_dialog_is_cancelled(vlc_object_t *p_obj, vlc_dialog_id *p_id);
262 #define vlc_dialog_is_cancelled(a, b) \
263     vlc_dialog_is_cancelled(VLC_OBJECT(a), b)
264
265 /**
266  * @}
267  * @defgroup vlc_dialog_impl VLC dialog callbacks
268  * Need to be implemented by GUI modules or libvlc
269  * @{
270  */
271
272 /**
273  * Dialog callbacks to be implemented
274  */
275 typedef struct vlc_dialog_cbs
276 {
277     /**
278      * Called when an error message needs to be displayed
279      *
280      * @param p_data opaque pointer for the callback
281      * @param psz_title title of the diaog
282      * @param psz_text text of the dialog
283      */
284     void (*pf_display_error)(void *p_data, const char *psz_title,
285                              const char *psz_text);
286
287     /**
288      * Called when a login dialog needs to be displayed
289      *
290      * You can interact with this dialog by calling vlc_dialog_id_post_login()
291      * to post an answer or vlc_dialog_id_dismiss() to cancel this dialog.
292      *
293      * @note to receive this callack, vlc_dialog_cbs.pf_cancel should not be
294      * NULL.
295      *
296      * @param p_data opaque pointer for the callback
297      * @param p_id id used to interact with the dialog
298      * @param psz_title title of the diaog
299      * @param psz_text text of the dialog
300      * @param psz_default_username user name that should be set on the user form
301      * @param b_ask_store if true, ask the user if he wants to save the
302      * credentials
303      */
304     void (*pf_display_login)(void *p_data, vlc_dialog_id *p_id,
305                              const char *psz_title, const char *psz_text,
306                              const char *psz_default_username,
307                              bool b_ask_store);
308
309     /**
310      * Called when a question dialog needs to be displayed
311      *
312      * You can interact with this dialog by calling vlc_dialog_id_post_action()
313      * to post an answer or vlc_dialog_id_dismiss() to cancel this dialog.
314      *
315      * @note to receive this callack, vlc_dialog_cbs.pf_cancel should not be
316      * NULL.
317      *
318      * @param p_data opaque pointer for the callback
319      * @param p_id id used to interact with the dialog
320      * @param psz_title title of the diaog
321      * @param psz_text text of the dialog
322      * @param i_type question type (or severity) of the dialog
323      * @param psz_cancel text of the cancel button
324      * @param psz_action1 text of the first button, if NULL, don't display this
325      * button
326      * @param psz_action2 text of the second button, if NULL, don't display
327      * this button
328      */
329     void (*pf_display_question)(void *p_data, vlc_dialog_id *p_id,
330                                 const char *psz_title, const char *psz_text,
331                                 vlc_dialog_question_type i_type,
332                                 const char *psz_cancel, const char *psz_action1,
333                                 const char *psz_action2);
334
335     /**
336      * Called when a progress dialog needs to be displayed
337      *
338      * If cancellable (psz_cancel != NULL), you can cancel this dialog by
339      * calling vlc_dialog_id_dismiss()
340      *
341      * @note to receive this callack, vlc_dialog_cbs.pf_cancel and
342      * vlc_dialog_cbs.pf_update_progress should not be NULL.
343      *
344      * @param p_data opaque pointer for the callback
345      * @param p_id id used to interact with the dialog
346      * @param psz_title title of the diaog
347      * @param psz_text text of the dialog
348      * @param b_indeterminate true if the progress dialog is indeterminate
349      * @param f_position initial position of the progress bar (between 0.0 and
350      * 1.0)
351      * @param psz_cancel text of the cancel button, if NULL the dialog is not
352      * cancellable
353      */
354     void (*pf_display_progress)(void *p_data, vlc_dialog_id *p_id,
355                                 const char *psz_title, const char *psz_text,
356                                 bool b_indeterminate, float f_position,
357                                 const char *psz_cancel);
358
359     /**
360      * Called when a displayed dialog needs to be cancelled
361      *
362      * The implementation must call vlc_dialog_id_dismiss() to really release
363      * the dialog.
364      *
365      * @param p_data opaque pointer for the callback
366      * @param p_id id of the dialog
367      */
368     void (*pf_cancel)(void *p_data, vlc_dialog_id *p_id);
369
370     /**
371      * Called when a progress dialog needs to be updated
372      *
373      * @param p_data opaque pointer for the callback
374      * @param p_id id of the dialog
375      * @param f_position osition of the progress bar (between 0.0 and 1.0)
376      * @param psz_text new text of the progress dialog
377      */
378     void (*pf_update_progress)(void *p_data, vlc_dialog_id *p_id,
379                                float f_position, const char *psz_text);
380 } vlc_dialog_cbs;
381
382 /**
383  * Register callbacks to handle VLC dialogs
384  *
385  * @param p_cbs a pointer to callbacks, or NULL to unregister callbacks.
386  * @param p_data opaque pointer for the callback
387  */
388 VLC_API void
389 vlc_dialog_provider_set_callbacks(vlc_object_t *p_obj,
390                                   const vlc_dialog_cbs *p_cbs, void *p_data);
391 #define vlc_dialog_provider_set_callbacks(a, b, c) \
392     vlc_dialog_provider_set_callbacks(VLC_OBJECT(a), b, c)
393
394 /**
395  * Associate an opaque pointer with the dialog id
396  */
397 VLC_API void
398 vlc_dialog_id_set_context(vlc_dialog_id *p_id, void *p_context);
399
400 /**
401  * Return the opaque pointer associated with the dialog id
402  */
403 VLC_API void *
404 vlc_dialog_id_get_context(vlc_dialog_id *p_id);
405
406 /**
407  * Post a login answer
408  *
409  * After this call, p_id won't be valid anymore
410  *
411  * @see vlc_dialog_cbs.pf_display_login
412  *
413  * @param p_id id of the dialog
414  * @param psz_username valid and non empty string
415  * @param psz_password valid string (can be empty)
416  * @param b_store if true, store the credentials
417  * @return VLC_SUCCESS on success, or a VLC error code on error
418  */
419 VLC_API int
420 vlc_dialog_id_post_login(vlc_dialog_id *p_id, const char *psz_username,
421                          const char *psz_password, bool b_store);
422
423 /**
424  * Post a question answer
425  *
426  * After this call, p_id won't be valid anymore
427  *
428  * @see vlc_dialog_cbs.pf_display_question
429  *
430  * @param p_id id of the dialog
431  * @param i_action 1 for action1, 2 for action2
432  * @return VLC_SUCCESS on success, or a VLC error code on error
433  */
434 VLC_API int
435 vlc_dialog_id_post_action(vlc_dialog_id *p_id, int i_action);
436
437 /**
438  * Dismiss a dialog
439  *
440  * After this call, p_id won't be valid anymore
441  *
442  * @see vlc_dialog_cbs.pf_cancel
443  *
444  * @param p_id id of the dialog
445  * @return VLC_SUCCESS on success, or a VLC error code on error
446  */
447 VLC_API int
448 vlc_dialog_id_dismiss(vlc_dialog_id *p_id);
449
450 /**
451  * @}
452  * @defgroup vlc_dialog_ext VLC extension dialog functions
453  * @{
454  */
455
456 VLC_API int
457 vlc_ext_dialog_update(vlc_object_t *p_obj, extension_dialog_t *dialog);
458 #define vlc_ext_dialog_update(a, b) \
459     vlc_ext_dialog_update(VLC_OBJECT(a), b)
460
461 /**
462  * Dialog extension callback to be implemented
463  */
464 typedef void (*vlc_dialog_ext_update_cb)(extension_dialog_t *p_ext_dialog,
465                                          void *p_data);
466
467 /**
468  * Register a callback for VLC extension dialog
469  *
470  * @param pf_update a pointer to the update callback, or NULL to unregister
471  * callback
472  * @param p_data opaque pointer for the callback
473  */
474 VLC_API void
475 vlc_dialog_provider_set_ext_callback(vlc_object_t *p_obj,
476                                      vlc_dialog_ext_update_cb pf_update,
477                                      void *p_data);
478 #define vlc_dialog_provider_set_ext_callback(a, b, c) \
479     vlc_dialog_provider_set_ext_callback(VLC_OBJECT(a), b, c)
480
481 /** @} @} */
482
483 #endif