/*---------------------------------------------------------------------------* Copyright (C) Nintendo. All rights reserved. These coded instructions, statements, and computer programs contain proprietary information of Nintendo of America Inc. and/or Nintendo Company Ltd., and are protected by Federal copyright law. They may not be disclosed to third parties or copied or duplicated in any form, in whole or in part, without the prior written consent of Nintendo. *---------------------------------------------------------------------------*/ //------------------------------------------------------------------------------ /** @file swkbd_Api.h * @brief Software Keyboard Library API Members */ //------------------------------------------------------------------------------ #ifndef NN_SWKBD_H_ #define NN_SWKBD_H_ #include // The VPADStatus structure is defined here. #include // The KPADStatus structure is defined here. #include /** @namespace nn The nn namespace. @namespace nn::swkbd The swkbd namespace. */ namespace nn { //------------------------------------------------------------------------------ namespace swkbd { //------------------------------------------------------------------------------ /** @defgroup basic_api Basic Software Keyboard (SWKBD) API. * @{ */ /** * Initial settings class. * * Pass as parameters to the nn::swkbd::Create function. */ class CreateArg { public: /// Working buffer used by the library.
Allocate and specify a memory region of the size returned by the nn::swkbd::GetWorkMemorySize function. u8* mBuffer; /// Region.
Specify the system region. Defaults to Japan if not specified. RegionType mRegion; /// Flags specifying the features not to use.
Specify these flags with the nn::swkbd::LoadOffFlag bit flag. u32 mLoadOffFlag; /// Specify the file client to use when loading software keyboard resources. For more information, see the SDK file system (FS library) function FSAddClient. FSClient* mFSClient; /// Instantiates an object. CreateArg() : mBuffer( NULL ), mRegion( cRegionType_Jp ), mLoadOffFlag( 0 ), mFSClient( NULL ) { } }; //------------------------------------------------------------------------------ /** * Constructs the software keyboard object. * * You need a working buffer equal in size to the value obtained with the nn::swkbd::GetWorkMemorySize function. * Allocate a buffer of the size obtained and specify it in the parameter. * If you omit this parameter, working memory is allocated using the MEMAllocFromDefaultHeapEx function. * * Nintendo recommends that you call this function in a thread that has lower priority than that of the main thread because files are loaded internally from NAND memory. * The thread that called this function may be referenced while calling other functions. Therefore it should not be destroyed until the keyboard terminates. * * In addition, because GX2 display list operations are performed from inside this function, do not perform GX2 operations in parallel with this function on the same core. * Call GX2Init in advance for the same reason. * * The OSDynLoad_SetAllocator function is also used internally. * Note that if there is already an allocator set by the application, it will be overwritten. * * When specifying cores, call the function with just one core specified. Setting thread affinity to multiple cores and then calling functions from that thread can result in failure. * For more on affinity, see CreateThread in the Cafe SDK API Reference. * * @param[in] arg Specifies an argument class. * * @return Returns true on success. */ bool Create( const CreateArg& arg ); //------------------------------------------------------------------------------ /** * Gets the size of memory required to create the software keyboard object. * * @param[in] load_off_flag Use the nn::swkbd::LoadOffFlag bit flag to specify which features not to use. * @return Returns the memory size (in bytes) required to construct the software keyboard. */ u32 GetWorkMemorySize( u32 load_off_flag = 0 ); //------------------------------------------------------------------------------ /** * Closes the library. * When no parameters were specified for the nn::swkbd::Create function, the memory allocated from the MEMAllocFromDefaultHeapEx function is deallocated within this function. * * When specifying cores, call the function with just one core specified. Setting thread affinity to multiple cores and then calling functions from that thread can result in failure. * For more on affinity, see CreateThread in the Cafe SDK API Reference. */ void Destroy(); //------------------------------------------------------------------------------ /** * This structure passes controller input to the software keyboard. * Pass as parameters to the nn::swkbd::Calc function. * The VPAD / KPADStatus structure is maintained by making an internal copy. * Because the VPADGetTPCalibratedPoint function is not called within the library, pass the values calibrated by the application using data obtained by the VPADRead function. */ class ControllerInfo { public: /// Data obtained from VPADRead. const VPADStatus* mVpadStatus; /// Data obtained from KPADRead. const KPADStatus* mKpadStatus[ WPAD_MAX_CONTROLLERS ]; /// Instantiates an object. ControllerInfo() : mVpadStatus( NULL ) { for( int i = 0; i < WPAD_MAX_CONTROLLERS; ++i ) { mKpadStatus[i] = NULL; } } }; //------------------------------------------------------------------------------ /** * The main software keyboard process. Call this function in every game frame. * * @param[in] controller_info Controller input information. */ void Calc( const nn::swkbd::ControllerInfo& controller_info ); //------------------------------------------------------------------------------ /** * Issues commands for rendering graphics for display on the TV. * The library does not create a frame buffer. * * Also refer to the demo/swkbd/simple sample program included in the package. */ void DrawTV(); //------------------------------------------------------------------------------ /** * Issues commands for rendering graphics for display on the Wii U GamePad (DRC). * The library does not create a frame buffer. * * Also refer to the demo/swkbd/simple sample program included in the package. */ void DrawDRC(); //------------------------------------------------------------------------------ /** * Displays the keyboard with a text input form. * * The keyboard is hidden immediately after initialization. Call this function to display it. * Functionality can be customized by changing the values of nn::swkbd::AppearArg. * For more information about nn::swkbd::AppearArg, see the file swkbd_AppearArg.h. * * @param[in] arg Specifies the class for setting options. * * @return Returns true if the command was accepted. * @note The command is not accepted if the state is nn::swkbd::cState_Appear or nn::swkbd::cState_Display. */ bool AppearInputForm( const nn::swkbd::AppearArg& arg ); //------------------------------------------------------------------------------ /** * Hides the keyboard that was displaying with the text input form. * * @return Returns true if the command was accepted. * @note The command is not accepted if the state is nn::swkbd::cState_Disappear or nn::swkbd::cState_Blank. */ bool DisappearInputForm(); //------------------------------------------------------------------------------ /** * Gets the state of the text input form. * * @return Returns the state of the text input form. */ nn::swkbd::State GetStateInputForm(); //------------------------------------------------------------------------------ /** * Gets the string that was entered in the text input form. * * @return Returns a pointer to a buffer storing the NULL-terminated string. */ const char16* GetInputFormString(); //------------------------------------------------------------------------------ /** * Changes the string entered into the text input form into the specified string. * * Any string already entered is deleted. * Moves the insertion point to the end of the specified string. * If the input form is hidden, use the nn::swkbd::InputFormArg::mFixedString parameter in nn::swkbd::AppearArg. * * @param[in] str Specifies the NULL-terminated string to enter into the text input form. It is handled as a blank string when NULL is specified. * * @note This parameter does not work in the mode for calling the single keyboard. */ void SetInputFormString( const char16* str ); //------------------------------------------------------------------------------ /** * Gets whether the Cancel button in the lower left of the keyboard has been pressed. * * @param[out] by_select_cursor Returns true if confirmed with the selection cursor (a key operation). * * @return Returns true if the Cancel button was pressed. * * @note If the by_select_cursor parameter returns true, accommodate the continuation of key operations even after the keyboard has been closed. */ bool IsDecideCancelButton( bool* by_select_cursor = NULL ); //------------------------------------------------------------------------------ /** * Gets whether the OK button in the lower right of the keyboard has been pressed. * * @param[out] by_select_cursor Returns true if confirmed with the selection cursor (a key operation). * * @return Returns true if the OK button was pressed. * * @note If the by_select_cursor parameter returns true, accommodate the continuation of key operations even after the keyboard has been closed. */ bool IsDecideOkButton( bool* by_select_cursor = NULL ); //------------------------------------------------------------------------------ /** * Enables and disables the OK button. * * If disabled, the OK button is dimmed and can no longer be clicked. * Disable the OK button when the application cannot accept the string being entered, for example when you want to limit the number of characters in a finalized string. * * @param[in] enable Specify true to enable the OK button or false to disable it. */ void SetEnableOkButton( bool enable ); //------------------------------------------------------------------------------ /** * Switches the Wii Remote that can operate the software keyboard. * * Use this function to change the Wii Remote that is doing the operating, for example when the battery has run out in a Wii Remote. * * @param[in] controller_type Specifies the controller type. * * @note This function is only enabled when the Wii Remote has been set for the keyboard that is displaying. * @note It is ignored if nn::swkbd::cControllerType_Drc has been specified. */ void SetControllerRemo( nn::swkbd::ControllerType controller_type ); //------------------------------------------------------------------------------ /** * Initializes the learning dictionary buffer. * * If you are preparing a new learning-dictionary buffer, which you need to enable the predictive text input feature, use this function to initialize that buffer. * * Also refer to the demo/swkbd/predict sample program included in the package. * * @param[out] dic_buf The learning dictionary buffer. * * @return Returns true if initialization is successful. */ bool InitLearnDic( void* dic_buf ); //------------------------------------------------------------------------------ /** * Gets whether the process for generating a font needs to be run. * * Also refer to the demo/swkbd/predict sample program included in the package. * * @return Indicates whether a thread needs to be run. */ bool IsNeedCalcSubThreadFont(); //------------------------------------------------------------------------------ /** * Runs the process to generate a font. Call this function in a subthread. * * Call this function from a thread having higher priority than the predictive text input thread. * This function may be called from the main thread if you are not using a lot of different fonts. * * Also refer to the demo/swkbd/simple demo/swkbd/predict sample program included in the package. */ void CalcSubThreadFont(); //------------------------------------------------------------------------------ /** * Gets whether the predictive text input feature is required. * * For more information, see the demo/swkbd/predict sample program included in the package. * * @return Returns whether a thread needs to be run. */ bool IsNeedCalcSubThreadPredict(); //------------------------------------------------------------------------------ /** * Executes the predictive text input feature. Call this function from a subthread when using the predictive text input feature. * * Resources are loaded internally, so the processing load may increase temporarily. * Call this function from a thread having lower priority than the main thread, as in the sample program. * * For more information, see the demo/swkbd/predict sample program included in the package. */ void CalcSubThreadPredict(); /** @} */ //------------------------------------------------------------------------------ /** @ingroup controller_event * * Sets the class for processing controller events. * * For more information, see nn::swkbd::IControllerEventObj. * * @param[in] p Set to a class that overrides nn::swkbd::IControllerEventObj. */ void SetUserControllerEventObj( nn::swkbd::IControllerEventObj* p ); //------------------------------------------------------------------------------ /** @ingroup sound * * Sets the class for processing sounds. * The default sound is used if this class is not set. * * @param[in] p Set to a class that overrides nn::swkbd::ISoundObj. */ void SetUserSoundObj( nn::swkbd::ISoundObj* p ); //------------------------------------------------------------------------------ /** @ingroup sound * Disables sound processing. * * @param[in] isMute Specify true to mute or false otherwise. */ void MuteAllSound( bool isMute ); //------------------------------------------------------------------------------ /** @defgroup keyboard_single The API for calling a single keyboard. * This feature calls a single keyboard, without an input form. * @{ */ /** * Displays a single keyboard. * * @param[in] arg Specifies the class for setting options. * * @return Returns true if the command was accepted. * * @note The command is not accepted if the state is nn::swkbd::cState_Appear or nn::swkbd::cState_Display. */ bool AppearKeyboard( const nn::swkbd::KeyboardArg& arg ); //------------------------------------------------------------------------------ /** * Hides the keyboard that was shown by nn::swkbd::AppearKeyboard. * * @return Returns true if the command was accepted. * * @note The command is not accepted if the state is nn::swkbd::cState_Disappear or nn::swkbd::cState_Blank. */ bool DisappearKeyboard(); //------------------------------------------------------------------------------ /** * Gets the display state of the single keyboard. * * @return Returns the display state of the single keyboard. */ nn::swkbd::State GetStateKeyboard(); //------------------------------------------------------------------------------ /** * Sets the class for receiving keyboard-operated events and information. * * @param[in] arg Specifies the arguments for receiving keyboard commands. * * @note You need to reconfigure these arguments when text being edited from the application is operated on. */ void SetReceiver( const nn::swkbd::ReceiverArg& arg ); //------------------------------------------------------------------------------ /** * Determines whether the specified nn::swkbd::IEventReceiver will be the recipient of events during keyboard operation. * * @param[in] p The pointer to the class to judge. * * @return Returns true if it is the target for events from the keyboard. */ bool IsKeyboardTarget( nn::swkbd::IEventReceiver* p ); //------------------------------------------------------------------------------ /** * Gets the condition of the keyboard layout (the type of layout selected, and the state of the tabs). * * @param[out] condition The condition of the keyboard layout. */ void GetKeyboardCondition( nn::swkbd::KeyboardCondition* condition ); //------------------------------------------------------------------------------ /** * Determines whether the keyboard is covered by a subwindow. * * Gets whether the keyboard is covered by the window for switching keyboards or some other subwindow. * * @return Returns true if covered. * * @note Ignore user operations of the input form when the single keyboard is called and when the keyboard is being covered by a subwindow. */ bool IsCoveredWithSubWindow(); //------------------------------------------------------------------------------ /** * Determines whether the selection cursor is active. * * @return Returns true if active. * * @note Ignore user operations of the input form (pressing the A Button and the like) when the keyboard is displayed on the TV screen and the selection cursor is active (when the +Control Pad on the Wii Remote is being used for key entry). */ bool IsSelectCursorActive(); //------------------------------------------------------------------------------ /** * Deactivates the selection cursor. * * If the keyboard is displaying on the TV and the selection cursor is active, calling this function deactivates it. * * @return Returns true if active. */ void InactivateSelectCursor(); //------------------------------------------------------------------------------ /** * Confirms unfixed text. * * Use this function to confirm unfixed text, for example when the user touches an entry field and forces the cursor to move. */ void ConfirmUnfixAll(); //------------------------------------------------------------------------------ /** * Gets information for rendering text, such as information for drawing in an unconfirmed range. * * @param[out] info Rendering information. */ void GetDrawStringInfo( nn::swkbd::DrawStringInfo* info ); //------------------------------------------------------------------------------ /** * Sets the cursor position. * * Use this function to notify the keyboard of the cursor position when the cursor is moved in an input form. * * @param[in] pos The cursor position. */ void SetCursorPos( s32 pos ); //------------------------------------------------------------------------------ /** * Sets the starting position for character selection. * * Use this function to notify the keyboard of the starting position for character selection when the cursor is moved. * Specify –1 if text is not selected. * * @param[in] from The starting position for character selection. */ void SetSelectFrom( s32 from ); /** @} */ //------------------------------------------------------------------------------ } // namespace swkbd //------------------------------------------------------------------------------ } // namespace nn #endif /* NN_SWKBD_H_ */