Dialog Keyboard

Detailed Description

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 #include <kodi/gui/dialogs/Keyboard.h> be included to enjoy it.

Function Documentation

ShowAndGetInput() [1/2]

bool ATTRIBUTE_HIDDEN kodi::gui::dialogs::Keyboard::ShowAndGetInput ( std::string &  text, const std::string &  heading, bool  allowEmptyResult, bool  hiddenInput = false, unsigned int  autoCloseMs = 0  )

inline

Show keyboard with initial value text and replace with result string.

Parameters

[in,out]	text	Overwritten with user input if return=true.
[in]	heading	String shown on dialog title.
[in]	allowEmptyResult	Whether a blank password is valid or not.
[in]	hiddenInput	[opt] The inserted input is not shown as text.
[in]	autoCloseMs	[opt] To close the dialog after a specified time, in milliseconds, default is 0 which keeps the dialog open indefinitely.

Returns

true if successful display and user input. false if unsuccessful display, no user input, or canceled editing.

---

Example:

#include <kodi/gui/dialogs/Keyboard.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::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");

ShowAndGetInput() [2/2]

bool ATTRIBUTE_HIDDEN kodi::gui::dialogs::Keyboard::ShowAndGetInput ( std::string &  text, bool  allowEmptyResult, unsigned int  autoCloseMs = 0  )

inline

The example shows the display of keyboard call dialog at Kodi from the add-on.

Parameters

[out]	text	Overwritten with user input if return=true.
[in]	allowEmptyResult	If set to true keyboard can also exited without entered text.
[in]	autoCloseMs	[opt] To close the dialog after a specified time, in milliseconds, default is 0 which keeps the dialog open indefinitely.

Returns

true if successful display and user input. false if unsuccessful display, no user input, or canceled editing.

ShowAndGetNewPassword() [1/2]

bool ATTRIBUTE_HIDDEN kodi::gui::dialogs::Keyboard::ShowAndGetNewPassword ( std::string &  newPassword, const std::string &  heading, bool  allowEmptyResult, unsigned int  autoCloseMs = 0  )

inline

Shows keyboard and prompts for a password. Differs from ShowAndVerifyNewPassword() in that no second verification.

Parameters

[in,out]	newPassword	Overwritten with user input if return=true.
[in]	heading	String shown on dialog title.
[in]	allowEmptyResult	Whether a blank password is valid or not.
[in]	autoCloseMs	[opt] To close the dialog after a specified time, in milliseconds, default is 0 which keeps the dialog open indefinitely.

Returns

true if successful display and user input. false if unsuccessful display, no user input, or canceled editing.

ShowAndGetNewPassword() [2/2]

bool ATTRIBUTE_HIDDEN kodi::gui::dialogs::Keyboard::ShowAndGetNewPassword ( std::string &  newPassword, unsigned int  autoCloseMs = 0  )

inline

Shows keyboard and prompts for a password. Differs from ShowAndVerifyNewPassword() in that no second verification.

Parameters

[in,out]	newPassword	Overwritten with user input if return=true.
[in]	autoCloseMs	[opt] To close the dialog after a specified time, in milliseconds, default is 0 which keeps the dialog open indefinitely.

Returns

true if successful display and user input. false if unsuccessful display, no user input, or canceled editing.

ShowAndVerifyNewPassword() [1/2]

bool ATTRIBUTE_HIDDEN kodi::gui::dialogs::Keyboard::ShowAndVerifyNewPassword ( std::string &  newPassword, const std::string &  heading, bool  allowEmptyResult, unsigned int  autoCloseMs = 0  )

inline

Show keyboard twice to get and confirm a user-entered password string.

Parameters

[out]	newPassword	Overwritten with user input if return=true.
[in]	heading	String shown on dialog title.
[in]	allowEmptyResult
[in]	autoCloseMs	[opt] To close the dialog after a specified time, in milliseconds, default is 0 which keeps the dialog open indefinitely.

Returns

true if successful display and user input. false if unsuccessful display, no user input, or canceled editing.

---

Example:

#include <kodi/General.h>
#include <kodi/gui/dialogs/Keyboard.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::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);
  }
}

ShowAndVerifyNewPassword() [2/2]

bool ATTRIBUTE_HIDDEN kodi::gui::dialogs::Keyboard::ShowAndVerifyNewPassword ( std::string &  newPassword, unsigned int  autoCloseMs = 0  )

inline

Show keyboard twice to get and confirm a user-entered password string.

Parameters

[out]	newPassword	Overwritten with user input if return=true.
[in]	autoCloseMs	[opt] To close the dialog after a specified time, in milliseconds, default is 0 which keeps the dialog open indefinitely.

Returns

true if successful display and user input. false if unsuccessful display, no user input, or canceled editing.

ShowAndVerifyPassword()

int ATTRIBUTE_HIDDEN kodi::gui::dialogs::Keyboard::ShowAndVerifyPassword ( std::string &  password, const std::string &  heading, int  retries, unsigned int  autoCloseMs = 0  )

inline

Show keyboard and verify user input against password.

Parameters

[in,out]	password	Value to compare against user input.
[in]	heading	String shown on dialog title.
[in]	retries	If greater than 0, shows "Incorrect password, %d retries left" on dialog line 2, else line 2 is blank.
[in]	autoCloseMs	[opt] To close the dialog after a specified time, in milliseconds, default is 0 which keeps the dialog open indefinitely.

Returns

0 if successful display and user input. 1 if unsuccessful input. -1 if no user input or canceled editing.

ShowAndGetFilter()

bool ATTRIBUTE_HIDDEN kodi::gui::dialogs::Keyboard::ShowAndGetFilter ( std::string &  text, bool  searching, unsigned int  autoCloseMs = 0  )

inline

Shows a filter related keyboard.

Parameters

[in,out]	text	Overwritten with user input if return=true.
[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"
	autoCloseMs	[opt] To close the dialog after a specified time, in milliseconds, default is 0 which keeps the dialog open indefinitely.

Returns

true if successful display and user input. false if unsuccessful display, no user input, or canceled editing.

SendTextToActiveKeyboard()

bool ATTRIBUTE_HIDDEN kodi::gui::dialogs::Keyboard::SendTextToActiveKeyboard ( const std::string &  text, bool  closeKeyboard = false  )

inline

Send a text to a visible keyboard.

Parameters

[in]	text	Overwritten with user input if return=true.
[in]	closeKeyboard	[opt] The open dialog is if also closed on 'true'.

Returns

true if successful done, false if unsuccessful or keyboard not present.

IsKeyboardActivated()

bool ATTRIBUTE_HIDDEN kodi::gui::dialogs::Keyboard::IsKeyboardActivated ( )

inline

Check for visible keyboard on GUI.

Returns

true if keyboard present, false if not present