sync with upstream

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 @@
+#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
+ *  <http://www.gnu.org/licenses/>.
+ *
+ */
+
+#include "definitions.h"
+#include "../AddonBase.h"
+
+namespace kodi
+{
+namespace gui
+{
+
+  //============================================================================
+  ///
+  /// \defgroup cpp_kodi_gui_DialogKeyboard Dialog Keyboard
+  /// \ingroup cpp_kodi_gui
+  /// @brief \cpp_namespace{ kodi::gui::DialogKeyboard }
+  /// **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 DialogKeyboard.h "#include <kodi/gui/DialogKeyboard.h>"
+  /// be included to enjoy it.
+  ///
+  namespace DialogKeyboard
+  {
+    //==========================================================================
+    ///
+    /// \ingroup cpp_kodi_gui_DialogKeyboard
+    /// @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 <kodi/gui/DialogKeyboard.h>
+    ///
+    /// /*
+    ///  * 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::DialogKeyboard::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_DialogKeyboard
+    /// @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_DialogKeyboard
+    /// @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_DialogKeyboard
+    /// @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_DialogKeyboard
+    /// @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 <kodi/General.h>
+    /// #include <kodi/gui/DialogKeyboard.h>
+    ///
+    /// /*
+    ///  * 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::DialogKeyboard::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_DialogKeyboard
+    /// @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_DialogKeyboard
+    /// @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_DialogKeyboard
+    /// @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_DialogKeyboard
+    /// @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_DialogKeyboard
+    /// @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 gui */
+} /* namespace kodi */