Skip to content

Commit

Permalink
Document OSK
Browse files Browse the repository at this point in the history
  • Loading branch information
@dogo
dogo committed Aug 31, 2024
1 parent 23bdc6e commit a2451a9
Showing 1 changed file with 177 additions and 64 deletions.
241 changes: 177 additions & 64 deletions src/osk.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,110 +2,223 @@
#define OSK_H

/** @defgroup OSK On-Screen Keyboard
Functions to display Sony's On Screen Keyboard
@{
@{
Functions to display Sony's On Screen Keyboard.
*/
//<-- STAS: define the OSL_KEYBOARD structure and its methods for multithreaded environment

/**
* @brief Structure representing the on-screen keyboard (OSK) parameters.
*/
typedef struct {
SceUtilityOskParams oskParams;
// SceUtilityOskData *oskData;
SceUtilityOskParams oskParams; /**< Parameters for the on-screen keyboard. */
} OSL_KEYBOARD;

/** @brief Global instance of the on-screen keyboard. */
extern OSL_KEYBOARD* osl_osk;

/**
* @brief Initializes the on-screen keyboard with specified parameters.
*
* @param nData Number of data entries to initialize.
* @param language Language of the on-screen keyboard.
*
* @return Pointer to the initialized OSL_KEYBOARD structure.
*/
extern OSL_KEYBOARD* oslInitOskEx(int nData, int language);

/**
* @brief Initializes specific OSK data.
*
* @param kbd Pointer to the OSL_KEYBOARD structure.
* @param idx Index of the data entry.
* @param desc Description text (UTF-16).
* @param intext Initial text input (UTF-16).
* @param textLimit Maximum number of characters.
* @param linesNumber Number of lines for input.
*
* @return Status code of the initialization process.
*/
extern int oslInitOskDataEx(OSL_KEYBOARD *kbd, int idx, unsigned short *desc,
unsigned short *intext, int textLimit, int linesNumber);

/**
* @brief Activates the on-screen keyboard.
*
* @param kbd Pointer to the OSL_KEYBOARD structure.
* @param waitcycle Time to wait before the OSK is fully activated.
*
* @return Status code of the activation process.
*/
extern int oslActivateOskEx(OSL_KEYBOARD *kbd, int waitcycle);

/**
* @brief Checks if the on-screen keyboard is active.
*
* @param kbd Pointer to the OSL_KEYBOARD structure.
*
* @return Non-zero if the OSK is active, zero otherwise.
*/
extern int oslOskIsActiveEx(OSL_KEYBOARD *kbd);

/**
* @brief Deactivates the on-screen keyboard.
*
* @param kbd Pointer to the OSL_KEYBOARD structure.
*/
extern void oslDeActivateOskEx(OSL_KEYBOARD *kbd);

/**
* @brief Gets the result of the on-screen keyboard interaction.
*
* @param kbd Pointer to the OSL_KEYBOARD structure.
* @param idx Index of the data entry.
*
* @return Result code indicating whether the text was changed, unchanged, or canceled.
*/
extern int oslOskGetResultEx(OSL_KEYBOARD *kbd, int idx);

/**
* @brief Retrieves the text output from the on-screen keyboard.
*
* @param kbd Pointer to the OSL_KEYBOARD structure.
* @param idx Index of the data entry.
*
* @return Pointer to the text output (UTF-16).
*/
extern unsigned short* oslOskOutTextEx(OSL_KEYBOARD *kbd, int idx);

/**
* @brief Ends the on-screen keyboard session and releases resources.
*
* @param kbd Pointer to the OSL_KEYBOARD structure.
*/
extern void oslEndOskEx(OSL_KEYBOARD *kbd);


#define OSL_OSK_RESULT_UNCHANGED PSP_UTILITY_OSK_RESULT_UNCHANGED
#define OSL_OSK_RESULT_CANCELLED PSP_UTILITY_OSK_RESULT_CANCELLED
#define OSL_OSK_RESULT_CHANGED PSP_UTILITY_OSK_RESULT_CHANGED
//<-- STAS END -->

/**OSK cancel*/
#define OSL_OSK_CANCEL PSP_UTILITY_OSK_RESULT_CANCELLED /**<-- STAS: for backward compatibility */
/**OSK changed*/
/**
* @def OSL_OSK_RESULT_UNCHANGED
* @brief Indicates that the OSK result is unchanged.
*
* This macro maps to `PSP_UTILITY_OSK_RESULT_UNCHANGED`, which is used to indicate that the user did not modify the text in the On-Screen Keyboard.
*/
#define OSL_OSK_RESULT_UNCHANGED PSP_UTILITY_OSK_RESULT_UNCHANGED

/**
* @def OSL_OSK_RESULT_CANCELLED
* @brief Indicates that the OSK operation was cancelled.
*
* This macro maps to `PSP_UTILITY_OSK_RESULT_CANCELLED`, which is used to indicate that the user cancelled the On-Screen Keyboard without making changes.
*/
#define OSL_OSK_RESULT_CANCELLED PSP_UTILITY_OSK_RESULT_CANCELLED

/**
* @def OSL_OSK_RESULT_CHANGED
* @brief Indicates that the OSK result has changed.
*
* This macro maps to `PSP_UTILITY_OSK_RESULT_CHANGED`, which is used to indicate that the user modified the text in the On-Screen Keyboard.
*/
#define OSL_OSK_RESULT_CHANGED PSP_UTILITY_OSK_RESULT_CHANGED

/**
* @brief OSK cancel result.
*
* @deprecated Use PSP_UTILITY_OSK_RESULT_CANCELLED instead.
*/
#define OSL_OSK_CANCEL PSP_UTILITY_OSK_RESULT_CANCELLED

/**
* @brief OSK changed result.
*/
#define OSL_OSK_CHANGED PSP_UTILITY_OSK_RESULT_CHANGED
/**OSK unchanged*/

/**
* @brief OSK unchanged result.
*/
#define OSL_OSK_UNCHANGED PSP_UTILITY_OSK_RESULT_UNCHANGED

/** Initializes the OSK
\param *descStr
Text shown as a description (bottom right corner)
\param initialStr
Initial text in the OSK
\param textLimit
Maximum number of chars
\param linesNumber
Number of lines
\param language
Language
JAPANESE 0
ENGLISH 1
FRENCH 2
SPANISH 3
GERMAN 4
ITALIAN 5
DUTCH 6
PORTUGUESE 7
RUSSIAN 8
KOREAN 9
CHINESE_TRADITIONAL 10
CHINESE_SIMPLIFIED 11
If you pass to the function -1 then the language set in the firmware is used
*/
/**
* @brief Initializes the OSK with basic parameters.
*
* @param descStr Text shown as a description (bottom right corner).
* @param initialStr Initial text in the OSK.
* @param textLimit Maximum number of characters.
* @param linesNumber Number of lines.
* @param language Language for the OSK.
* - 0: JAPANESE
* - 1: ENGLISH
* - 2: FRENCH
* - 3: SPANISH
* - 4: GERMAN
* - 5: ITALIAN
* - 6: DUTCH
* - 7: PORTUGUESE
* - 8: RUSSIAN
* - 9: KOREAN
* - 10: CHINESE_TRADITIONAL
* - 11: CHINESE_SIMPLIFIED
* - -1: Use the language set in the firmware.
*/
void oslInitOsk(char *descStr, char *initialStr, int textLimit, int linesNumber, int language);

/** Draws the OSK
After drawing it you should check if the user closed it. Remember to call oslEndOsk.
\code
if (oslOskIsActive()){
oslDrawOsk();
if (oslGetOskStatus() == PSP_UTILITY_DIALOG_NONE){
//The user closed the OSK
oslEndOsk();
}
}
\endcode
*/
/**
* @brief Draws the OSK on the screen.
*
* After drawing it, you should check if the user has closed it.
* Remember to call oslEndOsk to properly terminate the OSK.
*
* @code
* if (oslOskIsActive()){
* oslDrawOsk();
* if (oslGetOskStatus() == PSP_UTILITY_DIALOG_NONE){
* //The user closed the OSK
* oslEndOsk();
* }
* }
* @endcode
*/
void oslDrawOsk();

/** Checks if the OSK is active.
*/
/**
* @brief Checks if the OSK is currently active.
*
* @return Non-zero if the OSK is active, zero otherwise.
*/
int oslOskIsActive();

/**Returns the current OSK status
*/
/**
* @brief Returns the current OSK status.
*
* @return Current status of the OSK.
*/
int oslGetOskStatus();

/**Returns the OSK result (OSL_OSK_CHANGED, OSL_OSK_UNCHANGED or OSL_OSK_CANCEL)
*/
/**
* @brief Returns the result of the OSK interaction.
*
* @return Result code (OSL_OSK_CHANGED, OSL_OSK_UNCHANGED, or OSL_OSK_CANCEL).
*/
int oslOskGetResult();

/**Get the text inserted in the OSK
*/
/**
* @brief Retrieves the text inserted by the user in the OSK.
*
* @param text Pointer to the buffer where the text will be stored (UTF-8).
*/
void oslOskGetText(char *text);

/**
* @brief Retrieves the text inserted by the user in the OSK (UCS2).
*
* @param text Pointer to the buffer where the text will be stored (UTF-16).
*/
void oslOskGetTextUCS2(unsigned short *text);

/**Ends the OSK
*/
/**
* @brief Ends the OSK session.
*
* This function should be called after the OSK is closed to clean up resources.
*/
void oslEndOsk();

/** @} */ // end of OSK group

/** @} */ // end of osk
#endif

0 comments on commit a2451a9

Please sign in to comment.