videolan
/
vlc
mirror of https://code.videolan.org/videolan/vlc
1
Fork 0
Code Releases Activity
vlc/include/vlc_dialog.h

501 lines
18 KiB
C
Raw Permalink Blame History

/*****************************************************************************
* 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 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;
/**
* 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
*/
typedef void (*vlc_dialog_error_cbs)(void *p_data, const char *psz_title, const char *psz_text);
/**
* Register callbacks to handle VLC dialogs
*
* @param p_obj the VLC object to get the dialog provider from
* @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)
/**
* Register callbacks to handle VLC error messages
*
* @version LibVLC 4.0.0 and later.
*
* @param p_obj the VLC object to get the dialog provider from
* @param p_cbs a pointer to the callback, or NULL to unregister the callback.
* @param p_data opaque pointer for the callback
*/
VLC_API void
vlc_dialog_provider_set_error_callback(vlc_object_t *p_obj,
vlc_dialog_error_cbs p_cbs, void *p_data);
#define vlc_dialog_provider_set_error_callback(a, b, c) \
vlc_dialog_provider_set_error_callback(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 p_obj a VLC object to get the libvlc instance from
* @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
View Git Blame Copy Permalink