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 ATTR_DLL_LOCAL 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 ATTR_DLL_LOCAL 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 ATTR_DLL_LOCAL 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 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 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 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 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 ATTR_DLL_LOCAL 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 ATTR_DLL_LOCAL 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 ATTR_DLL_LOCAL IsKeyboardActivated ( )

inline

Check for visible keyboard on GUI.

Returns: true if keyboard present, false if not present