From 4c3251ec645c8b71820dab7e51e612e5919d4e75 Mon Sep 17 00:00:00 2001 From: manuel Date: Sun, 23 Jul 2017 16:59:43 +0200 Subject: sync with upstream --- .../include/kodi/gui/dialogs/Keyboard.h | 419 +++++++++++++++++++++ 1 file changed, 419 insertions(+) create mode 100644 xbmc/addons/kodi-addon-dev-kit/include/kodi/gui/dialogs/Keyboard.h (limited to 'xbmc/addons/kodi-addon-dev-kit/include/kodi/gui/dialogs/Keyboard.h') 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 @@ +#pragma once +/* + * Copyright (C) 2005-2017 Team KODI + * http://kodi.tv + * + * This Program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2, 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 General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with KODI; see the file COPYING. If not, see + * . + * + */ + +#include "../definitions.h" +#include "../../AddonBase.h" + +namespace kodi +{ +namespace gui +{ +namespace dialogs +{ + + //============================================================================ + /// + /// \defgroup cpp_kodi_gui_dialogs_Keyboard Dialog Keyboard + /// \ingroup cpp_kodi_gui + /// @brief \cpp_namespace{ kodi::gui::dialogs::Keyboard } + /// **Keyboard dialogs** + /// + /// The functions listed below have to be permitted by the user for the + /// representation of a keyboard around an input. + /// + /// The class supports several kinds, from an easy text choice up to the + /// passport Word production and their confirmation for add-on. + /// + /// It has the header \ref Keyboard.h "#include " + /// be included to enjoy it. + /// + namespace Keyboard + { + //========================================================================== + /// + /// \ingroup cpp_kodi_gui_dialogs_Keyboard + /// @brief Show keyboard with initial value `text` and replace with result + /// string. + /// + /// @param[in,out] text Overwritten with user input if return=true. + /// @param[in] heading String shown on dialog title. + /// @param[in] allowEmptyResult Whether a blank password is valid or not. + /// @param[in] hiddenInput The inserted input is not shown as text. + /// @param[in] autoCloseMs To close the dialog after a specified + /// time, in milliseconds, default is 0 which + /// keeps the dialog open indefinitely. + /// @return true if successful display and user input. + /// false if unsuccessful display, no user + /// input, or canceled editing. + /// + /// + ///------------------------------------------------------------------------- + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.cpp} + /// #include + /// + /// /* + /// * The example shows the display of keyboard call dialog at Kodi from the add-on. + /// * Below all values are set, however, can last two (hidden input = false and autoCloseMs = 0) + /// * to be released if not needed. + /// */ + /// std::string text = "Please change me to them want you want"; /*< It can be leaved empty or a + /// entry text added */ + /// bool bRet = ::kodi::gui::dialogs::Keyboard::ShowAndGetInput(text, + /// "Demonstration text entry", + /// true, + /// false, + /// 0); + /// fprintf(stderr, "Written keyboard input is : '%s' and was %s\n", + /// text.c_str(), bRet ? "OK" : "Canceled"); + /// ~~~~~~~~~~~~~ + /// + inline bool ShowAndGetInput(std::string& text, const std::string& heading, bool allowEmptyResult, bool hiddenInput = false, unsigned int autoCloseMs = 0) + { + using namespace ::kodi::addon; + char* retString = nullptr; + bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_get_input_with_head(CAddonBase::m_interface->toKodi->kodiBase, + text.c_str(), &retString, heading.c_str(), allowEmptyResult, + hiddenInput, autoCloseMs); + if (retString != nullptr) + { + if (std::strlen(retString)) + text = retString; + CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString); + } + return ret; + } + //-------------------------------------------------------------------------- + + //========================================================================== + /// + /// \ingroup cpp_kodi_gui_dialogs_Keyboard + /// @brief The example shows the display of keyboard call dialog at Kodi + /// from the add-on. + /// + /// @param[out] text Overwritten with user input if return=true. + /// @param[in] allowEmptyResult If set to true keyboard can also exited + /// without entered text. + /// @param[in] autoCloseMs To close the dialog after a specified time, + /// in milliseconds, default is 0 which keeps + /// the dialog open indefinitely. + /// @return true if successful display and user input. + /// false if unsuccessful display, no user + /// input, or canceled editing. + /// + inline bool ShowAndGetInput(std::string& text, bool allowEmptyResult, unsigned int autoCloseMs = 0) + { + using namespace ::kodi::addon; + char* retString = nullptr; + bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_get_input(CAddonBase::m_interface->toKodi->kodiBase, + text.c_str(), &retString, + allowEmptyResult, autoCloseMs); + if (retString != nullptr) + { + if (std::strlen(retString)) + text = retString; + CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString); + } + return ret; + } + //-------------------------------------------------------------------------- + + //========================================================================== + /// + /// \ingroup cpp_kodi_gui_dialogs_Keyboard + /// @brief Shows keyboard and prompts for a password. Differs from + /// `ShowAndVerifyNewPassword()` in that no second verification + /// + /// @param[in,out] newPassword Overwritten with user input if return=true. + /// @param[in] heading String shown on dialog title. + /// @param[in] allowEmptyResult Whether a blank password is valid or not. + /// @param[in] autoCloseMs To close the dialog after a specified time, + /// in milliseconds, default is 0 which keeps + /// the dialog open indefinitely. + /// @return true if successful display and user input. + /// false if unsuccessful display, no user + /// input, or canceled editing. + /// + inline bool ShowAndGetNewPassword(std::string& newPassword, const std::string& heading, bool allowEmptyResult, unsigned int autoCloseMs = 0) + { + using namespace ::kodi::addon; + char* retString = nullptr; + bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_get_new_password_with_head(CAddonBase::m_interface->toKodi->kodiBase, + newPassword.c_str(), &retString, heading.c_str(), + allowEmptyResult, autoCloseMs); + if (retString != nullptr) + { + if (std::strlen(retString)) + newPassword = retString; + CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString); + } + return ret; + } + //-------------------------------------------------------------------------- + + //========================================================================== + /// + /// \ingroup cpp_kodi_gui_dialogs_Keyboard + /// @brief Shows keyboard and prompts for a password. Differs from + /// `ShowAndVerifyNewPassword()` in that no second verification + /// + /// @param[in,out] newPassword Overwritten with user input if return=true. + /// @param[in] autoCloseMs To close the dialog after a specified time, + /// in milliseconds, default is 0 which keeps + /// the dialog open indefinitely. + /// @return true if successful display and user input. + /// false if unsuccessful display, no user + /// input, or canceled editing. + /// + inline bool ShowAndGetNewPassword(std::string& newPassword, unsigned int autoCloseMs = 0) + { + using namespace ::kodi::addon; + char* retString = nullptr; + bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_get_new_password(CAddonBase::m_interface->toKodi->kodiBase, + newPassword.c_str(), &retString, autoCloseMs); + if (retString != nullptr) + { + if (std::strlen(retString)) + newPassword = retString; + CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString); + } + return ret; + } + //-------------------------------------------------------------------------- + + //========================================================================== + /// + /// \ingroup cpp_kodi_gui_dialogs_Keyboard + /// @brief Show keyboard twice to get and confirm a user-entered password + /// string. + /// + /// @param[out] newPassword Overwritten with user input if return=true. + /// @param[in] heading String shown on dialog title. + /// @param[in] allowEmptyResult + /// @param[in] autoCloseMs To close the dialog after a specified time, + /// in milliseconds, default is 0 which keeps + /// the dialog open indefinitely. + /// @return true if successful display and user input. + /// false if unsuccessful display, no user + /// input, or canceled editing. + /// + /// + ///------------------------------------------------------------------------- + /// + /// **Example:** + /// ~~~~~~~~~~~~~{.cpp} + /// #include + /// #include + /// + /// /* + /// * The example below shows the complete use of keyboard dialog for password + /// * check. If only one check from add-on needed can be function with retries + /// * set to '0' called alone. + /// * + /// * The use of MD5 translated password is always required for the check on Kodi! + /// */ + /// + /// int maxretries = 3; + /// /* + /// * Password names need to be send as md5 sum to kodi. + /// */ + /// std::string password; + /// kodi::GetMD5("kodi", password); + /// + /// /* + /// * To the loop about password checks. + /// */ + /// int ret; + /// for (unsigned int i = 0; i < maxretries; i++) + /// { + /// /* + /// * Ask the user about the password. + /// */ + /// ret = ::kodi::gui::dialogs::Keyboard::ShowAndVerifyPassword(password, "Demo password call for PW 'kodi'", i, 0); + /// if (ret == 0) + /// { + /// fprintf(stderr, "Password successfull confirmed after '%i' tries\n", i+1); + /// break; + /// } + /// else if (ret < 0) + /// { + /// fprintf(stderr, "Canceled editing on try '%i'\n", i+1); + /// break; + /// } + /// else /* if (ret > 0) */ + /// { + /// fprintf(stderr, "Wrong password entered on try '%i'\n", i+1); + /// } + /// } + /// ~~~~~~~~~~~~~ + /// + inline bool ShowAndVerifyNewPassword(std::string& newPassword, const std::string& heading, bool allowEmptyResult, unsigned int autoCloseMs = 0) + { + using namespace ::kodi::addon; + char* retString = nullptr; + bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_verify_new_password_with_head(CAddonBase::m_interface->toKodi->kodiBase, + &retString, heading.c_str(), allowEmptyResult, + autoCloseMs); + if (retString != nullptr) + { + if (std::strlen(retString)) + newPassword = retString; + CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString); + } + return ret; + } + //-------------------------------------------------------------------------- + + //========================================================================== + /// + /// \ingroup cpp_kodi_gui_dialogs_Keyboard + /// @brief Show keyboard twice to get and confirm a user-entered password + /// string. + /// + /// @param[out] newPassword Overwritten with user input if return=true. + /// @param[in] autoCloseMs To close the dialog after a specified time, + /// in milliseconds, default is 0 which keeps + /// the dialog open indefinitely. + /// @return true if successful display and user input. + /// false if unsuccessful display, no user + /// input, or canceled editing. + /// + inline bool ShowAndVerifyNewPassword(std::string& newPassword, unsigned int autoCloseMs = 0) + { + using namespace ::kodi::addon; + char* retString = nullptr; + bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_verify_new_password(CAddonBase::m_interface->toKodi->kodiBase, + &retString, autoCloseMs); + if (retString != nullptr) + { + if (std::strlen(retString)) + newPassword = retString; + CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString); + } + return ret; + } + //-------------------------------------------------------------------------- + + //========================================================================== + /// + /// \ingroup cpp_kodi_gui_dialogs_Keyboard + /// @brief Show keyboard and verify user input against `password`. + /// + /// @param[in,out] password Value to compare against user input. + /// @param[in] heading String shown on dialog title. + /// @param[in] retries If greater than 0, shows "Incorrect + /// password, %d retries left" on dialog line 2, + /// else line 2 is blank. + /// @param[in] autoCloseMs To close the dialog after a specified time, + /// in milliseconds, default is 0 which keeps + /// the dialog open indefinitely. + /// @return 0 if successful display and user input. 1 if + /// unsuccessful input. -1 if no user input or + /// canceled editing. + /// + inline int ShowAndVerifyPassword(std::string& password, const std::string& heading, int retries, unsigned int autoCloseMs = 0) + { + using namespace ::kodi::addon; + char* retString = nullptr; + int ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_verify_password(CAddonBase::m_interface->toKodi->kodiBase, + password.c_str(), &retString, heading.c_str(), + retries, autoCloseMs); + if (retString != nullptr) + { + if (std::strlen(retString)) + password = retString; + CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString); + } + return ret; + } + //-------------------------------------------------------------------------- + + //========================================================================== + /// + /// \ingroup cpp_kodi_gui_dialogs_Keyboard + /// @brief Shows a filter related keyboard + /// + /// @param[in,out] text Overwritten with user input if return=true. + /// @param[in] searching Use dialog for search and send our search + /// message in safe way (only the active window + /// needs it) + /// - header name if true is "Enter search string" + /// - header name if false is "Enter value" + /// @param autoCloseMs To close the dialog after a specified time, + /// in milliseconds, default is 0 which keeps + /// the dialog open indefinitely. + /// @return true if successful display and user input. + /// false if unsuccessful display, no user + /// input, or canceled editing. + /// + inline bool ShowAndGetFilter(std::string& text, bool searching, unsigned int autoCloseMs = 0) + { + using namespace ::kodi::addon; + char* retString = nullptr; + bool ret = CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->show_and_get_filter(CAddonBase::m_interface->toKodi->kodiBase, + text.c_str(), &retString, searching, autoCloseMs); + if (retString != nullptr) + { + if (std::strlen(retString)) + text = retString; + CAddonBase::m_interface->toKodi->free_string(CAddonBase::m_interface->toKodi->kodiBase, retString); + } + return ret; + } + //-------------------------------------------------------------------------- + + //========================================================================== + /// + /// \ingroup cpp_kodi_gui_dialogs_Keyboard + /// @brief Send a text to a visible keyboard + /// + /// @param[in] text Overwritten with user input if return=true. + /// @param[in] closeKeyboard The open dialog is if also closed on 'true'. + /// @return true if successful done, false if + /// unsuccessful or keyboard not present. + /// + inline bool SendTextToActiveKeyboard(const std::string& text, bool closeKeyboard = false) + { + using namespace ::kodi::addon; + return CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->send_text_to_active_keyboard(CAddonBase::m_interface->toKodi->kodiBase, + text.c_str(), closeKeyboard); + } + //-------------------------------------------------------------------------- + + //========================================================================== + /// + /// \ingroup cpp_kodi_gui_dialogs_Keyboard + /// @brief Check for visible keyboard on GUI + /// + /// @return true if keyboard present, false if not present + /// + inline bool IsKeyboardActivated() + { + using namespace ::kodi::addon; + return CAddonBase::m_interface->toKodi->kodi_gui->dialogKeyboard->is_keyboard_activated(CAddonBase::m_interface->toKodi->kodiBase); + } + //-------------------------------------------------------------------------- + }; + +} /* namespace dialogs */ +} /* namespace gui */ +} /* namespace kodi */ -- cgit v1.2.3