484 lines
17 KiB
C
484 lines
17 KiB
C
/*****************************************************************************
|
|
* vlc_dialog.h: user interaction dialogs
|
|
*****************************************************************************
|
|
* Copyright (C) 2009 Rémi Denis-Courmont
|
|
* Copyright (C) 2016 VLC authors and VideoLAN
|
|
*
|
|
* 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
|
|
* (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
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU Lesser General Public License for more details.
|
|
*
|
|
* 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.
|
|
*****************************************************************************/
|
|
|
|
#ifndef VLC_DIALOG_H_
|
|
#define VLC_DIALOG_H_
|
|
# include <stdarg.h>
|
|
|
|
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 */
|
|
int
|
|
libvlc_InternalDialogInit(libvlc_int_t *p_libvlc);
|
|
|
|
/* Called from src/libvlc.c */
|
|
void
|
|
libvlc_InternalDialogClean(libvlc_int_t *p_libvlc);
|
|
|
|
/**
|
|
* @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);
|
|
#define vlc_dialog_update_progress_text(a, b, c, d, ...) \
|
|
vlc_dialog_update_progress_text(VLC_OBJECT(a), b, c, d, ##__VA_ARGS__)
|
|
|
|
/**
|
|
* 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
|
|
*
|
|
* @param p_data opaque pointer for the callback
|
|
* @param psz_title title of the dialog
|
|
* @param psz_text text of the dialog
|
|
*/
|
|
void (*pf_display_error)(void *p_data, const char *psz_title,
|
|
const char *psz_text);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @note to receive this callback, vlc_dialog_cbs.pf_cancel should not be
|
|
* NULL.
|
|
*
|
|
* @param p_data opaque pointer for the callback
|
|
* @param p_id id used to interact with the dialog
|
|
* @param psz_title title of the dialog
|
|
* @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
|
|
*/
|
|
void (*pf_display_login)(void *p_data, vlc_dialog_id *p_id,
|
|
const char *psz_title, const char *psz_text,
|
|
const char *psz_default_username,
|
|
bool b_ask_store);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @note to receive this callback, vlc_dialog_cbs.pf_cancel should not be
|
|
* NULL.
|
|
*
|
|
* @param p_data opaque pointer for the callback
|
|
* @param p_id id used to interact with the dialog
|
|
* @param psz_title title of the dialog
|
|
* @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
|
|
*/
|
|
void (*pf_display_question)(void *p_data, vlc_dialog_id *p_id,
|
|
const char *psz_title, const char *psz_text,
|
|
vlc_dialog_question_type i_type,
|
|
const char *psz_cancel, const char *psz_action1,
|
|
const char *psz_action2);
|
|
|
|
/**
|
|
* 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()
|
|
*
|
|
* @note to receive this callback, vlc_dialog_cbs.pf_cancel and
|
|
* vlc_dialog_cbs.pf_update_progress should not be NULL.
|
|
*
|
|
* @param p_data opaque pointer for the callback
|
|
* @param p_id id used to interact with the dialog
|
|
* @param psz_title title of the dialog
|
|
* @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
|
|
*/
|
|
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);
|
|
|
|
/**
|
|
* 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
|
|
* @param p_id id of the dialog
|
|
*/
|
|
void (*pf_cancel)(void *p_data, vlc_dialog_id *p_id);
|
|
|
|
/**
|
|
* Called when a progress dialog needs to be updated
|
|
*
|
|
* @param p_data opaque pointer for the callback
|
|
* @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
|
|
*/
|
|
void (*pf_update_progress)(void *p_data, vlc_dialog_id *p_id,
|
|
float f_position, const char *psz_text);
|
|
} 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)
|
|
|
|
/** @} @} */
|
|
|
|
#endif
|