summaryrefslogtreecommitdiffstats
path: root/xbmc/addons/kodi-addon-dev-kit/include/kodi/gui/DialogKeyboard.h
diff options
context:
space:
mode:
Diffstat (limited to 'xbmc/addons/kodi-addon-dev-kit/include/kodi/gui/DialogKeyboard.h')
-rw-r--r--xbmc/addons/kodi-addon-dev-kit/include/kodi/gui/DialogKeyboard.h416
1 files changed, 416 insertions, 0 deletions
diff --git a/xbmc/addons/kodi-addon-dev-kit/include/kodi/gui/DialogKeyboard.h b/xbmc/addons/kodi-addon-dev-kit/include/kodi/gui/DialogKeyboard.h
new file mode 100644
index 0000000..9261972
--- /dev/null
+++ b/xbmc/addons/kodi-addon-dev-kit/include/kodi/gui/DialogKeyboard.h
@@ -0,0 +1,416 @@
1#pragma once
2/*
3 * Copyright (C) 2005-2017 Team KODI
4 * http://kodi.tv
5 *
6 * This Program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2, or (at your option)
9 * any later version.
10 *
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 General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with KODI; see the file COPYING. If not, see
18 * <http://www.gnu.org/licenses/>.
19 *
20 */
21
22#include "definitions.h"
23#include "../AddonBase.h"
24
25namespace kodi
26{
27namespace gui
28{
29
30 //============================================================================
31 ///
32 /// \defgroup cpp_kodi_gui_DialogKeyboard Dialog Keyboard
33 /// \ingroup cpp_kodi_gui
34 /// @brief \cpp_namespace{ kodi::gui::DialogKeyboard }
35 /// **Keyboard dialogs**
36 ///
37 /// The functions listed below have to be permitted by the user for the
38 /// representation of a keyboard around an input.
39 ///
40 /// The class supports several kinds, from an easy text choice up to the
41 /// passport Word production and their confirmation for add-on.
42 ///
43 /// It has the header \ref DialogKeyboard.h "#include <kodi/gui/DialogKeyboard.h>"
44 /// be included to enjoy it.
45 ///
46 namespace DialogKeyboard
47 {
48 //==========================================================================
49 ///
50 /// \ingroup cpp_kodi_gui_DialogKeyboard
51 /// @brief Show keyboard with initial value `text` and replace with result
52 /// string.
53 ///
54 /// @param[in,out] text Overwritten with user input if return=true.
55 /// @param[in] heading String shown on dialog title.
56 /// @param[in] allowEmptyResult Whether a blank password is valid or not.
57 /// @param[in] hiddenInput The inserted input is not shown as text.
58 /// @param[in] autoCloseMs To close the dialog after a specified
59 /// time, in milliseconds, default is 0 which
60 /// keeps the dialog open indefinitely.
61 /// @return true if successful display and user input.
62 /// false if unsuccessful display, no user
63 /// input, or canceled editing.
64 ///
65 ///
66 ///-------------------------------------------------------------------------
67 ///
68 /// **Example:**
69 /// ~~~~~~~~~~~~~{.cpp}
70 /// #include <kodi/gui/DialogKeyboard.h>
71 ///
72 /// /*
73 /// * The example shows the display of keyboard call dialog at Kodi from the add-on.
74 /// * Below all values are set, however, can last two (hidden input = false and autoCloseMs = 0)
75 /// * to be released if not needed.
76 /// */
77 /// std::string text = "Please change me to them want you want"; /*< It can be leaved empty or a
78 /// entry text added */
79 /// bool bRet = ::kodi::gui::DialogKeyboard::ShowAndGetInput(text,
80 /// "Demonstration text entry",
81 /// true,
82 /// false,
83 /// 0);
84 /// fprintf(stderr, "Written keyboard input is : '%s' and was %s\n",
85 /// text.c_str(), bRet ? "OK" : "Canceled");
86 /// ~~~~~~~~~~~~~
87 ///
88 inline bool ShowAndGetInput(std::string& text, const std::string& heading, bool allowEmptyResult, bool hiddenInput = false, unsigned int autoCloseMs = 0)
89 {
90 using namespace ::kodi::addon;
91 char* retString = nullptr;
92 bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_get_input_with_head(CAddonBase::m_interface->toKodi->kodiBase,
93 text.c_str(), &retString, heading.c_str(), allowEmptyResult,
94 hiddenInput, autoCloseMs);
95 if (retString != nullptr)
96 {
97 if (std::strlen(retString))
98 text = retString;
99 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString);
100 }
101 return ret;
102 }
103 //--------------------------------------------------------------------------
104
105 //==========================================================================
106 ///
107 /// \ingroup cpp_kodi_gui_DialogKeyboard
108 /// @brief The example shows the display of keyboard call dialog at Kodi
109 /// from the add-on.
110 ///
111 /// @param[out] text Overwritten with user input if return=true.
112 /// @param[in] allowEmptyResult If set to true keyboard can also exited
113 /// without entered text.
114 /// @param[in] autoCloseMs To close the dialog after a specified time,
115 /// in milliseconds, default is 0 which keeps
116 /// the dialog open indefinitely.
117 /// @return true if successful display and user input.
118 /// false if unsuccessful display, no user
119 /// input, or canceled editing.
120 ///
121 inline bool ShowAndGetInput(std::string& text, bool allowEmptyResult, unsigned int autoCloseMs = 0)
122 {
123 using namespace ::kodi::addon;
124 char* retString = nullptr;
125 bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_get_input(CAddonBase::m_interface->toKodi->kodiBase,
126 text.c_str(), &retString,
127 allowEmptyResult, autoCloseMs);
128 if (retString != nullptr)
129 {
130 if (std::strlen(retString))
131 text = retString;
132 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString);
133 }
134 return ret;
135 }
136 //--------------------------------------------------------------------------
137
138 //==========================================================================
139 ///
140 /// \ingroup cpp_kodi_gui_DialogKeyboard
141 /// @brief Shows keyboard and prompts for a password. Differs from
142 /// `ShowAndVerifyNewPassword()` in that no second verification
143 ///
144 /// @param[in,out] newPassword Overwritten with user input if return=true.
145 /// @param[in] heading String shown on dialog title.
146 /// @param[in] allowEmptyResult Whether a blank password is valid or not.
147 /// @param[in] autoCloseMs To close the dialog after a specified time,
148 /// in milliseconds, default is 0 which keeps
149 /// the dialog open indefinitely.
150 /// @return true if successful display and user input.
151 /// false if unsuccessful display, no user
152 /// input, or canceled editing.
153 ///
154 inline bool ShowAndGetNewPassword(std::string& newPassword, const std::string& heading, bool allowEmptyResult, unsigned int autoCloseMs = 0)
155 {
156 using namespace ::kodi::addon;
157 char* retString = nullptr;
158 bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_get_new_password_with_head(CAddonBase::m_interface->toKodi->kodiBase,
159 newPassword.c_str(), &retString, heading.c_str(),
160 allowEmptyResult, autoCloseMs);
161 if (retString != nullptr)
162 {
163 if (std::strlen(retString))
164 newPassword = retString;
165 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString);
166 }
167 return ret;
168 }
169 //--------------------------------------------------------------------------
170
171 //==========================================================================
172 ///
173 /// \ingroup cpp_kodi_gui_DialogKeyboard
174 /// @brief Shows keyboard and prompts for a password. Differs from
175 /// `ShowAndVerifyNewPassword()` in that no second verification
176 ///
177 /// @param[in,out] newPassword Overwritten with user input if return=true.
178 /// @param[in] autoCloseMs To close the dialog after a specified time,
179 /// in milliseconds, default is 0 which keeps
180 /// the dialog open indefinitely.
181 /// @return true if successful display and user input.
182 /// false if unsuccessful display, no user
183 /// input, or canceled editing.
184 ///
185 inline bool ShowAndGetNewPassword(std::string& newPassword, unsigned int autoCloseMs = 0)
186 {
187 using namespace ::kodi::addon;
188 char* retString = nullptr;
189 bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_get_new_password(CAddonBase::m_interface->toKodi->kodiBase,
190 newPassword.c_str(), &retString, autoCloseMs);
191 if (retString != nullptr)
192 {
193 if (std::strlen(retString))
194 newPassword = retString;
195 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString);
196 }
197 return ret;
198 }
199 //--------------------------------------------------------------------------
200
201 //==========================================================================
202 ///
203 /// \ingroup cpp_kodi_gui_DialogKeyboard
204 /// @brief Show keyboard twice to get and confirm a user-entered password
205 /// string.
206 ///
207 /// @param[out] newPassword Overwritten with user input if return=true.
208 /// @param[in] heading String shown on dialog title.
209 /// @param[in] allowEmptyResult
210 /// @param[in] autoCloseMs To close the dialog after a specified time,
211 /// in milliseconds, default is 0 which keeps
212 /// the dialog open indefinitely.
213 /// @return true if successful display and user input.
214 /// false if unsuccessful display, no user
215 /// input, or canceled editing.
216 ///
217 ///
218 ///-------------------------------------------------------------------------
219 ///
220 /// **Example:**
221 /// ~~~~~~~~~~~~~{.cpp}
222 /// #include <kodi/General.h>
223 /// #include <kodi/gui/DialogKeyboard.h>
224 ///
225 /// /*
226 /// * The example below shows the complete use of keyboard dialog for password
227 /// * check. If only one check from add-on needed can be function with retries
228 /// * set to '0' called alone.
229 /// *
230 /// * The use of MD5 translated password is always required for the check on Kodi!
231 /// */
232 ///
233 /// int maxretries = 3;
234 /// /*
235 /// * Password names need to be send as md5 sum to kodi.
236 /// */
237 /// std::string password;
238 /// kodi::GetMD5("kodi", password);
239 ///
240 /// /*
241 /// * To the loop about password checks.
242 /// */
243 /// int ret;
244 /// for (unsigned int i = 0; i < maxretries; i++)
245 /// {
246 /// /*
247 /// * Ask the user about the password.
248 /// */
249 /// ret = ::kodi::gui::DialogKeyboard::ShowAndVerifyPassword(password, "Demo password call for PW 'kodi'", i, 0);
250 /// if (ret == 0)
251 /// {
252 /// fprintf(stderr, "Password successfull confirmed after '%i' tries\n", i+1);
253 /// break;
254 /// }
255 /// else if (ret < 0)
256 /// {
257 /// fprintf(stderr, "Canceled editing on try '%i'\n", i+1);
258 /// break;
259 /// }
260 /// else /* if (ret > 0) */
261 /// {
262 /// fprintf(stderr, "Wrong password entered on try '%i'\n", i+1);
263 /// }
264 /// }
265 /// ~~~~~~~~~~~~~
266 ///
267 inline bool ShowAndVerifyNewPassword(std::string& newPassword, const std::string& heading, bool allowEmptyResult, unsigned int autoCloseMs = 0)
268 {
269 using namespace ::kodi::addon;
270 char* retString = nullptr;
271 bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_verify_new_password_with_head(CAddonBase::m_interface->toKodi->kodiBase,
272 &retString, heading.c_str(), allowEmptyResult,
273 autoCloseMs);
274 if (retString != nullptr)
275 {
276 if (std::strlen(retString))
277 newPassword = retString;
278 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString);
279 }
280 return ret;
281 }
282 //--------------------------------------------------------------------------
283
284 //==========================================================================
285 ///
286 /// \ingroup cpp_kodi_gui_DialogKeyboard
287 /// @brief Show keyboard twice to get and confirm a user-entered password
288 /// string.
289 ///
290 /// @param[out] newPassword Overwritten with user input if return=true.
291 /// @param[in] autoCloseMs To close the dialog after a specified time,
292 /// in milliseconds, default is 0 which keeps
293 /// the dialog open indefinitely.
294 /// @return true if successful display and user input.
295 /// false if unsuccessful display, no user
296 /// input, or canceled editing.
297 ///
298 inline bool ShowAndVerifyNewPassword(std::string& newPassword, unsigned int autoCloseMs = 0)
299 {
300 using namespace ::kodi::addon;
301 char* retString = nullptr;
302 bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_verify_new_password(CAddonBase::m_interface->toKodi->kodiBase,
303 &retString, autoCloseMs);
304 if (retString != nullptr)
305 {
306 if (std::strlen(retString))
307 newPassword = retString;
308 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString);
309 }
310 return ret;
311 }
312 //--------------------------------------------------------------------------
313
314 //==========================================================================
315 ///
316 /// \ingroup cpp_kodi_gui_DialogKeyboard
317 /// @brief Show keyboard and verify user input against `password`.
318 ///
319 /// @param[in,out] password Value to compare against user input.
320 /// @param[in] heading String shown on dialog title.
321 /// @param[in] retries If greater than 0, shows "Incorrect
322 /// password, %d retries left" on dialog line 2,
323 /// else line 2 is blank.
324 /// @param[in] autoCloseMs To close the dialog after a specified time,
325 /// in milliseconds, default is 0 which keeps
326 /// the dialog open indefinitely.
327 /// @return 0 if successful display and user input. 1 if
328 /// unsuccessful input. -1 if no user input or
329 /// canceled editing.
330 ///
331 inline int ShowAndVerifyPassword(std::string& password, const std::string& heading, int retries, unsigned int autoCloseMs = 0)
332 {
333 using namespace ::kodi::addon;
334 char* retString = nullptr;
335 int ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_verify_password(CAddonBase::m_interface->toKodi->kodiBase,
336 password.c_str(), &retString, heading.c_str(),
337 retries, autoCloseMs);
338 if (retString != nullptr)
339 {
340 if (std::strlen(retString))
341 password = retString;
342 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString);
343 }
344 return ret;
345 }
346 //--------------------------------------------------------------------------
347
348 //==========================================================================
349 ///
350 /// \ingroup cpp_kodi_gui_DialogKeyboard
351 /// @brief Shows a filter related keyboard
352 ///
353 /// @param[in,out] text Overwritten with user input if return=true.
354 /// @param[in] searching Use dialog for search and send our search
355 /// message in safe way (only the active window
356 /// needs it)
357 /// - header name if true is "Enter search string"
358 /// - header name if false is "Enter value"
359 /// @param autoCloseMs To close the dialog after a specified time,
360 /// in milliseconds, default is 0 which keeps
361 /// the dialog open indefinitely.
362 /// @return true if successful display and user input.
363 /// false if unsuccessful display, no user
364 /// input, or canceled editing.
365 ///
366 inline bool ShowAndGetFilter(std::string& text, bool searching, unsigned int autoCloseMs = 0)
367 {
368 using namespace ::kodi::addon;
369 char* retString = nullptr;
370 bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_get_filter(CAddonBase::m_interface->toKodi->kodiBase,
371 text.c_str(), &retString, searching, autoCloseMs);
372 if (retString != nullptr)
373 {
374 if (std::strlen(retString))
375 text = retString;
376 CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString);
377 }
378 return ret;
379 }
380 //--------------------------------------------------------------------------
381
382 //==========================================================================
383 ///
384 /// \ingroup cpp_kodi_gui_DialogKeyboard
385 /// @brief Send a text to a visible keyboard
386 ///
387 /// @param[in] text Overwritten with user input if return=true.
388 /// @param[in] closeKeyboard The open dialog is if also closed on 'true'.
389 /// @return true if successful done, false if
390 /// unsuccessful or keyboard not present.
391 ///
392 inline bool SendTextToActiveKeyboard(const std::string& text, bool closeKeyboard = false)
393 {
394 using namespace ::kodi::addon;
395 return CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->send_text_to_active_keyboard(CAddonBase::m_interface->toKodi->kodiBase,
396 text.c_str(), closeKeyboard);
397 }
398 //--------------------------------------------------------------------------
399
400 //==========================================================================
401 ///
402 /// \ingroup cpp_kodi_gui_DialogKeyboard
403 /// @brief Check for visible keyboard on GUI
404 ///
405 /// @return true if keyboard present, false if not present
406 ///
407 inline bool IsKeyboardActivated()
408 {
409 using namespace ::kodi::addon;
410 return CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->is_keyboard_activated(CAddonBase::m_interface->toKodi->kodiBase);
411 }
412 //--------------------------------------------------------------------------
413 };
414
415} /* namespace gui */
416} /* namespace kodi */
generated by cgit v1.2.3 (git 2.25.1) at 2026-01-12 07:03:47 +0000