1 /*---------------------------------------------------------------------------* 2 3 Copyright (C) 2010-2012 Nintendo. All rights reserved. 4 5 These coded instructions, statements, and computer programs contain 6 proprietary information of Nintendo of America Inc. and/or Nintendo 7 Company Ltd., and are protected by Federal copyright law. They may 8 not be disclosed to third parties or copied or duplicated in any form, 9 in whole or in part, without the prior written consent of Nintendo. 10 11 *---------------------------------------------------------------------------*/ 12 13 //------------------------------------------------------------------------------ 14 /** @file swkbd_Api.h 15 * @brief Software Keyboard Library API Members 16 */ 17 //------------------------------------------------------------------------------ 18 #ifndef NN_SWKBD_H_ 19 #define NN_SWKBD_H_ 20 21 #include <cafe/vpad.h> // The <tt>VPADStatus</tt> structure is defined here. 22 #include <cafe/pads/kpad/kpad.h> // The <tt>KPADStatus</tt> structure is defined here. 23 #include <cafe/fs.h> 24 25 26 /** 27 @namespace nn 28 The <tt>nn</tt> namespace. 29 30 @namespace nn::swkbd 31 The <tt>swkbd</tt> namespace. 32 */ 33 34 namespace nn { 35 //------------------------------------------------------------------------------ 36 namespace swkbd { 37 //------------------------------------------------------------------------------ 38 /** @defgroup basic_api Basic Software Keyboard (SWKBD) API. 39 * @{ 40 */ 41 /** 42 * Initial settings class. 43 * 44 * Pass as parameters to the <tt>nn::swkbd::Create</tt> function. 45 */ 46 class CreateArg 47 { 48 public: 49 /// 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. 50 u8* mBuffer; 51 /// Region.<br/>Specify the system region. Defaults to Japan if not specified. 52 RegionType mRegion; 53 /// Flags specifying the features not to use.<br/>Specify these flags with the <tt>nn::swkbd::LoadOffFlag</tt> bit flag. 54 u32 mLoadOffFlag; 55 /// 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>. 56 FSClient* mFSClient; 57 58 /// Constructor. CreateArg()59 CreateArg() : mBuffer( NULL ), mRegion( cRegionType_Jp ), mLoadOffFlag( 0 ), mFSClient( NULL ) 60 { 61 } 62 }; 63 64 //------------------------------------------------------------------------------ 65 /** 66 * Constructs the software keyboard object. 67 * 68 * You need a working buffer equal in size to the value obtained with the <tt>nn::swkbd::GetWorkMemorySize</tt> function. 69 * 70 * Allocate a buffer of the size obtained and specify it in the parameter. 71 * If you omit this parameter, working memory is allocated using the <tt>MEMAllocFromDefaultHeapEx</tt> function. 72 * 73 * 74 * 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. 75 * The thread that called this function may be referenced while calling other functions. Therefore it should not be destroyed until the keyboard terminates. 76 * 77 * 78 * 79 * 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. 80 * 81 * Call <tt>GX2Init</tt> in advance for the same reason. 82 * 83 * The <tt>OSDynLoad_SetAllocator</tt> function is also used internally. 84 * Note that if there is already an allocator set by the application, it will be overwritten. 85 * 86 * 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. 87 * 88 * For more on affinity, see <tt>CreateThread</tt> in the <i>Cafe SDK API Reference</i>. 89 * 90 * @param[in] arg Specifies an argument class. 91 * 92 * @return Returns <tt>true</tt> on success. 93 */ 94 bool Create( const CreateArg& arg ); 95 96 //------------------------------------------------------------------------------ 97 /** 98 * Gets the size of memory required to create the software keyboard object. 99 * 100 * @param[in] load_off_flag Use the <tt>nn::swkbd::LoadOffFlag</tt> bit flag to specify which features not to use. 101 * The memory size (in bytes) required to construct the software keyboard. 102 */ 103 u32 GetWorkMemorySize( u32 load_off_flag = 0 ); 104 105 //------------------------------------------------------------------------------ 106 /** 107 * Closes the library. 108 * 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. 109 * 110 * 111 * 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. 112 * 113 * For more on affinity, see <tt>CreateThread</tt> in the <i>Cafe SDK API Reference</i>. 114 */ 115 void Destroy(); 116 117 //------------------------------------------------------------------------------ 118 /** 119 * This structure passes controller input to the software keyboard. 120 * 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. 121 * 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. 122 * 123 * 124 */ 125 class ControllerInfo 126 { 127 public: 128 /// Data obtained from <tt>VPADRead</tt>. 129 const VPADStatus* mVpadStatus; 130 /// Data obtained from <tt>KPADRead</tt>. 131 const KPADStatus* mKpadStatus[ WPAD_MAX_CONTROLLERS ]; 132 133 /// Constructor. ControllerInfo()134 ControllerInfo() : mVpadStatus( NULL ) 135 { 136 for( int i = 0; i < WPAD_MAX_CONTROLLERS; ++i ) 137 { 138 mKpadStatus[i] = NULL; 139 } 140 } 141 }; 142 143 //------------------------------------------------------------------------------ 144 /** 145 * The main software keyboard process. Call this function in every game frame. 146 * 147 * @param[in] controller_info Controller input information. 148 */ 149 void Calc( const nn::swkbd::ControllerInfo& controller_info ); 150 151 //------------------------------------------------------------------------------ 152 /** 153 * Issues commands for rendering graphics for display on the TV. 154 * The library does not create a frame buffer. 155 * 156 * Also refer to the <tt> demo/swkbd/simple</tt> sample program included in the package. 157 */ 158 void DrawTV(); 159 160 //------------------------------------------------------------------------------ 161 /** 162 * Issues commands for rendering graphics for display on the Wii U GamePad (DRC). 163 * The library does not create a frame buffer. 164 * 165 * Also refer to the <tt> demo/swkbd/simple</tt> sample program included in the package. 166 */ 167 void DrawDRC(); 168 169 //------------------------------------------------------------------------------ 170 /** 171 * Displays the keyboard with a text input form. 172 * 173 * The keyboard is hidden immediately after initialization. Call this function to display it. 174 * Functionality can be customized by changing the values of <tt>nn::swkbd::AppearArg</tt>. 175 * For more information about <tt>nn::swkbd::AppearArg</tt>, see the file <tt>swkbd_AppearArg.h</tt>. 176 * 177 * @param[in] arg Specifies the class for setting options. 178 * 179 * @return Returns <tt>true</tt> if the command was accepted. 180 * @note The command is not accepted if the state is <tt>nn::swkbd::cState_Appear</tt> or <tt>nn::swkbd::cState_Display</tt>. 181 */ 182 bool AppearInputForm( const nn::swkbd::AppearArg& arg ); 183 184 //------------------------------------------------------------------------------ 185 /** 186 * Hides the keyboard that was displaying with the text input form. 187 * 188 * @return Returns <tt>true</tt> if the command was accepted. 189 * @note The command is not accepted if the state is <tt>nn::swkbd::cState_Disappear</tt> or <tt>nn::swkbd::cState_Blank</tt>. 190 */ 191 bool DisappearInputForm(); 192 193 //------------------------------------------------------------------------------ 194 /** 195 * Gets the state of the text input form. 196 * 197 * @return Returns the state of the text input form. 198 */ 199 nn::swkbd::State GetStateInputForm(); 200 201 //------------------------------------------------------------------------------ 202 /** 203 * Gets the string that was entered in the text input form. 204 * 205 * @return Returns a pointer to a buffer storing the <tt>NULL</tt>-terminated string. 206 */ 207 const char16* GetInputFormString(); 208 209 //------------------------------------------------------------------------------ 210 /** 211 * Changes the string entered into the text input form into the specified string. 212 * 213 * Any string already entered is deleted. 214 * Moves the insertion point to the end of the specified string. 215 * If the input form is hidden, use the <span class="argument">nn::swkbd::InputFormArg::mFixedString</span> parameter in <tt>nn::swkbd::AppearArg</tt>. 216 * 217 * @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. 218 * 219 * @note This parameter does not work in the mode for calling the single keyboard. 220 */ 221 void SetInputFormString( const char16* str ); 222 223 //------------------------------------------------------------------------------ 224 /** 225 * Gets whether the <b>Cancel</b> button in the lower left of the keyboard has been pressed. 226 * 227 * @param[out] by_select_cursor Returns <tt>true</tt> if confirmed with the selection cursor (a key operation). 228 * 229 * @return Returns <tt>true</tt> if the <b>Cancel</b> button was pressed. 230 * 231 * @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. 232 */ 233 bool IsDecideCancelButton( bool* by_select_cursor = NULL ); 234 235 //------------------------------------------------------------------------------ 236 /** 237 * Gets whether the <b>OK</b> button in the lower right of the keyboard has been pressed. 238 * 239 * @param[out] by_select_cursor Returns <tt>true</tt> if confirmed with the selection cursor (a key operation). 240 * 241 * @return Returns <tt>true</tt> if the <b>OK</b> button was pressed. 242 * 243 * @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. 244 */ 245 bool IsDecideOkButton( bool* by_select_cursor = NULL ); 246 247 //------------------------------------------------------------------------------ 248 /** 249 * Enables and disables the <b>OK</b> button. 250 * 251 * If disabled, the <b>OK</b> button is dimmed and can no longer be clicked. 252 * 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. 253 * 254 * @param[in] enable If <tt>true</tt>, the <b>OK</b> button is enabled; if <tt>false</tt>, it is disabled. 255 */ 256 void SetEnableOkButton( bool enable ); 257 258 //------------------------------------------------------------------------------ 259 /** 260 * Switches the Wii Remote that can operate the software keyboard. 261 * 262 * 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. 263 * 264 * @param[in] controller_type Specifies the controller type. 265 * 266 * @note This function is only enabled when the Wii Remote has been set for the keyboard that is displaying. 267 * @note It is ignored if <tt>nn::swkbd::cControllerType_Drc</tt> has been specified. 268 */ 269 void SetControllerRemo( nn::swkbd::ControllerType controller_type ); 270 271 //------------------------------------------------------------------------------ 272 /** 273 * Initializes the learning dictionary buffer. 274 * 275 * 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. 276 * 277 * 278 * Also refer to the <tt>demo/swkbd/predict </tt> sample program included in the package. 279 * 280 * @param[out] dic_buf The learning dictionary buffer. 281 * 282 * @return Returns <tt>true</tt> if initialization is successful. 283 */ 284 bool InitLearnDic( void* dic_buf ); 285 286 //------------------------------------------------------------------------------ 287 /** 288 * Gets whether the process for generating a font needs to be run. 289 * 290 * Also refer to the <tt>demo/swkbd/predict </tt> sample program included in the package. 291 * 292 * @return Indicates whether a thread needs to be run. 293 */ 294 bool IsNeedCalcSubThreadFont(); 295 296 //------------------------------------------------------------------------------ 297 /** 298 * Runs the process to generate a font. Call this function in a subthread. 299 * 300 * Call this function from a thread having higher priority than the predictive text input thread. 301 * This function may be called from the main thread if you are not using a lot of different fonts. 302 * 303 * Also refer to the <tt>demo/swkbd/simple demo/swkbd/predict</tt> sample program included in the package. 304 */ 305 void CalcSubThreadFont(); 306 307 //------------------------------------------------------------------------------ 308 /** 309 * Gets whether the predictive text input feature is required. 310 * 311 * Also refer to the <tt>demo/swkbd/predict </tt> sample program included in the package. 312 * 313 * @return Indicates whether a thread needs to be run. 314 */ 315 bool IsNeedCalcSubThreadPredict(); 316 317 //------------------------------------------------------------------------------ 318 /** 319 * Executes the predictive text input feature. Call this function from a subthread when using the predictive text input feature. 320 * 321 * Resources are loaded internally, so the processing load may increase temporarily. 322 * Call this function from a thread having lower priority than the main thread, as in the sample program. 323 * 324 * 325 * Also refer to the <tt>demo/swkbd/predict </tt> sample program included in the package. 326 */ 327 void CalcSubThreadPredict(); 328 329 /** @} */ 330 331 //------------------------------------------------------------------------------ 332 /** @ingroup controller_event 333 * 334 * Sets the class for processing controller events. 335 * 336 * For more information, see <tt>nn::swkbd::IControllerEventObj</tt>. 337 * 338 * @param[in] p Set to a class that overrides <tt>nn::swkbd::IControllerEventObj</tt>. 339 */ 340 void SetUserControllerEventObj( nn::swkbd::IControllerEventObj* p ); 341 342 //------------------------------------------------------------------------------ 343 /** @ingroup sound 344 * 345 * Sets the class for processing sounds. 346 * The default sound is used if this class is not set. 347 * 348 * @param[in] p Set to a class that overrides <tt>nn::swkbd::ISoundObj</tt>. 349 */ 350 void SetUserSoundObj( nn::swkbd::ISoundObj* p ); 351 352 //------------------------------------------------------------------------------ 353 /** @ingroup sound 354 * Disables sound processing. 355 * 356 * @param[in] isMute Mutes if <tt>true</tt>, and unmutes if <tt>false</tt>. 357 */ 358 void MuteAllSound( bool isMute ); 359 360 //------------------------------------------------------------------------------ 361 /** @defgroup keyboard_single The API for calling a single keyboard. 362 * This feature calls a single keyboard, without an input form. 363 * @{ 364 */ 365 /** 366 * Displays a single keyboard. 367 * 368 * @param[in] arg Specifies the class for setting options. 369 * 370 * @return Returns <tt>true</tt> if the command was accepted. 371 * 372 * @note The command is not accepted if the state is <tt>nn::swkbd::cState_Appear</tt> or <tt>nn::swkbd::cState_Display</tt>. 373 */ 374 bool AppearKeyboard( const nn::swkbd::KeyboardArg& arg ); 375 376 //------------------------------------------------------------------------------ 377 /** 378 * Hides the keyboard that was shown by <tt>nn::swkbd::AppearKeyboard</tt>. 379 * 380 * @return Returns <tt>true</tt> if the command was accepted. 381 * 382 * @note The command is not accepted if the state is <tt>nn::swkbd::cState_Disappear</tt> or <tt>nn::swkbd::cState_Blank</tt>. 383 */ 384 bool DisappearKeyboard(); 385 386 //------------------------------------------------------------------------------ 387 /** 388 * Gets the display state of the single keyboard. 389 * 390 * @return Returns the display state of the single keyboard. 391 */ 392 nn::swkbd::State GetStateKeyboard(); 393 394 //------------------------------------------------------------------------------ 395 /** 396 * Sets the class for receiving keyboard-operated events and information. 397 * 398 * @param[in] arg Specifies the arguments for receiving keyboard commands. 399 * 400 * @note You need to reconfigure these arguments when text being edited from the application is operated on. 401 */ 402 void SetReceiver( const nn::swkbd::ReceiverArg& arg ); 403 404 //------------------------------------------------------------------------------ 405 /** 406 * Determines whether the specified <tt>nn::swkbd::IEventReceiver</tt> will be the recipient of events during keyboard operation. 407 * 408 * @param[in] p The pointer to the class to judge. 409 * 410 * @return Returns <tt>true</tt> if it is the target for events from the keyboard. 411 */ 412 bool IsKeyboardTarget( nn::swkbd::IEventReceiver* p ); 413 414 //------------------------------------------------------------------------------ 415 /** 416 * Gets the condition of the keyboard layout (the type of layout selected, and the state of the tabs). 417 * 418 * @param[out] condition The condition of the keyboard layout. 419 */ 420 void GetKeyboardCondition( nn::swkbd::KeyboardCondition* condition ); 421 422 //------------------------------------------------------------------------------ 423 /** 424 * Determines whether the keyboard is covered by a subwindow. 425 * 426 * Gets whether the keyboard is covered by the window for switching keyboards or some other subwindow. 427 * 428 * @return Returns <tt>true</tt> if covered. 429 * 430 * @note Ignore user operations of the input form when the single keyboard is called and when the keyboard is being covered by a subwindow. 431 */ 432 bool IsCoveredWithSubWindow(); 433 434 //------------------------------------------------------------------------------ 435 /** 436 * Determines whether the selection cursor is active. 437 * 438 * @return Returns <tt>true</tt> if active. 439 * 440 * @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). 441 */ 442 bool IsSelectCursorActive(); 443 444 //------------------------------------------------------------------------------ 445 /** 446 * Deactivates the selection cursor. 447 * 448 * If the keyboard is displaying on the TV and the selection cursor is active, calling this function deactivates it. 449 * 450 * 451 * @return Returns <tt>true</tt> if active. 452 */ 453 void InactivateSelectCursor(); 454 455 //------------------------------------------------------------------------------ 456 /** 457 * Confirms unfixed text. 458 * 459 * Use this function to confirm unfixed text, for example when the user touches an entry field and forces the cursor to move. 460 * 461 */ 462 void ConfirmUnfixAll(); 463 464 //------------------------------------------------------------------------------ 465 /** 466 * Gets information for rendering text, such as information for drawing in an unconfirmed range. 467 * 468 * @param[out] info Rendering information. 469 */ 470 void GetDrawStringInfo( nn::swkbd::DrawStringInfo* info ); 471 472 //------------------------------------------------------------------------------ 473 /** 474 * Sets the cursor position. 475 * 476 * Use this function to notify the keyboard of the cursor position when the cursor is moved in an input form. 477 * 478 * @param[in] pos The cursor position. 479 */ 480 void SetCursorPos( s32 pos ); 481 482 //------------------------------------------------------------------------------ 483 /** 484 * Sets the starting position for character selection. 485 * 486 * Use this function to notify the keyboard of the starting position for character selection when the cursor is moved. 487 * Specify <tt>-1</tt> if text is not selected. 488 * 489 * @param[in] from The starting position for character selection. 490 */ 491 void SetSelectFrom( s32 from ); 492 493 /** @} */ 494 495 496 //------------------------------------------------------------------------------ 497 } // namespace swkbd 498 //------------------------------------------------------------------------------ 499 } // namespace nn 500 501 #endif /* NN_SWKBD_H_ */ 502