1 /*****************************************************************************
2 * libvlc_dialog.h: libvlc dialog API
3 *****************************************************************************
4 * Copyright © 2016 VLC authors and VideoLAN
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU Lesser General Public License as published by
8 * the Free Software Foundation; either version 2.1 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public License
17 * along with this program; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
19 *****************************************************************************/
21 #ifndef LIBVLC_DIALOG_H
22 #define LIBVLC_DIALOG_H 1
30 typedef struct libvlc_dialog_id libvlc_dialog_id
;
33 * @defgroup libvlc_dialog LibVLC dialog
37 * LibVLC dialog external API
40 typedef enum libvlc_dialog_question_type
42 LIBVLC_DIALOG_QUESTION_NORMAL
,
43 LIBVLC_DIALOG_QUESTION_WARNING
,
44 LIBVLC_DIALOG_QUESTION_CRITICAL
,
45 } libvlc_dialog_question_type
;
48 * Dialog callbacks to be implemented
50 typedef struct libvlc_dialog_cbs
53 * Called when an error message needs to be displayed
55 * @param p_data opaque pointer for the callback
56 * @param psz_title title of the dialog
57 * @param psz_text text of the dialog
59 void (*pf_display_error
)(void *p_data
, const char *psz_title
,
60 const char *psz_text
);
63 * Called when a login dialog needs to be displayed
65 * You can interact with this dialog by calling libvlc_dialog_post_login()
66 * to post an answer or libvlc_dialog_dismiss() to cancel this dialog.
68 * @note to receive this callback, libvlc_dialog_cbs.pf_cancel should not be
71 * @param p_data opaque pointer for the callback
72 * @param p_id id used to interact with the dialog
73 * @param psz_title title of the dialog
74 * @param psz_text text of the dialog
75 * @param psz_default_username user name that should be set on the user form
76 * @param b_ask_store if true, ask the user if he wants to save the
79 void (*pf_display_login
)(void *p_data
, libvlc_dialog_id
*p_id
,
80 const char *psz_title
, const char *psz_text
,
81 const char *psz_default_username
,
85 * Called when a question dialog needs to be displayed
87 * You can interact with this dialog by calling libvlc_dialog_post_action()
88 * to post an answer or libvlc_dialog_dismiss() to cancel this dialog.
90 * @note to receive this callback, libvlc_dialog_cbs.pf_cancel should not be
93 * @param p_data opaque pointer for the callback
94 * @param p_id id used to interact with the dialog
95 * @param psz_title title of the dialog
96 * @param psz_text text of the dialog
97 * @param i_type question type (or severity) of the dialog
98 * @param psz_cancel text of the cancel button
99 * @param psz_action1 text of the first button, if NULL, don't display this
101 * @param psz_action2 text of the second button, if NULL, don't display
104 void (*pf_display_question
)(void *p_data
, libvlc_dialog_id
*p_id
,
105 const char *psz_title
, const char *psz_text
,
106 libvlc_dialog_question_type i_type
,
107 const char *psz_cancel
, const char *psz_action1
,
108 const char *psz_action2
);
111 * Called when a progress dialog needs to be displayed
113 * If cancellable (psz_cancel != NULL), you can cancel this dialog by
114 * calling libvlc_dialog_dismiss()
116 * @note to receive this callback, libvlc_dialog_cbs.pf_cancel and
117 * libvlc_dialog_cbs.pf_update_progress should not be NULL.
119 * @param p_data opaque pointer for the callback
120 * @param p_id id used to interact with the dialog
121 * @param psz_title title of the dialog
122 * @param psz_text text of the dialog
123 * @param b_indeterminate true if the progress dialog is indeterminate
124 * @param f_position initial position of the progress bar (between 0.0 and
126 * @param psz_cancel text of the cancel button, if NULL the dialog is not
129 void (*pf_display_progress
)(void *p_data
, libvlc_dialog_id
*p_id
,
130 const char *psz_title
, const char *psz_text
,
131 bool b_indeterminate
, float f_position
,
132 const char *psz_cancel
);
135 * Called when a displayed dialog needs to be cancelled
137 * The implementation must call libvlc_dialog_dismiss() to really release
140 * @param p_data opaque pointer for the callback
141 * @param p_id id of the dialog
143 void (*pf_cancel
)(void *p_data
, libvlc_dialog_id
*p_id
);
146 * Called when a progress dialog needs to be updated
148 * @param p_data opaque pointer for the callback
149 * @param p_id id of the dialog
150 * @param f_position osition of the progress bar (between 0.0 and 1.0)
151 * @param psz_text new text of the progress dialog
153 void (*pf_update_progress
)(void *p_data
, libvlc_dialog_id
*p_id
,
154 float f_position
, const char *psz_text
);
158 * Register callbacks in order to handle VLC dialogs
160 * @version LibVLC 3.0.0 and later.
162 * @param p_cbs a pointer to callbacks, or NULL to unregister callbacks.
163 * @param p_data opaque pointer for the callback
166 libvlc_dialog_set_callbacks(libvlc_instance_t
*p_instance
,
167 const libvlc_dialog_cbs
*p_cbs
, void *p_data
);
170 * Associate an opaque pointer with the dialog id
172 * @version LibVLC 3.0.0 and later.
175 libvlc_dialog_set_context(libvlc_dialog_id
*p_id
, void *p_context
);
178 * Return the opaque pointer associated with the dialog id
180 * @version LibVLC 3.0.0 and later.
183 libvlc_dialog_get_context(libvlc_dialog_id
*p_id
);
186 * Post a login answer
188 * After this call, p_id won't be valid anymore
190 * @see libvlc_dialog_cbs.pf_display_login
192 * @version LibVLC 3.0.0 and later.
194 * @param p_id id of the dialog
195 * @param psz_username valid and non empty string
196 * @param psz_password valid string (can be empty)
197 * @param b_store if true, store the credentials
198 * @return 0 on success, or -1 on error
201 libvlc_dialog_post_login(libvlc_dialog_id
*p_id
, const char *psz_username
,
202 const char *psz_password
, bool b_store
);
205 * Post a question answer
207 * After this call, p_id won't be valid anymore
209 * @see libvlc_dialog_cbs.pf_display_question
211 * @version LibVLC 3.0.0 and later.
213 * @param p_id id of the dialog
214 * @param i_action 1 for action1, 2 for action2
215 * @return 0 on success, or -1 on error
218 libvlc_dialog_post_action(libvlc_dialog_id
*p_id
, int i_action
);
223 * After this call, p_id won't be valid anymore
225 * @see libvlc_dialog_cbs.pf_cancel
227 * @version LibVLC 3.0.0 and later.
229 * @param p_id id of the dialog
230 * @return 0 on success, or -1 on error
233 libvlc_dialog_dismiss(libvlc_dialog_id
*p_id
);
241 #endif /* LIBVLC_DIALOG_H */