swkbd.h

Go to the documentation of this file.

/**
 * @file swkbd.h
 * @brief Software keyboard applet.
 */
#pragma once
#include <3ds/types.h>
 
/// Keyboard types.
typedef enum
{
    SWKBD_TYPE_NORMAL = 0, ///< 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.
} SwkbdType;
 
/// Accepted input types.
typedef enum
{
    SWKBD_ANYTHING = 0,      ///< 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_NOTEMPTY = SWKBD_NOTEMPTY_NOTBLANK,
    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).
} SwkbdValidInput;
 
/// Keyboard dialog buttons.
typedef enum
{
    SWKBD_BUTTON_LEFT = 0, ///< Left button (usually Cancel)
    SWKBD_BUTTON_MIDDLE,   ///< Middle button (usually I Forgot)
    SWKBD_BUTTON_RIGHT,    ///< Right button (usually OK)
    SWKBD_BUTTON_CONFIRM = SWKBD_BUTTON_RIGHT,
    SWKBD_BUTTON_NONE,     ///< No button (returned by swkbdInputText in special cases)
} SwkbdButton;
 
/// Keyboard password modes.
typedef enum
{
    SWKBD_PASSWORD_NONE = 0,   ///< 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.
} SwkbdPasswordMode;
 
/// Keyboard input filtering flags.
enum
{
    SWKBD_FILTER_DIGITS    = BIT(0), ///< Disallow the use of more than a certain number of digits (0 or more)
    SWKBD_FILTER_AT        = BIT(1), ///< Disallow the use of the @ sign.
    SWKBD_FILTER_PERCENT   = BIT(2), ///< Disallow the use of the % sign.
    SWKBD_FILTER_BACKSLASH = BIT(3), ///< Disallow the use of the \ sign.
    SWKBD_FILTER_PROFANITY = BIT(4), ///< Disallow profanity using Nintendo's profanity filter.
    SWKBD_FILTER_CALLBACK  = BIT(5), ///< Use a callback in order to check the input.
};
 
/// Keyboard features.
enum
{
    SWKBD_PARENTAL          = BIT(0), ///< Parental PIN mode.
    SWKBD_DARKEN_TOP_SCREEN = BIT(1), ///< Darken the top screen when the keyboard is shown.
    SWKBD_PREDICTIVE_INPUT  = BIT(2), ///< Enable predictive input (necessary for Kanji input in JPN systems).
    SWKBD_MULTILINE         = BIT(3), ///< Enable multiline input.
    SWKBD_FIXED_WIDTH       = BIT(4), ///< Enable fixed-width mode.
    SWKBD_ALLOW_HOME        = BIT(5), ///< Allow the usage of the HOME button.
    SWKBD_ALLOW_RESET       = BIT(6), ///< Allow the usage of a software-reset combination.
    SWKBD_ALLOW_POWER       = BIT(7), ///< Allow the usage of the POWER button.
    SWKBD_DEFAULT_QWERTY    = BIT(9), ///< Default to the QWERTY page when the keyboard is shown.
};
 
/// Keyboard filter callback return values.
typedef enum
{
    SWKBD_CALLBACK_OK = 0,   ///< 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.
} SwkbdCallbackResult;
 
/// Keyboard return values.
typedef enum
{
    SWKBD_NONE          = -1, ///< Dummy/unused.
    SWKBD_INVALID_INPUT = -2, ///< Invalid parameters to swkbd.
    SWKBD_OUTOFMEM      = -3, ///< Out of memory.
 
    SWKBD_D0_CLICK = 0, ///< 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 = 10, ///< The HOME button was pressed.
    SWKBD_RESETPRESSED,     ///< The soft-reset key combination was pressed.
    SWKBD_POWERPRESSED,     ///< The POWER button was pressed.
 
    SWKBD_PARENTAL_OK = 20, ///< The parental PIN was verified successfully.
    SWKBD_PARENTAL_FAIL,    ///< The parental PIN was incorrect.
 
    SWKBD_BANNED_INPUT = 30, ///< The filter callback returned SWKBD_CALLBACK_CLOSE.
} SwkbdResult;
 
/// Maximum dictionary word length, in UTF-16 code units.
#define SWKBD_MAX_WORD_LEN         40
/// Maximum button text length, in UTF-16 code units.
#define SWKBD_MAX_BUTTON_TEXT_LEN  16
/// Maximum hint text length, in UTF-16 code units.
#define SWKBD_MAX_HINT_TEXT_LEN    64
/// Maximum filter callback error message length, in UTF-16 code units.
#define SWKBD_MAX_CALLBACK_MSG_LEN 256
 
/// Keyboard dictionary word for predictive input.
typedef struct
{
    u16 reading[SWKBD_MAX_WORD_LEN+1]; ///< Reading of the word (that is, the string that needs to be typed).
    u16 word[SWKBD_MAX_WORD_LEN+1];    ///< Spelling of the word.
    u8 language;                       ///< Language the word applies to.
    bool all_languages;                ///< Specifies if the word applies to all languages.
} SwkbdDictWord;
 
/// Keyboard filter callback function.
typedef SwkbdCallbackResult (* SwkbdCallbackFn)(void* user, const char** ppMessage, const char* text, size_t textlen);
/// Keyboard status data.
typedef struct { u32 data[0x11]; } SwkbdStatusData;
/// Keyboard predictive input learning data.
typedef struct { u32 data[0x291B]; } SwkbdLearningData;
 
/// Internal libctru book-keeping structure for software keyboards.
typedef struct
{
    const char* initial_text;
    const SwkbdDictWord* dict;
    SwkbdStatusData* status_data;
    SwkbdLearningData* learning_data;
    SwkbdCallbackFn callback;
    void* callback_user;
} SwkbdExtra;
 
/// Software keyboard parameter structure, it shouldn't be modified directly.
typedef struct
{
    int type;
    int num_buttons_m1;
    int valid_input;
    int password_mode;
    int is_parental_screen;
    int darken_top_screen;
    u32 filter_flags;
    u32 save_state_flags;
    u16 max_text_len;
    u16 dict_word_count;
    u16 max_digits;
    u16 button_text[3][SWKBD_MAX_BUTTON_TEXT_LEN+1];
    u16 numpad_keys[2];
    u16 hint_text[SWKBD_MAX_HINT_TEXT_LEN+1];
    bool predictive_input;
    bool multiline;
    bool fixed_width;
    bool allow_home;
    bool allow_reset;
    bool allow_power;
    bool unknown; // XX: what is this supposed to do? "communicateWithOtherRegions"
    bool default_qwerty;
    bool button_submits_text[4];
    u16 language; // XX: not working? supposedly 0 = use system language, CFG_Language+1 = pick language
    int initial_text_offset;
    int dict_offset;
    int initial_status_offset;
    int initial_learning_offset;
    size_t shared_memory_size;
    u32 version;
    SwkbdResult result;
    int status_offset;
    int learning_offset;
    int text_offset;
    u16 text_length;
    int callback_result;
    u16 callback_msg[SWKBD_MAX_CALLBACK_MSG_LEN+1];
    bool skip_at_check;
    union
    {
        u8 reserved[171];
        SwkbdExtra extra;
    };
} SwkbdState;
 
/**
 * @brief Initializes software keyboard status.
 * @param swkbd Pointer to swkbd state.
 * @param type Keyboard type.
 * @param numButtons Number of dialog buttons to display (1, 2 or 3).
 * @param maxTextLength Maximum number of UTF-16 code units that input text can have (or -1 to let libctru use a big default).
 */
void swkbdInit(SwkbdState* swkbd, SwkbdType type, int numButtons, int maxTextLength);
 
/**
 * @brief Configures password mode in a software keyboard.
 * @param swkbd Pointer to swkbd state.
 * @param mode Password mode.
 */
static inline void swkbdSetPasswordMode(SwkbdState* swkbd, SwkbdPasswordMode mode)
{
    swkbd->password_mode = mode;
}
 
/**
 * @brief Configures input validation in a software keyboard.
 * @param swkbd Pointer to swkbd state.
 * @param validInput Specifies which inputs are valid.
 * @param filterFlags Bitmask specifying which characters are disallowed (filtered).
 * @param maxDigits In case digits are disallowed, specifies how many digits are allowed at maximum in input strings (0 completely restricts digit input).
 */
static inline void swkbdSetValidation(SwkbdState* swkbd, SwkbdValidInput validInput, u32 filterFlags, int maxDigits)
{
    swkbd->valid_input = validInput;
    swkbd->filter_flags = filterFlags;
    swkbd->max_digits = (filterFlags & SWKBD_FILTER_DIGITS) ? maxDigits : 0;
}
 
/**
 * @brief Configures what characters will the two bottom keys in a numpad produce.
 * @param swkbd Pointer to swkbd state.
 * @param left Unicode codepoint produced by the leftmost key in the bottom row (0 hides the key).
 * @param left Unicode codepoint produced by the rightmost key in the bottom row (0 hides the key).
 */
static inline void swkbdSetNumpadKeys(SwkbdState* swkbd, int left, int right)
{
    swkbd->numpad_keys[0] = left;
    swkbd->numpad_keys[1] = right;
}
 
/**
 * @brief Specifies which special features are enabled in a software keyboard.
 * @param swkbd Pointer to swkbd state.
 * @param features Feature bitmask.
 */
void swkbdSetFeatures(SwkbdState* swkbd, u32 features);
 
/**
 * @brief Sets the hint text of a software keyboard (that is, the help text that is displayed when the textbox is empty).
 * @param swkbd Pointer to swkbd state.
 * @param text Hint text.
 */
void swkbdSetHintText(SwkbdState* swkbd, const char* text);
 
/**
 * @brief Configures a dialog button in a software keyboard.
 * @param swkbd Pointer to swkbd state.
 * @param button Specifies which button to configure.
 * @param text Button text.
 * @param submit Specifies whether pushing the button will submit the text or discard it.
 */
void swkbdSetButton(SwkbdState* swkbd, SwkbdButton button, const char* text, bool submit);
 
/**
 * @brief Sets the initial text that a software keyboard will display on launch.
 * @param swkbd Pointer to swkbd state.
 * @param text Initial text.
 */
void swkbdSetInitialText(SwkbdState* swkbd, const char* text);
 
/**
 * @brief Configures a word in a predictive dictionary for use with a software keyboard.
 * @param word Pointer to dictionary word structure.
 * @param 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.
 * @param text Spelling of the word, that is, the actual characters that will be produced when the user decides to select the word.
 */
void swkbdSetDictWord(SwkbdDictWord* word, const char* reading, const char* text);
 
/**
 * @brief Sets the custom word dictionary to be used with the predictive input system of a software keyboard.
 * @param swkbd Pointer to swkbd state.
 * @param dict Pointer to dictionary words.
 * @param wordCount Number of words in the dictionary.
 */
void swkbdSetDictionary(SwkbdState* swkbd, const SwkbdDictWord* dict, int wordCount);
 
/**
 * @brief Configures software keyboard internal status management.
 * @param swkbd Pointer to swkbd state.
 * @param data Pointer to internal status structure (can be in, out or both depending on the other parameters).
 * @param in Specifies whether the data should be read from the structure when the keyboard is launched.
 * @param out Specifies whether the data should be written to the structure when the keyboard is closed.
 */
void swkbdSetStatusData(SwkbdState* swkbd, SwkbdStatusData* data, bool in, bool out);
 
/**
 * @brief Configures software keyboard predictive input learning data management.
 * @param swkbd Pointer to swkbd state.
 * @param data Pointer to learning data structure (can be in, out or both depending on the other parameters).
 * @param in Specifies whether the data should be read from the structure when the keyboard is launched.
 * @param out Specifies whether the data should be written to the structure when the keyboard is closed.
 */
void swkbdSetLearningData(SwkbdState* swkbd, SwkbdLearningData* data, bool in, bool out);
 
/**
 * @brief Configures a custom function to be used to check the validity of input when it is submitted in a software keyboard.
 * @param swkbd Pointer to swkbd state.
 * @param callback Filter callback function.
 * @param user Custom data to be passed to the callback function.
 */
void swkbdSetFilterCallback(SwkbdState* swkbd, SwkbdCallbackFn callback, void* user);
 
/**
 * @brief Launches a software keyboard in order to input text.
 * @param swkbd Pointer to swkbd state.
 * @param buf Pointer to output buffer which will hold the inputted text.
 * @param bufsize Maximum number of UTF-8 code units that the buffer can hold (including null terminator).
 * @return 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.
 */
SwkbdButton swkbdInputText(SwkbdState* swkbd, char* buf, size_t bufsize);
 
/**
 * @brief Retrieves the result condition of a software keyboard after it has been used.
 * @param swkbd Pointer to swkbd state.
 * @return The result value.
 */
static inline SwkbdResult swkbdGetResult(SwkbdState* swkbd)
{
    return swkbd->result;
}