nn/swkbd/swkbd_Api.h

/*---------------------------------------------------------------------------*

Copyright (C) 2010-2012 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 <cafe/vpad.h>              // The <tt>VPADStatus</tt> structure is defined here.
#include <cafe/pads/kpad/kpad.h>    // The <tt>KPADStatus</tt> structure is defined here.
#include <cafe/fs.h>


/**
@namespace nn
The <tt>nn</tt> namespace.

@namespace nn::swkbd
The <tt>swkbd</tt> namespace.
*/

namespace nn {
//------------------------------------------------------------------------------
namespace swkbd {
//------------------------------------------------------------------------------
/** @defgroup basic_api Basic Software Keyboard (SWKBD) API.
 * @{
 */
/**
 * Initial settings class.
 *
 * Pass as parameters to the <tt>nn::swkbd::Create</tt> function.
 */
class CreateArg
{
public:
    /// Working buffer used by the library.<br/>Allocate and specify a memory region of the size returned by the <tt> nn::swkbd::GetWorkMemorySize</tt> function.
    u8* mBuffer;
    /// Region.<br/>Specify the system region. Defaults to Japan if not specified.
    RegionType mRegion;
    /// Flags specifying the features not to use.<br/>Specify these flags with the <tt>nn::swkbd::LoadOffFlag</tt> 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 <tt>FSAddClient</tt>.
    FSClient* mFSClient;

    /// Constructor.
    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 <tt>nn::swkbd::GetWorkMemorySize</tt> 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 <tt>MEMAllocFromDefaultHeapEx</tt> 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 <tt>GX2Init</tt> in advance for the same reason.
 *
 * The <tt>OSDynLoad_SetAllocator</tt> 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 <tt>CreateThread</tt> in the <i>Cafe SDK API Reference</i>.
 *
 * @param[in] arg  Specifies an argument class.
 *
 * @return Returns <tt>true</tt> 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 <tt>nn::swkbd::LoadOffFlag</tt> bit flag to specify which features not to use.
 * 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 <tt>nn::swkbd::Create</tt> function, the memory allocated from the <tt>MEMAllocFromDefaultHeapEx</tt> 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 <tt>CreateThread</tt> in the <i>Cafe SDK API Reference</i>.
 */
void Destroy();

//------------------------------------------------------------------------------
/**
 * This structure passes controller input to the software keyboard.
 * Pass as parameters to the <tt>nn::swkbd::Calc</tt> function. The <tt>VPAD</tt> / <tt>KPADStatus</tt> structure is maintained by making an internal copy.
 * Because the <tt>VPADGetTPCalibratedPoint</tt> function is not called within the library, pass the values calibrated by the application using data obtained by the <tt>VPADRead</tt> function.
 *
 *
 */
class ControllerInfo
{
public:
    /// Data obtained from <tt>VPADRead</tt>.
    const VPADStatus* mVpadStatus;
    /// Data obtained from <tt>KPADRead</tt>.
    const KPADStatus* mKpadStatus[ WPAD_MAX_CONTROLLERS ];

    /// Constructor.
    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 <tt> demo/swkbd/simple</tt> 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 <tt> demo/swkbd/simple</tt> 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 <tt>nn::swkbd::AppearArg</tt>.
 * For more information about <tt>nn::swkbd::AppearArg</tt>, see the file <tt>swkbd_AppearArg.h</tt>.
 *
 * @param[in] arg  Specifies the class for setting options.
 *
 * @return Returns <tt>true</tt> if the command was accepted.
 * @note The command is not accepted if the state is <tt>nn::swkbd::cState_Appear</tt> or <tt>nn::swkbd::cState_Display</tt>.
 */
bool AppearInputForm( const nn::swkbd::AppearArg& arg );

//------------------------------------------------------------------------------
/**
 * Hides the keyboard that was displaying with the text input form.
 *
 * @return Returns <tt>true</tt> if the command was accepted.
 * @note The command is not accepted if the state is <tt>nn::swkbd::cState_Disappear</tt> or <tt>nn::swkbd::cState_Blank</tt>.
 */
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 <tt>NULL</tt>-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 <span class="argument">nn::swkbd::InputFormArg::mFixedString</span> parameter in <tt>nn::swkbd::AppearArg</tt>.
 *
 * @param[in] str  Specifies the <tt>NULL</tt>-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 <b>Cancel</b> button in the lower left of the keyboard has been pressed.
 *
 * @param[out] by_select_cursor  Returns <tt>true</tt> if confirmed with the selection cursor (a key operation).
 *
 * @return Returns <tt>true</tt> if the <b>Cancel</b> button was pressed.
 *
 * @note If the <span class="argument">by_select_cursor</span> parameter returns <tt>true</tt>, accommodate the continuation of key operations even after the keyboard has been closed.
 */
bool IsDecideCancelButton( bool* by_select_cursor = NULL );

//------------------------------------------------------------------------------
/**
 * Gets whether the <b>OK</b> button in the lower right of the keyboard has been pressed.
 *
 * @param[out] by_select_cursor  Returns <tt>true</tt> if confirmed with the selection cursor (a key operation).
 *
 * @return Returns <tt>true</tt> if the <b>OK</b> button was pressed.
 *
 * @note If the <span class="argument">by_select_cursor</span> parameter returns <tt>true</tt>, accommodate the continuation of key operations even after the keyboard has been closed.
 */
bool IsDecideOkButton( bool* by_select_cursor = NULL );

//------------------------------------------------------------------------------
/**
 * Enables and disables the <b>OK</b> button.
 *
 * If disabled, the <b>OK</b> button is dimmed and can no longer be clicked.
 * Disable the <b>OK</b> 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 If <tt>true</tt>, the <b>OK</b> button is enabled; if <tt>false</tt>, it is disabled.
 */
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 <tt>nn::swkbd::cControllerType_Drc</tt> 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, be sure to use this function to initialize that buffer.
 *
 *
 * Also refer to the <tt>demo/swkbd/predict </tt> sample program included in the package.
 *
 * @param[out] dic_buf  The learning dictionary buffer.
 *
 * @return Returns <tt>true</tt> 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 <tt>demo/swkbd/predict </tt> 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 <tt>demo/swkbd/simple demo/swkbd/predict</tt> sample program included in the package.
 */
void CalcSubThreadFont();

//------------------------------------------------------------------------------
/**
 * Gets whether the predictive text input feature is required.
 *
 * Also refer to the <tt>demo/swkbd/predict </tt> sample program included in the package.
 *
 * @return Indicates 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.
 *
 *
 * Also refer to the <tt>demo/swkbd/predict </tt> sample program included in the package.
 */
void CalcSubThreadPredict();

/** @} */

//------------------------------------------------------------------------------
/** @ingroup controller_event
 *
 * Sets the class for processing controller events.
 *
 * For more information, see <tt>nn::swkbd::IControllerEventObj</tt>.
 *
 * @param[in] p Set to a class that overrides <tt>nn::swkbd::IControllerEventObj</tt>.
 */
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 <tt>nn::swkbd::ISoundObj</tt>.
 */
void SetUserSoundObj( nn::swkbd::ISoundObj* p );

//------------------------------------------------------------------------------
/** @ingroup sound
 * Disables sound processing.
 *
 * @param[in] isMute Mutes if <tt>true</tt>, and unmutes if <tt>false</tt>.
 */
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 <tt>true</tt> if the command was accepted.
 *
 * @note The command is not accepted if the state is <tt>nn::swkbd::cState_Appear</tt> or <tt>nn::swkbd::cState_Display</tt>.
 */
bool AppearKeyboard( const nn::swkbd::KeyboardArg& arg );

//------------------------------------------------------------------------------
/**
 * Hides the keyboard that was shown by <tt>nn::swkbd::AppearKeyboard</tt>.
 *
 * @return Returns <tt>true</tt> if the command was accepted.
 *
 * @note The command is not accepted if the state is <tt>nn::swkbd::cState_Disappear</tt> or <tt>nn::swkbd::cState_Blank</tt>.
 */
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 <tt>nn::swkbd::IEventReceiver</tt> will be the recipient of events during keyboard operation.
 *
 * @param[in] p  The pointer to the class to judge.
 *
 * @return Returns <tt>true</tt> 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 <tt>true</tt> 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 <tt>true</tt> 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 <tt>true</tt> 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 <tt>-1</tt> 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_ */