Using ITextCtl

A text control enables the device user to enter a string of text using the keys on the device. The text control consists of an optional title and a rectangular window containing one or more lines in which the entered text is displayed to the device user. The text control handles the translation of device user key presses into characters. Your application only needs to pass keypress events to the text control while it is active and retrieve the text from the control when device user text entry has completed. The translation process depends on the text entry modes the device supports (for example, the standard multi-tap mode in which the device user selects from the characters mapped to each key, and Tegic's T9 predictive text input mode). If more than one text entry mode is supported, your application makes it possible for the device user to select the specified mode while the text control is active. The text control allows you to specify a Soft Key menu that is used for this purpose.

While the text control is active, your application must send all keypress events to it by calling ITEXTCTL_HandleEvent(). The input mode menu control is managed by the underlying text control. If the input mode menu is activated by pressing the associated softkey, then the underlying text control will be deactivated until the input mode menu is dismissed.

To use a text control in your application

1. Call ISHELL_CreateInstance() to create an instance of the text control.

2. Call ITEXTCTL_SetRect() to specify the screen rectangle that contains the text control.

3. If specified, call ITEXTCTL_SetTitle() or ITEXTCTL_SetText() to specify the control's title and the initial value of its text string.

4. Call ITEXTCTL_SetProperties() to set any text control properties.

5. Call ITEXTCTL_SetSoftKeyMenu() to specify the Soft Key menu that is associated with the text control, if any.

6. Call ITEXTCTL_SetActive() to activate the text control and draw its contents on the screen.

7. While the text control is active, call ITEXTCTL_HandleEvent() to pass it any key events generated by the user.

8. When the device user has completed entering text, call ITEXTCTL_GetText() or ITEXTCTL_GetTextPtr() to retrieve the text the device user has entered. (If you are using a Soft Key menu, the device user may signal the completion of text entry with a "Done" item in the menu, or by pressing the SELECT or other key if no Soft Key menu is present).

9. Call ITEXTCTL_Release() to free the text control when you no longer need it.

The following header file is required for ITextCtl

AEEText.h

Required Header File

AEEText.h