This chapter describes the APIs that must be implemented in a pinlet. It covers:
Pinlet Structures and Types
Pinlet Functions and Macros
Pinlet-Defined Functions
The header file Pinlet.h
declares the API that this chapter describes.
For more information about implementing pinlets, see Chapter 3, "Customizing the Dynamic Input Area."
Pinlet Structures and Types
PinletAPIType Struct
Purpose
Defines the functions that the pinlet implements.
Declared In
Pinlet.h
Prototype
typedef struct { PinletClearStateProcPtr pinletClearState; PinletGetInputModeProcPtr pinletGetInputMode; PinletSetInputModeProcPtr pinletSetInputMode; PinletShowReferenceDialogProcPtr pinletShowReferenceDialog; } PinletAPIType
Fields
-
pinletClearState
- Pointer to the function that clears the pinlet state. See
PinletClearStateProcPtr()
. -
pinletGetInputMode
- Pointer to the function that returns the pinlet's input mode. See
PinletGetInputModeProcPtr()
. -
pinletSetInputMode
- Pointer to the function that sets the pinlet's input mode. See
PinletSetInputModeProcPtr()
. -
pinletShowReferenceDialog
- Pointer to the function that displays pinlet help. See
PinletShowReferenceDialogProcPtr()
.
Comments
You pass this structure back to the Pen Input Manager in the parameter block for the sysPinletLaunchCmdLoadProcPtrs launch code.
The Pen Input Manager only calls the functions you specify while the pinlet is running.
Pinlet Functions and Macros
PINFeedChar Function
Purpose
Sends a character key to Palm OS®.
Declared In
Pinlet.h
Prototype
void PINFeedChar (
wchar32_t chr,
uint32_t flags
)
Parameters
-
→ chr
- The character to be sent. This character must use the UTF8 character encoding.
-
→ flags
- 0 or pinCharFlagVirtual if the character is a virtual character.
Returns
Comments
The Pen Input Manager expects characters in the UTF8 encoding. If necessary, use TxtConvertEncoding()
to convert a character from the device's native encoding to UTF8 before calling this function. Note that the character gets converted back to the device's native encoding before the application receives the keyDownEvent
.
See Also
PINFeedString Function
Purpose
Sends a string of characters to Palm OS.
Declared In
Pinlet.h
Prototype
void PINFeedString (
const char *str
)
Parameters
-
→ str
- A string containing the characters to be sent. The characters must use the UTF8 character encoding.
Returns
Comments
This function is a convenient way to send more than one character to the Pen Input Manager at once. A keyDownEvent
is created for each character in the string. You cannot send virtual characters using this function.
The Pen Input Manager expects characters in the UTF8 encoding. If necessary, use TxtConvertEncoding()
to convert characters from the device's native encoding to UTF8 before calling this function. Note that the characters get converted back to the device's native encoding before the application receives the keyDownEvent
.
See Also
Pinlet-Defined Functions
PinletClearStateProcPtr Function
Purpose
Clears the current internal state of the pinlet.
Declared In
Pinlet.h
Prototype
void ( *PinletClearStateProcPtr ) ( void )
Parameters
Returns
Comments
This function should clear any such internal state and should reset the input mode back to the normal mode. The Pen Input Manager calls this function when it receives the PINClearPinletState()
call.
As described in "Handling Multistroke Characters," a pinlet may need to keep some internal state while it is running. PinletClearStateProcPtr()
is called when the user has performed an action, such as switching to a new text field, that clearly indicates that they are done writing that character, so the internal state should be cleared.
See Also
PinletGetInputModeProcPtr Function
Purpose
Returns the current input mode of the pinlet.
Declared In
Pinlet.h
Prototype
uint16_t ( *PinletGetInputModeProcPtr ) ( void )
Parameters
Returns
One of the input mode constants listed in the section "Pinlet Input Modes."
Comments
The Pen Input Manager calls this function when it receives the PINGetInputMode()
call. Handwriting recognition pinlets should call through to the HWRGetInputMode()
function.
See Also
PinletSetInputModeProcPtr()
, "Considering the Input Modes"
PinletSetInputModeProcPtr Function
Purpose
Declared In
Pinlet.h
Prototype
void ( *PinletSetInputModeProcPtr ) ( uint16_t mode )
Parameters
-
→ mode
- The mode to which the pinlet should be set. This is one of the constants listed in the "Pinlet Input Modes" section.
Returns
Comments
The Pen Input Manager calls this function in response to the PINSetInputMode()
function.
The pinlet input mode determines how the pinlet translates the next set of input from the user. The modes that a pinlet uses or accepts are up to the pinlet. Typically, in the normal or default input mode, the pinlet translates user input into lowercase letters. Translation into any other type of character or symbol requires a different input mode.
The input mode should be considered a hint that the pinlet can use to coordinate with the application. If the pinlet does respect the input mode, it should have a visible indication of what its current input mode is.
Not all input modes apply to all pinlets. If the pinlet does not support the specified input mode, it should choose the closest equivalent that is supported, which could be the default mode.
Handwriting recognition pinlets can call through to the function HWRSetInputMode()
.
See Also
PinletGetInputModeProcPtr()
, "Considering the Input Modes"
PinletShowReferenceDialogProcPtr Function
Purpose
Displays the help or reference dialog for the pinlet.
Declared In
Pinlet.h
Prototype
void ( *PinletShowReferenceDialogProcPtr ) ( void )
Parameters
Returns
Comments
The Pen Input Manager calls this function in response to the PINShowReferenceDialog()
function.
The pinlet should display a dialog that teaches the user how to use the pinlet. Handwriting recognition pinlets can call through to HWRShowReferenceDialog()
.
Some pinlets may not require a help dialog. For example, keyboard pinlets rarely need explanatory text. If the pinlet has no help to display, this function should display an alert that says no help is available for this pinlet.