swkbd.h File Reference

Software keyboard applet. More...

`#include <3ds/types.h>`

Go to the source code of this file.

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