Software keyboard applet. More...

#include <3ds/types.h>

Data Structures
struct	SwkbdDictWord
	Keyboard dictionary word for predictive input. More...

struct	SwkbdStatusData
	Keyboard status data. More...

struct	SwkbdLearningData
	Keyboard predictive input learning data. More...

struct	SwkbdExtra
	Internal libctru book-keeping structure for software keyboards. More...

struct	SwkbdState
	Software keyboard parameter structure, it shouldn't be modified directly. More...

Macros
#define	SWKBD_MAX_WORD_LEN 40
	Maximum dictionary word length, in UTF-16 code units.

#define	SWKBD_MAX_BUTTON_TEXT_LEN 16
	Maximum button text length, in UTF-16 code units.

#define	SWKBD_MAX_HINT_TEXT_LEN 64
	Maximum hint text length, in UTF-16 code units.

#define	SWKBD_MAX_CALLBACK_MSG_LEN 256
	Maximum filter callback error message length, in UTF-16 code units.

Typedefs
typedef SwkbdCallbackResult(*	SwkbdCallbackFn) (void user, const char ppMessage, const char text, size_t textlen)
	Keyboard filter callback function.

Enumerations
enum	SwkbdType { SWKBD_TYPE_NORMAL = 0 , SWKBD_TYPE_QWERTY , SWKBD_TYPE_NUMPAD , SWKBD_TYPE_WESTERN }
	Keyboard types. More...

enum	SwkbdValidInput { SWKBD_ANYTHING = 0 , SWKBD_NOTEMPTY , SWKBD_NOTEMPTY_NOTBLANK , SWKBD_NOTBLANK_NOTEMPTY = SWKBD_NOTEMPTY_NOTBLANK , SWKBD_NOTBLANK , SWKBD_FIXEDLEN }
	Accepted input types. More...

enum	SwkbdButton { SWKBD_BUTTON_LEFT = 0 , SWKBD_BUTTON_MIDDLE , SWKBD_BUTTON_RIGHT , SWKBD_BUTTON_CONFIRM = SWKBD_BUTTON_RIGHT , SWKBD_BUTTON_NONE }
	Keyboard dialog buttons. More...

enum	SwkbdPasswordMode { SWKBD_PASSWORD_NONE = 0 , SWKBD_PASSWORD_HIDE , SWKBD_PASSWORD_HIDE_DELAY }
	Keyboard password modes. More...

enum	{ SWKBD_FILTER_DIGITS = BIT(0) , SWKBD_FILTER_AT = BIT(1) , SWKBD_FILTER_PERCENT = BIT(2) , SWKBD_FILTER_BACKSLASH = BIT(3) , SWKBD_FILTER_PROFANITY = BIT(4) , SWKBD_FILTER_CALLBACK = BIT(5) }
	Keyboard input filtering flags. More...

enum	{ SWKBD_PARENTAL = BIT(0) , SWKBD_DARKEN_TOP_SCREEN = BIT(1) , SWKBD_PREDICTIVE_INPUT = BIT(2) , SWKBD_MULTILINE = BIT(3) , SWKBD_FIXED_WIDTH = BIT(4) , SWKBD_ALLOW_HOME = BIT(5) , SWKBD_ALLOW_RESET = BIT(6) , SWKBD_ALLOW_POWER = BIT(7) , SWKBD_DEFAULT_QWERTY = BIT(9) }
	Keyboard features. More...

enum	SwkbdCallbackResult { SWKBD_CALLBACK_OK = 0 , SWKBD_CALLBACK_CLOSE , SWKBD_CALLBACK_CONTINUE }
	Keyboard filter callback return values. More...

enum	SwkbdResult { SWKBD_NONE = -1 , SWKBD_INVALID_INPUT = -2 , SWKBD_OUTOFMEM = -3 , SWKBD_D0_CLICK = 0 , SWKBD_D1_CLICK0 , SWKBD_D1_CLICK1 , SWKBD_D2_CLICK0 , SWKBD_D2_CLICK1 , SWKBD_D2_CLICK2 , SWKBD_HOMEPRESSED = 10 , SWKBD_RESETPRESSED , SWKBD_POWERPRESSED , SWKBD_PARENTAL_OK = 20 , SWKBD_PARENTAL_FAIL , SWKBD_BANNED_INPUT = 30 }
	Keyboard return values. More...

Functions
void	swkbdInit (SwkbdState *swkbd, SwkbdType type, int numButtons, int maxTextLength)
	Initializes software keyboard status. More...

static void	swkbdSetPasswordMode (SwkbdState *swkbd, SwkbdPasswordMode mode)
	Configures password mode in a software keyboard. More...

static void	swkbdSetValidation (SwkbdState *swkbd, SwkbdValidInput validInput, u32 filterFlags, int maxDigits)
	Configures input validation in a software keyboard. More...

static void	swkbdSetNumpadKeys (SwkbdState *swkbd, int left, int right)
	Configures what characters will the two bottom keys in a numpad produce. More...

void	swkbdSetFeatures (SwkbdState *swkbd, u32 features)
	Specifies which special features are enabled in a software keyboard. More...

void	swkbdSetHintText (SwkbdState swkbd, const char text)
	Sets the hint text of a software keyboard (that is, the help text that is displayed when the textbox is empty). More...

void	swkbdSetButton (SwkbdState swkbd, SwkbdButton button, const char text, bool submit)
	Configures a dialog button in a software keyboard. More...

void	swkbdSetInitialText (SwkbdState swkbd, const char text)
	Sets the initial text that a software keyboard will display on launch. More...

void	swkbdSetDictWord (SwkbdDictWord word, const char reading, const char *text)
	Configures a word in a predictive dictionary for use with a software keyboard. More...

void	swkbdSetDictionary (SwkbdState swkbd, const SwkbdDictWord dict, int wordCount)
	Sets the custom word dictionary to be used with the predictive input system of a software keyboard. More...

void	swkbdSetStatusData (SwkbdState swkbd, SwkbdStatusData data, bool in, bool out)
	Configures software keyboard internal status management. More...

void	swkbdSetLearningData (SwkbdState swkbd, SwkbdLearningData data, bool in, bool out)
	Configures software keyboard predictive input learning data management. More...

void	swkbdSetFilterCallback (SwkbdState swkbd, SwkbdCallbackFn callback, void user)
	Configures a custom function to be used to check the validity of input when it is submitted in a software keyboard. More...

SwkbdButton	swkbdInputText (SwkbdState swkbd, char buf, size_t bufsize)
	Launches a software keyboard in order to input text. More...

static SwkbdResult	swkbdGetResult (SwkbdState *swkbd)
	Retrieves the result condition of a software keyboard after it has been used. More...

Detailed Description

Software keyboard applet.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Keyboard input filtering flags.

Enumerator
SWKBD_FILTER_DIGITS	Disallow the use of more than a certain number of digits (0 or more)
SWKBD_FILTER_AT	Disallow the use of the @ sign.
SWKBD_FILTER_PERCENT	Disallow the use of the % sign.
SWKBD_FILTER_BACKSLASH	Disallow the use of the \ sign.
SWKBD_FILTER_PROFANITY	Disallow profanity using Nintendo's profanity filter.
SWKBD_FILTER_CALLBACK	Use a callback in order to check the input.

◆ anonymous enum

anonymous enum

Keyboard features.

Enumerator
SWKBD_PARENTAL	Parental PIN mode.
SWKBD_DARKEN_TOP_SCREEN	Darken the top screen when the keyboard is shown.
SWKBD_PREDICTIVE_INPUT	Enable predictive input (necessary for Kanji input in JPN systems).
SWKBD_MULTILINE	Enable multiline input.
SWKBD_FIXED_WIDTH	Enable fixed-width mode.
SWKBD_ALLOW_HOME	Allow the usage of the HOME button.
SWKBD_ALLOW_RESET	Allow the usage of a software-reset combination.
SWKBD_ALLOW_POWER	Allow the usage of the POWER button.
SWKBD_DEFAULT_QWERTY	Default to the QWERTY page when the keyboard is shown.

◆ SwkbdButton

enum SwkbdButton

Keyboard dialog buttons.

Enumerator
SWKBD_BUTTON_LEFT	Left button (usually Cancel)
SWKBD_BUTTON_MIDDLE	Middle button (usually I Forgot)
SWKBD_BUTTON_RIGHT	Right button (usually OK)
SWKBD_BUTTON_NONE	No button (returned by swkbdInputText in special cases)

◆ SwkbdCallbackResult

enum SwkbdCallbackResult

Keyboard filter callback return values.

Enumerator
SWKBD_CALLBACK_OK	Specifies that the input is valid.
SWKBD_CALLBACK_CLOSE	Displays an error message, then closes the keyboard.
SWKBD_CALLBACK_CONTINUE	Displays an error message and continues displaying the keyboard.

◆ SwkbdPasswordMode

enum SwkbdPasswordMode

Keyboard password modes.

Enumerator
SWKBD_PASSWORD_NONE	Characters are not concealed.
SWKBD_PASSWORD_HIDE	Characters are concealed immediately.
SWKBD_PASSWORD_HIDE_DELAY	Characters are concealed a second after they've been typed.

◆ SwkbdResult

enum SwkbdResult

Keyboard return values.

Enumerator
SWKBD_NONE	Dummy/unused.
SWKBD_INVALID_INPUT	Invalid parameters to swkbd.
SWKBD_OUTOFMEM	Out of memory.
SWKBD_D0_CLICK	The button was clicked in 1-button dialogs.
SWKBD_D1_CLICK0	The left button was clicked in 2-button dialogs.
SWKBD_D1_CLICK1	The right button was clicked in 2-button dialogs.
SWKBD_D2_CLICK0	The left button was clicked in 3-button dialogs.
SWKBD_D2_CLICK1	The middle button was clicked in 3-button dialogs.
SWKBD_D2_CLICK2	The right button was clicked in 3-button dialogs.
SWKBD_HOMEPRESSED	The HOME button was pressed.
SWKBD_RESETPRESSED	The soft-reset key combination was pressed.
SWKBD_POWERPRESSED	The POWER button was pressed.
SWKBD_PARENTAL_OK	The parental PIN was verified successfully.
SWKBD_PARENTAL_FAIL	The parental PIN was incorrect.
SWKBD_BANNED_INPUT	The filter callback returned SWKBD_CALLBACK_CLOSE.

◆ SwkbdType

enum SwkbdType

Keyboard types.

Enumerator
SWKBD_TYPE_NORMAL	Normal keyboard with several pages (QWERTY/accents/symbol/mobile)
SWKBD_TYPE_QWERTY	QWERTY keyboard only.
SWKBD_TYPE_NUMPAD	Number pad.
SWKBD_TYPE_WESTERN	On JPN systems, a text keyboard without Japanese input capabilities, otherwise same as SWKBD_TYPE_NORMAL.

◆ SwkbdValidInput

enum SwkbdValidInput

Accepted input types.

Enumerator
SWKBD_ANYTHING	All inputs are accepted.
SWKBD_NOTEMPTY	Empty inputs are not accepted.
SWKBD_NOTEMPTY_NOTBLANK	Empty or blank inputs (consisting solely of whitespace) are not accepted.
SWKBD_NOTBLANK	Blank inputs (consisting solely of whitespace) are not accepted, but empty inputs are.
SWKBD_FIXEDLEN	The input must have a fixed length (specified by maxTextLength in swkbdInit).

Function Documentation

◆ swkbdGetResult()

static SwkbdResult swkbdGetResult ( SwkbdState * swkbd )

inlinestatic

Retrieves the result condition of a software keyboard after it has been used.

Parameters

swkbd Pointer to swkbd state.

Returns: The result value.

Examples: input/software-keyboard/source/main.c.

◆ swkbdInit()

void swkbdInit	(	SwkbdState *	swkbd,
		SwkbdType	type,
		int	numButtons,
		int	maxTextLength
	)

Initializes software keyboard status.

Parameters

swkbd	Pointer to swkbd state.
type	Keyboard type.
numButtons	Number of dialog buttons to display (1, 2 or 3).
maxTextLength	Maximum number of UTF-16 code units that input text can have (or -1 to let libctru use a big default).

Examples: input/software-keyboard/source/main.c.

◆ swkbdInputText()

SwkbdButton swkbdInputText	(	SwkbdState *	swkbd,
		char *	buf,
		size_t	bufsize
	)

Launches a software keyboard in order to input text.

Parameters

swkbd	Pointer to swkbd state.
buf	Pointer to output buffer which will hold the inputted text.
bufsize	Maximum number of UTF-8 code units that the buffer can hold (including null terminator).

Returns: The identifier of the dialog button that was pressed, or SWKBD_BUTTON_NONE if a different condition was triggered - in that case use swkbdGetResult to check the condition.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetButton()

void swkbdSetButton	(	SwkbdState *	swkbd,
		SwkbdButton	button,
		const char *	text,
		bool	submit
	)

Configures a dialog button in a software keyboard.

Parameters

swkbd	Pointer to swkbd state.
button	Specifies which button to configure.
text	Button text.
submit	Specifies whether pushing the button will submit the text or discard it.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetDictionary()

void swkbdSetDictionary	(	SwkbdState *	swkbd,
		const SwkbdDictWord *	dict,
		int	wordCount
	)

Sets the custom word dictionary to be used with the predictive input system of a software keyboard.

Parameters

swkbd	Pointer to swkbd state.
dict	Pointer to dictionary words.
wordCount	Number of words in the dictionary.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetDictWord()

void swkbdSetDictWord	(	SwkbdDictWord *	word,
		const char *	reading,
		const char *	text
	)

Configures a word in a predictive dictionary for use with a software keyboard.

Parameters

word	Pointer to dictionary word structure.
reading	Reading of the word, that is, the sequence of characters that need to be typed to trigger the word in the predictive input system.
text	Spelling of the word, that is, the actual characters that will be produced when the user decides to select the word.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetFeatures()

void swkbdSetFeatures	(	SwkbdState *	swkbd,
		u32	features
	)

Specifies which special features are enabled in a software keyboard.

Parameters

swkbd	Pointer to swkbd state.
features	Feature bitmask.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetFilterCallback()

void swkbdSetFilterCallback	(	SwkbdState *	swkbd,
		SwkbdCallbackFn	callback,
		void *	user
	)

Configures a custom function to be used to check the validity of input when it is submitted in a software keyboard.

Parameters

swkbd	Pointer to swkbd state.
callback	Filter callback function.
user	Custom data to be passed to the callback function.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetHintText()

void swkbdSetHintText	(	SwkbdState *	swkbd,
		const char *	text
	)

Sets the hint text of a software keyboard (that is, the help text that is displayed when the textbox is empty).

Parameters

swkbd	Pointer to swkbd state.
text	Hint text.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetInitialText()

void swkbdSetInitialText	(	SwkbdState *	swkbd,
		const char *	text
	)

Sets the initial text that a software keyboard will display on launch.

Parameters

swkbd	Pointer to swkbd state.
text	Initial text.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetLearningData()

void swkbdSetLearningData	(	SwkbdState *	swkbd,
		SwkbdLearningData *	data,
		bool	in,
		bool	out
	)

Configures software keyboard predictive input learning data management.

Parameters

swkbd	Pointer to swkbd state.
data	Pointer to learning data structure (can be in, out or both depending on the other parameters).
in	Specifies whether the data should be read from the structure when the keyboard is launched.
out	Specifies whether the data should be written to the structure when the keyboard is closed.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetNumpadKeys()

static void swkbdSetNumpadKeys	(	SwkbdState *	swkbd,
		int	left,
		int	right
	)

inlinestatic

Configures what characters will the two bottom keys in a numpad produce.

Parameters

swkbd	Pointer to swkbd state.
left	Unicode codepoint produced by the leftmost key in the bottom row (0 hides the key).
left	Unicode codepoint produced by the rightmost key in the bottom row (0 hides the key).

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetPasswordMode()

static void swkbdSetPasswordMode	(	SwkbdState *	swkbd,
		SwkbdPasswordMode	mode
	)

inlinestatic

Configures password mode in a software keyboard.

Parameters

swkbd	Pointer to swkbd state.
mode	Password mode.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetStatusData()

void swkbdSetStatusData	(	SwkbdState *	swkbd,
		SwkbdStatusData *	data,
		bool	in,
		bool	out
	)

Configures software keyboard internal status management.

Parameters

swkbd	Pointer to swkbd state.
data	Pointer to internal status structure (can be in, out or both depending on the other parameters).
in	Specifies whether the data should be read from the structure when the keyboard is launched.
out	Specifies whether the data should be written to the structure when the keyboard is closed.

Examples: input/software-keyboard/source/main.c.

◆ swkbdSetValidation()

static void swkbdSetValidation	(	SwkbdState *	swkbd,
		SwkbdValidInput	validInput,
		u32	filterFlags,
		int	maxDigits
	)

inlinestatic

Configures input validation in a software keyboard.

Parameters

swkbd	Pointer to swkbd state.
validInput	Specifies which inputs are valid.
filterFlags	Bitmask specifying which characters are disallowed (filtered).
maxDigits	In case digits are disallowed, specifies how many digits are allowed at maximum in input strings (0 completely restricts digit input).

Examples: input/software-keyboard/source/main.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

◆ SwkbdButton

◆ SwkbdCallbackResult

◆ SwkbdPasswordMode

◆ SwkbdResult

◆ SwkbdType

◆ SwkbdValidInput

Function Documentation

◆ swkbdGetResult()

◆ swkbdInit()

◆ swkbdInputText()

◆ swkbdSetButton()

◆ swkbdSetDictionary()

◆ swkbdSetDictWord()

◆ swkbdSetFeatures()

◆ swkbdSetFilterCallback()

◆ swkbdSetHintText()

◆ swkbdSetInitialText()

◆ swkbdSetLearningData()

◆ swkbdSetNumpadKeys()

◆ swkbdSetPasswordMode()

◆ swkbdSetStatusData()

◆ swkbdSetValidation()