nn::swkbd::CTR::Config Structure

struct Config
{
KeyboardType keyboardType;
BottomButtonType bottomButtonType;
FinishableCondition finishableCondition;
MaskMode maskMode;
ParentalControlsMode parentalControlsMode;
bit32 upperScreenFlag;
bit32 textCheckFlag;
bit32 extOutputDataFlag;
u16 textLengthMax;
u16 numUserWords;
u16 numNumbersMax;
wchar_t bottomButtonText[BOTTOM_BUTTON_MAX][BOTTOM_BUTTON_TEXT_LENGTH_MAX+1];
wchar_t tenkeyExtKeyChar[TENKEY_EXT_KEY_MAX];
wchar_t guideText[GUIDE_TEXT_LENGTH_MAX+1];
bool prediction;
bool lineFeed;
bool fixedWidthMode;
bool homeButton;
bool softwareReset;
bool powerButton;
bool communicateWithOtherRegions;
bool bootWithQwerty;
bool bottomButtonToFinish[BOTTOM_BUTTON_MAX];
DisplayLanguage displayLanguage;
sptr initialInputText;
sptr userWordArray;
sptr initialStatusData;
sptr initialLearningData;
size_t sharedMemorySize;
u16 versionNumber;
ReturnCode returnCode;
sptr statusData;
sptr learningData;
sptr inputText;
u16 inputTextLength;
AppTextCheckResult appTextCheckResult;
wchar_t appTextCheckDialogText[APP_TEXT_CHECK_DIALOG_TEXT_LENGTH_MAX+1];
bool skipAtMarkCheck;
u8 reserved[171];
};

Configuration structure.

This structure is exchanged between the application and the software keyboard applet and stores various data.

Input Parameters Passed to the Applet

In addition to parameters that specify the behavior of the software keyboard, this structure also stores information about the text entered by the user.

You must always call the nn::swkbd::CTR::InitializeConfig function to initialize this structure before setting its member variables.
However, the only member variables whose values you can set directly are the ones classified on this page as Input (Direct Setting Possible). Changing the values of the other member variables might cause a malfunction.

Details of Input Members

keyboardType

Use the nn::swkbd::CTR::KeyboardType enumerated type to specify the type of keyboard you want to use. If you specify any value other than KEYBOARD_TYPE_FULL, predictive text is not available. If you specify KEYBOARD_TYPE_TENKEY, newlines are also disabled.

bottomButtonType

Use the nn::swkbd::CTR::BottomButtonType enumerated type to specify the type of the bottom-row buttons (the buttons laid out along the lowest edge of the screen).

finishableCondition

Use the nn::swkbd::CTR::FinishableCondition enumerated type to specify the conditions that must be met for users to finalize their text input. Users cannot finalize any text input unless they meet these conditions.

maskMode

Use the nn::swkbd::CTR::MaskMode enumerated type to specify the method to use when masking user-entered content.
When you specify any value other than MASK_MODE_DISABLE, user-entered characters are replaced with asterisks (*) using the specified method. Newlines, however, are not replaced.

parentalControlsMode

Use the nn::swkbd::CTR::ParentalControlsMode enumerated type to specify whether to start the software keyboard in a special format that allows the user to temporarily disable Parental Controls.
When you specify any value other than PARENTAL_CONTROLS_MODE_DISABLE, the settings of all the other member variables except upperScreenFlag, homeButton, and softwareReset are ignored.

upperScreenFlag

Use a bitwise OR of the nn::swkbd::CTR::UpperScreenFlag enumerated type flags to specify how to display the upper screen.

textCheckFlag

Use a bitwise OR of the nn::swkbd::CTR::TextCheckFlag enumerated type flags to specify the types of text checks you want to perform while the software keyboard is running.
When you specify any value other than TEXT_CHECK_DISABLE, the value set in the textLengthMax member variable is clamped so as not to exceed nn::swkbd::CTR::TEXT_CHECK_TEXT_LENGTH_MAX_MAX. If you specify TEXT_CHECK_BANNED_WORDS, the value set in the textLengthMax member variable is clamped so as not to exceed nn::swkbd::CTR::BANNED_WORD_CHECK_TEXT_LENGTH_MAX_MAX and newlines are disabled.

extOutputDataFlag

Use a bitwise OR of the nn::swkbd::CTR::ExtOutputDataFlag enumerated type flags to specify the types of any data you want to output in addition to the user-entered text and the return code.

numUserWords

Specify the number of elements in the nn::swkbd::CTR::UserWord structure array to pass as an argument to the nn::swkbd::CTR::StartKeyboardApplet function.
If using user dictionaries, always set an appropriate value here.

numNumbersMax

Specify the maximum number of numbers that users can input when TEXT_CHECK_NUMBER is set in the textCheckFlag member variable and you want to restrict numerical input.
Specify 0 to completely prohibit the input of numbers.
When TEXT_CHECK_NUMBER is not set in the textCheckFlag member variable, this member variable's setting is ignored.

bottomButtonText

Specify a null-terminated string for the text to display on the bottom-row buttons.
Use the nn::swkbd::CTR::BottomButton enumerated type to specify the primary index of the array. If you specify an empty string, the default text for the system's region and language settings will be used.

tenkeyExtKeyChar

Specify the characters to assign to the keys placed to the immediate left and right of the 0 key on the numeric keypad.
Use the nn::swkbd::CTR::TenkeyExtKey enumerated type to specify the index of the array.
Basically, the characters you specify are displayed unchanged on the keys, but there is an exception: if you specify a single-byte space (0x0020) a special extended character is displayed on the key.
You cannot specify any of the control characters from 0x0001 to 0x001F. If you specify a null character, that key is not displayed.

guideText

Specify a null-terminated string to serve as guide text (the text displayed in an input field before the user enters any characters in that field).
Note that guide text is not displayed when true is specified for the fixedWih3hMode member variable, causing the keyboard to start in fixed-width display mode.

fixedWih3hMode

Specify whether to start the software keyboard in fixed-width display mode.
If you specify true, the keyboard starts in fixed-width display mode. Entered text is displayed as fixed-width and the number of characters that can be input is visible. In addition, the value set in the textLengthMax member variable is clamped so as not to exceed nn::swkbd::CTR::FIXED_WIDTH_TEXT_LENGTH_MAX_MAX and newlines are disabled.

homeButton

Specify whether to end the software keyboard when HOME is pressed.
When you specify true, the software keyboard ends and outputs any existing user-entered text when HOME is pressed.
Note: When the keyboard ends this way, the output text does not undergo any of the text checks specified by the textCheckFlag member variable. Be careful about using such unchecked text.

softwareReset

Specify whether to enable software resets.
When you specify true, the software keyboard ends when the button combination for a software reset is pressed.

powerButton

Specify whether to end the software keyboard when the POWER button is pressed.
In general, do not change this from the default value of true.

communicateWithOtherRegions

Specify whether the application exchanges data with other regions.
When TEXT_CHECK_BANNED_WORDS is set in the textCheckFlag member variable, the text patterns that are checked for are changed as a result of this member variable's setting.
When TEXT_CHECK_BANNED_WORDS is not set in the textCheckFlag member variable, this member variable's setting is ignored. This variable is not currently accessed.

bootWithQwerty

Specify whether to forcibly set the key layout to the QWERTY layout at startup.
When you specify false, the key layout selected at startup differs depending on the language setting.
Specifically, the layout is kana for Japanese, Cyrillic for Russian, and QWERTY for all other languages.
This member variable's setting is ignored, however, when you specify any value other than KEYBOARD_TYPE_FULL for the KeyboardType member variable, or when the initial operating status data is passed as an argument to the nn::swkbd::CTR::StartKeyboardApplet function.

bottomButtonToFinish

Specify which of the bottom-row buttons is the OK button (the button the user presses to finalize input).
Use the nn::swkbd::CTR::BottomButton enumerated type to specify the index in the array, and specify true to make that button the OK button.
The bottom-row button specified as the OK button is not tappable until the conditions for finalizing input (specified in the finishableCondition member variable) are met.

displayLanguage

Use the nn::swkbd::CTR::DisplayLanguage enumerated type to specify which language to use when displaying various text on the software keyboard.
The keyboard layout and the scope of available characters will change based on the language set here. If the default value (DISPLAY_LANGUAGE_DEFAULT) is specified, the language specified in the System Settings is used. If a language that cannot be specified in System Settings is specified here, Japanese will be assumed for systems whose system region is Japan, and English will be assumed for systems whose system region is the Americas or Europe.

Output Parameters Received from the Applet

The data output when the software keyboard ends can be obtained by checking the values of the member variables classified as Output in the Member Variables section of this page.
Any comparatively large data items are stored in the shared memory that was passed as an argument to the nn::swkbd::CTR::StartKeyboardApplet function. The starting addresses of the data items are stored in the output member variables of this structure as offsets from the start of shared memory. Obtain the data by referencing those values.

Details of Output Members

returnCode

Stores the return code that indicates the reason why the software keyboard ended.
Among these codes are codes indicating that the POWER Button or the HOME Button was pressed, but those codes alone do not allow you to determine whether to call the nn::applet::CTR::ProcessPowerButton or nn::applet::CTR::ProcessHomeButton function.
To determine whether it is necessary to call those functions, you must call the nn::applet::CTR::IsExpectedToProcessPowerButton and nn::applet::CTR::IsExpectedToProcessHomeButton functions.

statusData

Stores the starting address of the operating status data describing the software keyboard's status when it ended. (This address is stored as an offset from the start of the shared memory region.)
A value of -1 is stored when EXT_OUTPUT_DATA_STATUS was not set in the extOutputDataFlag member variable of this structure when the software keyboard was started.
The size of the data is defined by nn::swkbd::CTR::STATUS_DATA_SIZE.
If you pass this data as an argument to the nn::swkbd::CTR::StartKeyboardApplet function the next time the software keyboard is started, you can carry over the keyboard's operating status from the previous time it was used.

learningData

Stores the starting address of the predictive text learning data from when the software keyboard ended. (This address is stored as an offset from the start of the shared memory region.)
A value of -1 is stored when EXT_OUTPUT_DATA_LEARNING was not set in the extOutputDataFlag member variable of this structure when the software keyboard was started.
The size of the data is defined by nn::swkbd::CTR::LEARNING_DATA_SIZE.
If you pass this data as an argument to the nn::swkbd::CTR::StartKeyboardApplet function the next time the software keyboard is started, you can carry over the keyboard's learning status from the previous time it was used.

inputText

Stores the starting address of the user-entered string. (This address is stored as an offset from the start of the shared memory region.)
Strings are of the wchar_t type and are null-terminated. A value of -1 is stored if the software keyboard was closed without input being finalized.

inputTextLength

Stores the length of the user-entered string. The null terminator is not included in this length.

2011/10/13

Noted that the communicateWithOtherRegions variable is not currently accessed.

2011/09/01

Revised the appearance of the Description.

2011/08/05

Added the member variables displayLanguage and skipAtMarkCheck.

2011/03/18

Added note to description of the bottomButtonText member variable that the default text will be used based on the system's region and language settings.

2011/03/01

Initial version.