Struct ctru::applets::swkbd::SoftwareKeyboard

pub struct SoftwareKeyboard { /* private fields */ }

Configuration structure to setup the Software Keyboard applet.

Implementations

impl SoftwareKeyboard

pub fn new(keyboard_type: Kind, buttons: ButtonConfig) -> Self

Initialize a new configuration for the Software Keyboard applet depending on how many “exit” buttons are available to the user (1, 2 or 3).

Example

use ctru::applets::swkbd::{SoftwareKeyboard, ButtonConfig, Kind};

// Standard keyboard. Equivalent to `SoftwareKeyboard::default()`.
let keyboard = SoftwareKeyboard::new(Kind::Normal, ButtonConfig::LeftRight);

// Numpad (with only the "confirm" button).
let keyboard = SoftwareKeyboard::new(Kind::Numpad, ButtonConfig::Right);

pub fn launch( &mut self, apt: &Apt, gfx: &Gfx ) -> Result<(String, Button), Error>

Launches the applet based on the given configuration and returns a string containing the text input.

Example

use ctru::applets::swkbd::SoftwareKeyboard;
let mut keyboard = SoftwareKeyboard::default();

let (text, button) = keyboard.launch(&apt, &gfx)?;

pub fn set_features(&mut self, features: Features)

Set special features for this keyboard.

Example

use ctru::applets::swkbd::{SoftwareKeyboard, Features};

let mut keyboard = SoftwareKeyboard::default();

let features = Features::DARKEN_TOP_SCREEN & Features::MULTILINE;
keyboard.set_features(features);

pub fn set_validation(&mut self, validation: ValidInput, filters: Filters)

Configure input validation for this keyboard.

Example

use ctru::applets::swkbd::{SoftwareKeyboard, ValidInput, Filters};
let mut keyboard = SoftwareKeyboard::default();

// Disallow empty or blank input.
let validation = ValidInput::NotEmptyNotBlank;

// Disallow the use of numerical digits and profanity.
let filters = Filters::DIGITS & Filters::PROFANITY;
keyboard.set_validation(validation, filters);

pub fn set_filter_callback( &mut self, callback: Option<Box<dyn Fn(&str) -> (CallbackResult, Option<Cow<'static, str>>)>> )

Configure a custom filtering function to validate the input.

The callback function must return a CallbackResult and the error message to display when the input is invalid.

Notes

Passing [None] will unbind the custom filter callback.

The error message returned by the callback should be shorter than 256 characters, otherwise it will be truncated.

Example

use std::borrow::Cow;
use ctru::applets::swkbd::{SoftwareKeyboard, CallbackResult};

let mut keyboard = SoftwareKeyboard::default();

keyboard.set_filter_callback(Some(Box::new(move |str| {
    if str.contains("boo") {
        return (CallbackResult::Retry, Some("Ah, you scared me!".into()));
    }

    (CallbackResult::Ok, None)
})));

pub fn set_max_digits(&mut self, digits: u16)

Configure the maximum number of digits that can be entered in the keyboard when the Filters::DIGITS flag is enabled.

Example

use ctru::applets::swkbd::{SoftwareKeyboard, ValidInput, Filters};
let mut keyboard = SoftwareKeyboard::default();

// Disallow empty or blank input.
let validation = ValidInput::NotEmptyNotBlank;

// Disallow the use of numerical digits. This filter is customizable thanks to `set_max_digits`.
let filters = Filters::DIGITS;
keyboard.set_validation(validation, filters);

// No more than 3 numbers are accepted.
keyboard.set_max_digits(3);

pub fn set_initial_text(&mut self, text: Option<Cow<'static, str>>)

Set the initial text for this software keyboard.

The initial text is the text already written when you open the software keyboard.

Notes

Passing [None] will clear the initial text.

Example

use ctru::applets::swkbd::SoftwareKeyboard;
let mut keyboard = SoftwareKeyboard::default();

keyboard.set_initial_text(Some("Write here what you like!".into()));

pub fn set_hint_text(&mut self, text: Option<&str>)

Set the hint text for this software keyboard.

The hint text is the text shown in gray before any text gets written in the input box.

Notes

Passing [None] will clear the hint text.

The hint text will be converted to UTF-16 when passed to the software keyboard, and the text will be truncated if the length exceeds 64 code units after conversion.

Example

use ctru::applets::swkbd::SoftwareKeyboard;
let mut keyboard = SoftwareKeyboard::default();

keyboard.set_hint_text(Some("Write here what you like!"));

pub fn set_password_mode(&mut self, mode: PasswordMode)

Set a password mode for this software keyboard.

Depending on the selected mode the input text will be concealed.

Example

use ctru::applets::swkbd::{SoftwareKeyboard, PasswordMode};
let mut keyboard = SoftwareKeyboard::default();

keyboard.set_password_mode(PasswordMode::Hide);

pub fn set_numpad_keys( &mut self, left_key: Option<char>, right_key: Option<char> )

Set the 2 custom characters to add to the keyboard while using Kind::Numpad.

These characters will appear in their own buttons right next to the 0 key.

Notes

If [None] is passed as either key, that button will not be shown to the user.

Example

use ctru::applets::swkbd::{SoftwareKeyboard, Kind, ButtonConfig};
let mut keyboard = SoftwareKeyboard::new(Kind::Numpad, ButtonConfig::LeftRight);

keyboard.set_numpad_keys(Some('#'), Some('.'));

// The right numpad key will not be shown.
keyboard.set_numpad_keys(Some('!'), None);

pub fn configure_button(&mut self, button: Button, text: &str, submit: bool)

Configure the look and behavior of a button for this keyboard.

Arguments

• button - the Button to be configured based on the position.
• text - the text displayed in the button.
• submit - whether pressing the button will accept the keyboard’s input or discard it.

Example

use ctru::applets::swkbd::{SoftwareKeyboard, Button, ButtonConfig, Kind};

// We create a `SoftwareKeyboard` with left and right buttons.
let mut keyboard = SoftwareKeyboard::new(Kind::Normal, ButtonConfig::LeftRight);

// Set the left button text to "Cancel" and pressing it will NOT return the user's input.
keyboard.configure_button(Button::Left, "Cancel", false);

// Set the right button text to "Ok" and pressing it will return the user's input.
keyboard.configure_button(Button::Right, "Ok", true);

pub fn set_max_text_len(&mut self, len: u16)

Configure the maximum number of UTF-16 code units that can be entered into the software keyboard. By default the limit is 65000 code units.

Notes

This action will overwrite any previously submitted ValidInput validation.

Keyboard input is converted from UTF-16 to UTF-8 before being handed to Rust, so this code point limit does not necessarily equal the max number of UTF-8 code points receivable by SoftwareKeyboard::launch().

Example

use ctru::applets::swkbd::{SoftwareKeyboard, Button, Kind};
let mut keyboard = SoftwareKeyboard::default();

// Set the maximum text length to 18 UTF-16 code units.
keyboard.set_max_text_len(18);

Trait Implementations

impl Default for SoftwareKeyboard

Creates a new SoftwareKeyboard configuration set to using a Kind::Normal keyboard and 2 Buttons.

fn default() -> Self

Returns the “default value” for a type.