Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

11    Pinlet

Input Services

Exploring Palm OS®

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 ^TOP^

PinletAPIType Struct ^TOP^

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 ^TOP^

PINFeedChar Function ^TOP^

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

Nothing.

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()

PINFeedString Function ^TOP^

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

Nothing.

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

PINFeedChar()

Pinlet-Defined Functions ^TOP^

PinletClearStateProcPtr Function ^TOP^

Purpose

Clears the current internal state of the pinlet.

Declared In

Pinlet.h

Prototype

void (
   *PinletClearStateProcPtr
) (
   void
)

Parameters

None.

Returns

Nothing.

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

HWRClearInputState()

PinletGetInputModeProcPtr Function ^TOP^

Purpose

Returns the current input mode of the pinlet.

Declared In

Pinlet.h

Prototype

uint16_t (
   *PinletGetInputModeProcPtr
) (
   void
)

Parameters

None.

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 ^TOP^

Purpose

Sets the pinlet input mode.

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

Nothing.

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 ^TOP^

Purpose

Displays the help or reference dialog for the pinlet.

Declared In

Pinlet.h

Prototype

void (
   *PinletShowReferenceDialogProcPtr
) (
   void
)

Parameters

None.

Returns

Nothing.

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.

See Also

"Help Dialog"