Dialog Keyboard

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. More...

Functions
bool ATTR_DLL_LOCAL	kodi::gui::dialogs::Keyboard::ShowAndGetInput (std::string &text, const std::string &heading, bool allowEmptyResult, bool hiddenInput=false, unsigned int autoCloseMs=0)
	Show keyboard with initial value text and replace with result string.
bool ATTR_DLL_LOCAL	kodi::gui::dialogs::Keyboard::ShowAndGetInput (std::string &text, bool allowEmptyResult, unsigned int autoCloseMs=0)
	The example shows the display of keyboard call dialog at Kodi from the add-on.
bool ATTR_DLL_LOCAL	kodi::gui::dialogs::Keyboard::ShowAndGetNewPassword (std::string &newPassword, const std::string &heading, bool allowEmptyResult, unsigned int autoCloseMs=0)
	Shows keyboard and prompts for a password. Differs from ShowAndVerifyNewPassword() in that no second verification.
bool ATTR_DLL_LOCAL	kodi::gui::dialogs::Keyboard::ShowAndGetNewPassword (std::string &newPassword, unsigned int autoCloseMs=0)
	Shows keyboard and prompts for a password. Differs from ShowAndVerifyNewPassword() in that no second verification.
bool ATTR_DLL_LOCAL	kodi::gui::dialogs::Keyboard::ShowAndVerifyNewPassword (std::string &newPassword, const std::string &heading, bool allowEmptyResult, unsigned int autoCloseMs=0)
	Show keyboard twice to get and confirm a user-entered password string.
bool ATTR_DLL_LOCAL	kodi::gui::dialogs::Keyboard::ShowAndVerifyNewPassword (std::string &newPassword, unsigned int autoCloseMs=0)
	Show keyboard twice to get and confirm a user-entered password string.
int ATTR_DLL_LOCAL	kodi::gui::dialogs::Keyboard::ShowAndVerifyPassword (std::string &password, const std::string &heading, int retries, unsigned int autoCloseMs=0)
	Show keyboard and verify user input against password.
bool ATTR_DLL_LOCAL	kodi::gui::dialogs::Keyboard::ShowAndGetFilter (std::string &text, bool searching, unsigned int autoCloseMs=0)
	Shows a filter related keyboard.
bool ATTR_DLL_LOCAL	kodi::gui::dialogs::Keyboard::SendTextToActiveKeyboard (const std::string &text, bool closeKeyboard=false)
	Send a text to a visible keyboard.
bool ATTR_DLL_LOCAL	kodi::gui::dialogs::Keyboard::IsKeyboardActivated ()
	Check for visible keyboard on GUI.

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

IsKeyboardActivated()

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

inline

Check for visible keyboard on GUI.

Returns

true if keyboard present, false if not present

SendTextToActiveKeyboard()

bool ATTR_DLL_LOCAL 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.

ShowAndGetFilter()

bool ATTR_DLL_LOCAL 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.

ShowAndGetInput() [1/2]

bool ATTR_DLL_LOCAL 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.

ShowAndGetInput() [2/2]

bool ATTR_DLL_LOCAL 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");

ShowAndGetNewPassword() [1/2]

bool ATTR_DLL_LOCAL 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 ATTR_DLL_LOCAL 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 ATTR_DLL_LOCAL 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 successfully 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 ATTR_DLL_LOCAL 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 ATTR_DLL_LOCAL 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.