vlc_dialog.h 17 KB
Newer Older
1 2 3 4
/*****************************************************************************
 * vlc_dialog.h: user interaction dialogs
 *****************************************************************************
 * Copyright (C) 2009 Rémi Denis-Courmont
Thomas Guillem's avatar
Thomas Guillem committed
5
 * Copyright (C) 2016 VLC authors and VideoLAN
6
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
7 8 9
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
10 11 12 13
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
14 15
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
16
 *
Jean-Baptiste Kempf's avatar
LGPL  
Jean-Baptiste Kempf committed
17 18 19
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
20 21 22 23
 *****************************************************************************/

#ifndef VLC_DIALOG_H_
#define VLC_DIALOG_H_
24
# include <stdarg.h>
25

Thomas Guillem's avatar
Thomas Guillem committed
26 27 28 29 30
typedef struct vlc_dialog_provider vlc_dialog_provider;
typedef struct vlc_dialog_id vlc_dialog_id;
typedef struct extension_dialog_t extension_dialog_t;

/* Called from src/libvlc.c */
31 32
int
libvlc_InternalDialogInit(libvlc_int_t *p_libvlc);
Thomas Guillem's avatar
Thomas Guillem committed
33 34 35

/* Called from src/libvlc.c */
void
36
libvlc_InternalDialogClean(libvlc_int_t *p_libvlc);
Thomas Guillem's avatar
Thomas Guillem committed
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

/**
 * @defgroup vlc_dialog VLC dialog
 * @ingroup interface
 * @{
 * @file
 * This file declares VLC dialog functions
 * @defgroup vlc_dialog_api VLC dialog functions
 * In order to interact with the user
 * @{
 */

/**
 * Dialog question type, see vlc_dialog_wait_question()
 */
typedef enum vlc_dialog_question_type
{
    VLC_DIALOG_QUESTION_NORMAL,
    VLC_DIALOG_QUESTION_WARNING,
    VLC_DIALOG_QUESTION_CRITICAL,
} vlc_dialog_question_type;

/**
 * Sends an error message
 *
 * This function returns immediately
 *
 * @param p_obj the VLC object emitting the error
 * @param psz_title title of the error dialog
 * @param psz_fmt format string for the error message
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_display_error(vlc_object_t *p_obj, const char *psz_title,
                         const char *psz_fmt, ...) VLC_FORMAT(3,4);
#define vlc_dialog_display_error(a, b, c, ...) \
    vlc_dialog_display_error(VLC_OBJECT(a), b, c, ##__VA_ARGS__)

/**
 * Sends an error message
 *
 * Equivalent to vlc_dialog_display_error() expect that it's called with a
 * va_list.
 */
VLC_API int
vlc_dialog_display_error_va(vlc_object_t *p_obj, const char *psz_title,
                            const char *psz_fmt, va_list ap);

/**
 * Requests an user name and a password
 *
 * This function waits until the user dismisses the dialog or responds. It's
 * interruptible via vlc_interrupt. In that case, vlc_dialog_cbs.pf_cancel()
 * will be invoked. If p_store is not NULL, the user will be asked to store the
 * password or not.
 *
 * @param p_obj the VLC object emitting the dialog
 * @param ppsz_username a pointer to the user name provided by the user, it
 * must be freed with free() on success
 * @param ppsz_password a pointer to the password provided by the user, it must
 * be freed with free() on success
 * @param p_store a pointer to the store answer provided by the user (optional)
 * @param psz_default_username default user name proposed
 * @param psz_title title of the login dialog
 * @param psz_fmt format string for the login message
 * @return < 0 on error, 0 if the user cancelled it, and 1 if ppsz_username and
 * ppsz_password are valid.
 */
VLC_API int
vlc_dialog_wait_login(vlc_object_t *p_obj, char **ppsz_username,
                      char **ppsz_password, bool *p_store,
                      const char *psz_default_username,
                      const char *psz_title, const char *psz_fmt, ...)
                      VLC_FORMAT(7,8);
#define vlc_dialog_wait_login(a, b, c, d, e, f, g, ...) \
    vlc_dialog_wait_login(VLC_OBJECT(a), b, c, d, e, f, g, ##__VA_ARGS__)

/**
 * Requests an user name and a password
 *
 * Equivalent to vlc_dialog_wait_login() expect that it's called with a
 * va_list.
 */
VLC_API int
vlc_dialog_wait_login_va(vlc_object_t *p_obj, char **ppsz_username,
                         char **ppsz_password, bool *p_store,
                         const char *psz_default_username,
                         const char *psz_title, const char *psz_fmt, va_list ap);

/**
 * Asks a total (Yes/No/Cancel) question
 *
 * This function waits until the user dismisses the dialog or responds. It's
 * interruptible via vlc_interrupt. In that case, vlc_dialog_cbs.pf_cancel()
 * will be invoked. The psz_cancel is mandatory since this dialog is always
 * cancellable by the user.
 *
 * @param p_obj the VLC object emitting the dialog
 * @param i_type question type (severity of the question)
 * @param psz_cancel text of the cancel button
 * @param psz_action1 first choice/button text (optional)
 * @param psz_action2 second choice/button text (optional)
 * @param psz_title title of the question dialog
 * @param psz_fmt format string for the question message
 * @return < 0 on error, 0 if the user cancelled it, 1 on action1, 2 on action2
 */
VLC_API int
vlc_dialog_wait_question(vlc_object_t *p_obj,
                         vlc_dialog_question_type i_type,
                         const char *psz_cancel, const char *psz_action1,
                         const char *psz_action2, const char *psz_title,
                         const char *psz_fmt, ...) VLC_FORMAT(7,8);
#define vlc_dialog_wait_question(a, b, c, d, e, f, g, ...) \
    vlc_dialog_wait_question(VLC_OBJECT(a), b, c, d, e, f, g, ##__VA_ARGS__)

/**
 * Asks a total (Yes/No/Cancel) question
 *
 * Equivalent to vlc_dialog_wait_question() expect that it's called with a
 * va_list.
 */
VLC_API int
vlc_dialog_wait_question_va(vlc_object_t *p_obj,
                            vlc_dialog_question_type i_type,
                            const char *psz_cancel, const char *psz_action1,
                            const char *psz_action2, const char *psz_title,
                            const char *psz_fmt, va_list ap);

/**
 * Display a progress dialog
 *
 * This function returns immediately
 *
 * @param p_obj the VLC object emitting the dialog
 * @param b_indeterminate true if the progress dialog is indeterminate
 * @param f_position initial position of the progress bar (between 0.0 and 1.0)
 * @param psz_cancel text of the cancel button, if NULL the dialog is not
 * cancellable (optional)
 * @param psz_title title of the progress dialog
 * @param psz_fmt format string for the progress message
 * @return a valid vlc_dialog_id on success, must be released with
 * vlc_dialog_id_release()
 */
VLC_API vlc_dialog_id *
vlc_dialog_display_progress(vlc_object_t *p_obj, bool b_indeterminate,
                            float f_position, const char *psz_cancel,
                            const char *psz_title, const char *psz_fmt, ...)
                            VLC_FORMAT(6,7);
#define vlc_dialog_display_progress(a, b, c, d, e, f, ...) \
    vlc_dialog_display_progress(VLC_OBJECT(a), b, c, d, e, f, ##__VA_ARGS__)

/**
 * Display a progress dialog
 *
 * Equivalent to vlc_dialog_display_progress() expect that it's called with a
 * va_list.
 */
VLC_API vlc_dialog_id *
vlc_dialog_display_progress_va(vlc_object_t *p_obj, bool b_indeterminate,
                               float f_position, const char *psz_cancel,
                               const char *psz_title, const char *psz_fmt,
                               va_list ap);

/**
 * Update the position of the progress dialog
 *
 * @param p_obj the VLC object emitting the dialog
 * @param p_id id of the dialog to update
 * @param f_position position of the progress bar (between 0.0 and 1.0)
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_update_progress(vlc_object_t *p_obj, vlc_dialog_id *p_id,
                           float f_position);
#define vlc_dialog_update_progress(a, b, c) \
    vlc_dialog_update_progress(VLC_OBJECT(a), b, c)

/**
 * Update the position and the message of the progress dialog
 *
 * @param p_obj the VLC object emitting the dialog
 * @param p_id id of the dialog to update
 * @param f_position position of the progress bar (between 0.0 and 1.0)
 * @param psz_fmt format string for the progress message
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_update_progress_text(vlc_object_t *p_obj, vlc_dialog_id *p_id,
                                float f_position, const char *psz_fmt, ...)
                                VLC_FORMAT(4, 5);
Thomas Guillem's avatar
Thomas Guillem committed
227 228
#define vlc_dialog_update_progress_text(a, b, c, d, ...) \
    vlc_dialog_update_progress_text(VLC_OBJECT(a), b, c, d, ##__VA_ARGS__)
Thomas Guillem's avatar
Thomas Guillem committed
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 276 277 278 279

/**
 * Update the position and the message of the progress dialog
 *
 * Equivalent to vlc_dialog_update_progress_text() expect that it's called
 * with a va_list.
 */
VLC_API int
vlc_dialog_update_progress_text_va(vlc_object_t *p_obj, vlc_dialog_id *p_id,
                                   float f_position, const char *psz_fmt,
                                   va_list ap);

/**
 * Release the dialog id returned by vlc_dialog_display_progress()
 *
 * It causes the vlc_dialog_cbs.pf_cancel() callback to be invoked.
 *
 * @param p_obj the VLC object emitting the dialog
 * @param p_id id of the dialog to release
 */
VLC_API void
vlc_dialog_release(vlc_object_t *p_obj, vlc_dialog_id *p_id);
#define vlc_dialog_release(a, b) \
    vlc_dialog_release(VLC_OBJECT(a), b)

/**
 * Return true if the dialog id is cancelled
 *
 * @param p_obj the VLC object emitting the dialog
 * @param p_id id of the dialog
 */
VLC_API bool
vlc_dialog_is_cancelled(vlc_object_t *p_obj, vlc_dialog_id *p_id);
#define vlc_dialog_is_cancelled(a, b) \
    vlc_dialog_is_cancelled(VLC_OBJECT(a), b)

/**
 * @}
 * @defgroup vlc_dialog_impl VLC dialog callbacks
 * Need to be implemented by GUI modules or libvlc
 * @{
 */

/**
 * Dialog callbacks to be implemented
 */
typedef struct vlc_dialog_cbs
{
    /**
     * Called when an error message needs to be displayed
     *
280
     * @param p_data opaque pointer for the callback
Thomas Guillem's avatar
Thomas Guillem committed
281
     * @param psz_title title of the dialog
Thomas Guillem's avatar
Thomas Guillem committed
282 283
     * @param psz_text text of the dialog
     */
284 285
    void (*pf_display_error)(void *p_data, const char *psz_title,
                             const char *psz_text);
Thomas Guillem's avatar
Thomas Guillem committed
286 287 288 289 290 291 292

    /**
     * Called when a login dialog needs to be displayed
     *
     * You can interact with this dialog by calling vlc_dialog_id_post_login()
     * to post an answer or vlc_dialog_id_dismiss() to cancel this dialog.
     *
Thomas Guillem's avatar
Thomas Guillem committed
293
     * @note to receive this callback, vlc_dialog_cbs.pf_cancel should not be
Thomas Guillem's avatar
Thomas Guillem committed
294 295
     * NULL.
     *
296
     * @param p_data opaque pointer for the callback
Thomas Guillem's avatar
Thomas Guillem committed
297
     * @param p_id id used to interact with the dialog
Thomas Guillem's avatar
Thomas Guillem committed
298
     * @param psz_title title of the dialog
Thomas Guillem's avatar
Thomas Guillem committed
299 300 301 302 303
     * @param psz_text text of the dialog
     * @param psz_default_username user name that should be set on the user form
     * @param b_ask_store if true, ask the user if he wants to save the
     * credentials
     */
304 305
    void (*pf_display_login)(void *p_data, vlc_dialog_id *p_id,
                             const char *psz_title, const char *psz_text,
Thomas Guillem's avatar
Thomas Guillem committed
306
                             const char *psz_default_username,
307
                             bool b_ask_store);
Thomas Guillem's avatar
Thomas Guillem committed
308 309 310 311 312 313 314

    /**
     * Called when a question dialog needs to be displayed
     *
     * You can interact with this dialog by calling vlc_dialog_id_post_action()
     * to post an answer or vlc_dialog_id_dismiss() to cancel this dialog.
     *
Thomas Guillem's avatar
Thomas Guillem committed
315
     * @note to receive this callback, vlc_dialog_cbs.pf_cancel should not be
Thomas Guillem's avatar
Thomas Guillem committed
316 317
     * NULL.
     *
318
     * @param p_data opaque pointer for the callback
Thomas Guillem's avatar
Thomas Guillem committed
319
     * @param p_id id used to interact with the dialog
Thomas Guillem's avatar
Thomas Guillem committed
320
     * @param psz_title title of the dialog
Thomas Guillem's avatar
Thomas Guillem committed
321 322 323 324 325 326 327 328
     * @param psz_text text of the dialog
     * @param i_type question type (or severity) of the dialog
     * @param psz_cancel text of the cancel button
     * @param psz_action1 text of the first button, if NULL, don't display this
     * button
     * @param psz_action2 text of the second button, if NULL, don't display
     * this button
     */
329 330
    void (*pf_display_question)(void *p_data, vlc_dialog_id *p_id,
                                const char *psz_title, const char *psz_text,
Thomas Guillem's avatar
Thomas Guillem committed
331 332
                                vlc_dialog_question_type i_type,
                                const char *psz_cancel, const char *psz_action1,
333
                                const char *psz_action2);
Thomas Guillem's avatar
Thomas Guillem committed
334 335 336 337 338 339 340

    /**
     * Called when a progress dialog needs to be displayed
     *
     * If cancellable (psz_cancel != NULL), you can cancel this dialog by
     * calling vlc_dialog_id_dismiss()
     *
Thomas Guillem's avatar
Thomas Guillem committed
341
     * @note to receive this callback, vlc_dialog_cbs.pf_cancel and
Thomas Guillem's avatar
Thomas Guillem committed
342 343
     * vlc_dialog_cbs.pf_update_progress should not be NULL.
     *
344
     * @param p_data opaque pointer for the callback
Thomas Guillem's avatar
Thomas Guillem committed
345
     * @param p_id id used to interact with the dialog
Thomas Guillem's avatar
Thomas Guillem committed
346
     * @param psz_title title of the dialog
Thomas Guillem's avatar
Thomas Guillem committed
347 348 349 350 351 352 353
     * @param psz_text text of the dialog
     * @param b_indeterminate true if the progress dialog is indeterminate
     * @param f_position initial position of the progress bar (between 0.0 and
     * 1.0)
     * @param psz_cancel text of the cancel button, if NULL the dialog is not
     * cancellable
     */
354 355 356 357
    void (*pf_display_progress)(void *p_data, vlc_dialog_id *p_id,
                                const char *psz_title, const char *psz_text,
                                bool b_indeterminate, float f_position,
                                const char *psz_cancel);
Thomas Guillem's avatar
Thomas Guillem committed
358 359 360 361 362 363 364 365

    /**
     * Called when a displayed dialog needs to be cancelled
     *
     * The implementation must call vlc_dialog_id_dismiss() to really release
     * the dialog.
     *
     * @param p_data opaque pointer for the callback
366
     * @param p_id id of the dialog
Thomas Guillem's avatar
Thomas Guillem committed
367
     */
368
    void (*pf_cancel)(void *p_data, vlc_dialog_id *p_id);
Thomas Guillem's avatar
Thomas Guillem committed
369 370 371 372

    /**
     * Called when a progress dialog needs to be updated
     *
373
     * @param p_data opaque pointer for the callback
Thomas Guillem's avatar
Thomas Guillem committed
374 375 376 377
     * @param p_id id of the dialog
     * @param f_position osition of the progress bar (between 0.0 and 1.0)
     * @param psz_text new text of the progress dialog
     */
378 379
    void (*pf_update_progress)(void *p_data, vlc_dialog_id *p_id,
                               float f_position, const char *psz_text);
Thomas Guillem's avatar
Thomas Guillem committed
380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482
} vlc_dialog_cbs;

/**
 * Register callbacks to handle VLC dialogs
 *
 * @param p_cbs a pointer to callbacks, or NULL to unregister callbacks.
 * @param p_data opaque pointer for the callback
 */
VLC_API void
vlc_dialog_provider_set_callbacks(vlc_object_t *p_obj,
                                  const vlc_dialog_cbs *p_cbs, void *p_data);
#define vlc_dialog_provider_set_callbacks(a, b, c) \
    vlc_dialog_provider_set_callbacks(VLC_OBJECT(a), b, c)

/**
 * Associate an opaque pointer with the dialog id
 */
VLC_API void
vlc_dialog_id_set_context(vlc_dialog_id *p_id, void *p_context);

/**
 * Return the opaque pointer associated with the dialog id
 */
VLC_API void *
vlc_dialog_id_get_context(vlc_dialog_id *p_id);

/**
 * Post a login answer
 *
 * After this call, p_id won't be valid anymore
 *
 * @see vlc_dialog_cbs.pf_display_login
 *
 * @param p_id id of the dialog
 * @param psz_username valid and non empty string
 * @param psz_password valid string (can be empty)
 * @param b_store if true, store the credentials
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_id_post_login(vlc_dialog_id *p_id, const char *psz_username,
                         const char *psz_password, bool b_store);

/**
 * Post a question answer
 *
 * After this call, p_id won't be valid anymore
 *
 * @see vlc_dialog_cbs.pf_display_question
 *
 * @param p_id id of the dialog
 * @param i_action 1 for action1, 2 for action2
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_id_post_action(vlc_dialog_id *p_id, int i_action);

/**
 * Dismiss a dialog
 *
 * After this call, p_id won't be valid anymore
 *
 * @see vlc_dialog_cbs.pf_cancel
 *
 * @param p_id id of the dialog
 * @return VLC_SUCCESS on success, or a VLC error code on error
 */
VLC_API int
vlc_dialog_id_dismiss(vlc_dialog_id *p_id);

/**
 * @}
 * @defgroup vlc_dialog_ext VLC extension dialog functions
 * @{
 */

VLC_API int
vlc_ext_dialog_update(vlc_object_t *p_obj, extension_dialog_t *dialog);
#define vlc_ext_dialog_update(a, b) \
    vlc_ext_dialog_update(VLC_OBJECT(a), b)

/**
 * Dialog extension callback to be implemented
 */
typedef void (*vlc_dialog_ext_update_cb)(extension_dialog_t *p_ext_dialog,
                                         void *p_data);

/**
 * Register a callback for VLC extension dialog
 *
 * @param pf_update a pointer to the update callback, or NULL to unregister
 * callback
 * @param p_data opaque pointer for the callback
 */
VLC_API void
vlc_dialog_provider_set_ext_callback(vlc_object_t *p_obj,
                                     vlc_dialog_ext_update_cb pf_update,
                                     void *p_data);
#define vlc_dialog_provider_set_ext_callback(a, b, c) \
    vlc_dialog_provider_set_ext_callback(VLC_OBJECT(a), b, c)

/** @} @} */

483
#endif