From f955e734df6165dd9fc7e5a8ac26378c691962ae Mon Sep 17 00:00:00 2001 From: Ash Logan Date: Sat, 16 Feb 2019 17:19:55 +1100 Subject: [PATCH] include/swkbd: First shot at documenting swkbd Mostly based off wut's example, but hey, should be pretty good! --- include/nn/swkbd.h | 1 + include/nn/swkbd/swkbd_cpp.h | 260 +++++++++++++++++++++++++++++++++- include/swkbd/rpl_interface.h | 1 + include/swkbd/swkbd.dox | 3 +- 4 files changed, 261 insertions(+), 4 deletions(-) diff --git a/include/nn/swkbd.h b/include/nn/swkbd.h index 6e96293..293c27c 100644 --- a/include/nn/swkbd.h +++ b/include/nn/swkbd.h @@ -2,6 +2,7 @@ /** * \defgroup nn_swkbd nn_swkbd + * Graphical software keyboard, supporting several languages and configurations. */ #include diff --git a/include/nn/swkbd/swkbd_cpp.h b/include/nn/swkbd/swkbd_cpp.h index 92ad09c..fe2cc4a 100644 --- a/include/nn/swkbd/swkbd_cpp.h +++ b/include/nn/swkbd/swkbd_cpp.h @@ -9,6 +9,8 @@ /** * \defgroup nn_swkbd_swkbd Software Keyboard * \ingroup nn_swkbd + * See \link nn::swkbd \endlink. + * * @{ */ @@ -16,6 +18,20 @@ namespace nn { + +/** + * Graphical software keyboard, supporting several languages and configurations. + * Applications should first call \link Create \endlink to initialise the + * library, followed by \link AppearInputForm \endlink to show a text area and + * virtual keyboard. Input should be forwarded to the keyboard via + * \link Calc \endlink, along with calls to \link CalcSubThreadFont \endlink and + * \link CalcSubThreadPredict \endlink. Finally, the keyboard can be rendered + * with \link DrawTV \endlink and \link DrawDRC \endlink. The user's interaction + * with the keyboard can be tracked with \link GetInputFormString \endlink, + * \link IsDecideOkButton \endlink and \link IsDecideCancelButton \endlink; and + * once satisfied the application can dismiss the keyboard with + * \link DisappearInputForm \endlink. Don't forget \link Destroy \endlink! + */ namespace swkbd { @@ -42,6 +58,7 @@ enum class State Unknown0 = 0, }; +//! Configuration options for the virtual keyboard. struct ConfigArg { ConfigArg() @@ -56,6 +73,7 @@ struct ConfigArg unk_0xA4 = -1; } + //! The language to use for input LanguageType languageType; uint32_t unk_0x04; uint32_t unk_0x08; @@ -94,19 +112,23 @@ WUT_CHECK_OFFSET(ReceiverArg, 0x10, unk_0x10); WUT_CHECK_OFFSET(ReceiverArg, 0x14, unk_0x14); WUT_CHECK_SIZE(ReceiverArg, 0x18); +//! Arguments for the swkbd keyboard struct KeyboardArg { + //! Configuration for the keyboard itself ConfigArg configArg; ReceiverArg receiverArg; }; WUT_CHECK_SIZE(KeyboardArg, 0xC0); +//! Arguments for swkbd the input form (text area). struct InputFormArg { uint32_t unk_0x00 = 1; int32_t unk_0x04 = -1; uint32_t unk_0x08 = 0; uint32_t unk_0x0C = 0; + //! The maximum number of characters that can be entered, -1 for unlimited. int32_t maxTextLength = -1; uint32_t unk_0x14 = 0; uint32_t unk_0x18 = 0; @@ -127,18 +149,25 @@ WUT_CHECK_OFFSET(InputFormArg, 0x1D, unk_0x1D); WUT_CHECK_OFFSET(InputFormArg, 0x1E, unk_0x1E); WUT_CHECK_SIZE(InputFormArg, 0x20); +//! Arguments for the swkbd input form and keyboard. struct AppearArg { + //! Arguments for the virtual keyboard KeyboardArg keyboardArg; + //! Arguments for the input form (text area) InputFormArg inputFormArg; }; WUT_CHECK_SIZE(AppearArg, 0xE0); +//!The arguments used to initialise swkbd and pass in its required resources. struct CreateArg { + //! A pointer to a work memory buffer; see \link GetWorkMemorySize \endlink. void *workMemory = nullptr; + //! The swkbd region to use. RegionType regionType = RegionType::Europe; uint32_t unk_0x08 = 0; + //! An FSClient for swkbd to use while loading resources. FSClient *fsClient = nullptr; }; WUT_CHECK_OFFSET(CreateArg, 0x00, workMemory); @@ -147,9 +176,12 @@ WUT_CHECK_OFFSET(CreateArg, 0x08, unk_0x08); WUT_CHECK_OFFSET(CreateArg, 0x0C, fsClient); WUT_CHECK_SIZE(CreateArg, 0x10); +//! Input and controller information for swkbd. struct ControllerInfo { + //! DRC input information, see \link VPADRead \endlink. VPADStatus *vpad = nullptr; + //! Wiimote and extension controller inputs, see \link KPADRead \endlink. KPADStatus *kpad[4] = { nullptr, nullptr, nullptr, nullptr }; }; WUT_CHECK_OFFSET(ControllerInfo, 0x00, vpad); @@ -180,45 +212,169 @@ struct IEventReceiver; struct IControllerEventObj; struct ISoundObj; +/** + * Show an input form (keyboard with text area) with the given configuration. + * + * \param args + * An \link nn::swkbd::AppearArg AppearArg \endlink struct with the desired + * configuration for the keyboard and input form. + * + * \return + * \c true on success, or \c false on error. + * + * \sa + * - \link DisappearInputForm \endlink + * - \link GetInputFormString \endlink + * - \link IsDecideOkButton \endlink + * - \link IsDecideCancelButton \endlink + */ bool AppearInputForm(const AppearArg& args); +/** + * Show a keyboard with the given configuration. + * + * \param args + * An \link nn::swkbd::KeyboardArg KeyboardArg \endlink struct with the desired + * configuration for the keyboard. + * + * \return + * \c true on success, or \c false on error. + * + * \sa + * - \link DisappearKeyboard \endlink + * - \link IsDecideOkButton \endlink + * - \link IsDecideCancelButton \endlink + */ bool AppearKeyboard(const KeyboardArg& args); +/** + * Calculate font data. Call in response to + * \link IsNeedCalcSubThreadFont \endlink. + * + * \sa + * - \link CalcSubThreadPredict \endlink + * - \link Calc \endlink + */ void CalcSubThreadFont(); +/** + * Calculate word prediction data. Call in response to + * \link IsNeedCalcSubThreadPredict \endlink. + * + * \sa + * - \link CalcSubThreadFont \endlink + * - \link Calc \endlink + */ void CalcSubThreadPredict(); +/** + * Respond to user inputs and calculate the state of input buffers and graphics. + * + * \param controllerInfo + * A \link nn::swkbd::ControllerInfo ControllerInfo \endlink structure + * containing fresh data from the controllers (see \link VPADRead \endlink + * and \link KPADRead \endlink). Each controller can also be \c nullptr if data + * is not available. + * + * \sa + * - \link CalcSubThreadFont \endlink + * - \link CalcSubThreadPredict \endlink + */ void Calc(const ControllerInfo &controllerInfo); void ConfirmUnfixAll(); +/** + * Initialise the swkbd library and create the keyboard and input form. + * + * \param args + * A \link nn::swkbd::CreateArg CreateArg \endlink structure containing the + * desired keyboard region, a pointer to work memory, and an + * \link FSClient \endlink. See \link nn::swkbd::CreateArg CreateArg\endlink. + * + * \return + * \c true on success, \c false otherwise. + * + * \sa + * - \link Destroy \endlink + * - \link GetWorkMemorySize \endlink + */ bool Create(const CreateArg &args); +/** + * Clean up and shut down the swkbd library. + * + * \note + * Resources passed into \link Create \endlink (work memory, filesystem client) + * must be manually freed by the application after calling this + * function. + * + * \sa + * - \link Create \endlink + */ void Destroy(); +/** + * Hide a previously shown input form. + * + * \return + * \c true on success, \c false otherwise. + * + * \sa + * - \link AppearInputForm \endlink + * - \link GetInputFormString \endlink + */ bool DisappearInputForm(); +/** + * Hide a previously shown keyboard. + * + * \return + * \c true on success, \c false otherwise. + * + * \sa + * - \link AppearKeyboard \endlink + */ bool DisappearKeyboard(); +/** + * Draw the keyboard to the DRC. Must be called inside a valid GX2 rendering + * context, after rendering all other DRC graphics (to appear under the + * keyboard) + */ void DrawDRC(); +/** + * Draw the keyboard to the TV. Must be called inside a valid GX2 rendering + * context, after rendering all other TV graphics (to appear under the + * keyboard) + */ void DrawTV(); void GetDrawStringInfo(DrawStringInfo *drawStringInfo); +/** + * Get the string the user typed into the input form. + * + * \returns + * The user's text, as a null-terminated UTF-16 string. + * + * \sa + * - \link SetInputFormString \endlink + */ const char16_t * GetInputFormString(); @@ -231,49 +387,147 @@ GetStateInputForm(); State GetStateKeyboard(); +/** + * Get the required size for swkbd's work memory buffer. The application must + * allocate a buffer of this size and pass it into \link Create \endlink. + * + * \param unk + * Unknown. A value of 0 seems to work. + * + * \return + * The required size of the work buffer, in bytes. + * + * \sa + * - \link Create \endlink + */ uint32_t GetWorkMemorySize(uint32_t unk); void InactivateSelectCursor(); - bool InitLearnDic(void *dictionary); bool IsCoveredWithSubWindow(); +/** + * Gets the current status of the Cancel button on the keyboard. + * + * \param outIsSelected + * Pointer to a boolean to write the button status to, or \c nullptr if the + * return value is enough. + * + * \return + * \c true if the Cancel button has been pressed, or \c false otherwise. + * + * \sa + * - \link IsDecideOkButton \endlink + */ bool IsDecideCancelButton(bool *outIsSelected); +/** + * Gets the current status of the OK button on the keyboard. + * + * \param outIsSelected + * Pointer to a boolean to write the button status to, or \c nullptr if the + * return value is enough. + * + * \return + * \c true if the OK button has been pressed, or \c false otherwise. + * + * \sa + * - \link IsDecideCancelButton \endlink + */ bool IsDecideOkButton(bool *outIsSelected); bool IsKeyboardTarget(IEventReceiver *eventReceiver); +/** + * Determines whether the font data needs calculating. If it does, a call to + * \link CalcSubThreadFont \endlink is required. + * + * \return + * \c true if the font data needs calculating, \c false otherwise. + * + * \sa + * - \link IsNeedCalcSubThreadPredict \endlink + */ bool IsNeedCalcSubThreadFont(); +/** + * Determines whether the prediction data needs calculating. If it does, a call + * to \link CalcSubThreadPredict \endlink is required. + * + * \return + * \c true if the prediction data needs calculating, \c false otherwise. + * + * \sa + * - \link IsNeedCalcSubThreadFont \endlink + */ bool IsNeedCalcSubThreadPredict(); +/** + * Determines whether the selection cursor is active. + * + * \return + * \c true if the selection cursor is active, \c false otherwise. + */ bool IsSelectCursorActive(); +/** + * Mutes or unmutes the sounds generated by the keyboard. + * + * \param muted + * \c true to disable all sounds, or \c false to enable them. + */ void MuteAllSound(bool muted); void SetControllerRemo(ControllerType type); +/** + * Set the character at which the cursor is positioned. + * + * \param pos + * The position at which to move the cursor, with 0 corresponding to the start + * of the string (before the first character). + * + * + */ void -SetCursorPos(int); +SetCursorPos(int pos); +/** + * Enables and disables the OK button on the keyboard. When disabled, the button + * cannot be pressed. + * + * \param enable + * \c true to enable the button, or \c false to disable it. + */ void -SetEnableOkButton(bool); +SetEnableOkButton(bool enable); +/** + * Sets the text in the input form. + * + * \param str + * The UTF-16 string to set the input form to. + * + * \sa + * - \link GetInputFormString \endlink + */ void SetInputFormString(const char16_t *str); diff --git a/include/swkbd/rpl_interface.h b/include/swkbd/rpl_interface.h index 6cd0662..c5eef5a 100644 --- a/include/swkbd/rpl_interface.h +++ b/include/swkbd/rpl_interface.h @@ -5,6 +5,7 @@ /** * \defgroup swkbd_rpl RPL Interface * \ingroup swkbd + * C++ linkage for swkbd, see \link nn::swkbd \endlink for general use. * @{ */ diff --git a/include/swkbd/swkbd.dox b/include/swkbd/swkbd.dox index e664827..5577996 100644 --- a/include/swkbd/swkbd.dox +++ b/include/swkbd/swkbd.dox @@ -1,5 +1,6 @@ /** * \defgroup swkbd swkbd * - * Software Keyboard library. + * C++ linkage for the software keyboard, see \link nn::swkbd \endlink for + * general use. */