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