Caret Tracking in Tablet PC Input Panel

Article
03/02/2007

Tracy Schultz
Tablet PC team

Microsoft Corporation

January 2004

Applies to:
Microsoft® Windows® XP Tablet PC Edition 2005

Summary: Tablet PC Input Panel depends on an application's support for caret tracking. This article describes some caret tracking best practices for enabling Tablet PC Input Panel that appears next to text entry areas in your application. Readers should be familiar with Input Panel and Microsoft Active Accessibility. (4 printed pages)

Introduction

Microsoft® Windows® XP Tablet PC Edition 2005 includes the ability to open Tablet PC Input Panel next to any editable text input control, such as an edit control or an editable combo box. Input Panel uses caret tracking events to determine which text input control has focus and can invoke Input Panel. However, Input Panel does not appear when a caret is not present or if caret events are not being accurately generated. The information in this article pertains only to Input Panel when it appears next to a text entry area. It does not pertain to Input Panel when you dock it at the top or bottom of the screen.

Figure 1. The Input Panel is not docked.

You can use Microsoft Active Accessibility (MSAA) to track caret events for input controls. MSAA is a set of Component Object Model (COM) interfaces and application programming interfaces (APIs) that provides a reliable way to expose and collect information about Windows-based UI elements and Web content. In addition to providing accessibility support, MSAA includes an API that an application can use to provide Input Panel with caret tracking information. Having full MSAA support is the simplest way to ensure Input Panel works in your application.

Note If your application uses a complete implementation of Windows Text Services Framework (TSF), Microsoft Rich Edit Version 4.1 or later with TSF functionality enabled, or Microsoft MSHTML, it is not necessary to implement MSAA to support caret tracking. Input Panel uses MSAA as the default caret tracking method. However, if you implement one of these other three APIs, Input Panel uses the API's caret tracking support for these fields.

Application Dependency

To appear next to the text entry area correctly, Input Panel requires the following three pieces of information from an application, all of which MSAA supports:

Caret position – Input Panel uses the caret position to determine which text field has focus and to track the cursor. Your application must update the caret position regularly. Any lag or discrepancy in caret position updates can result in Input Panel appearing in an incorrect location or not appearing at all.

Text field coordinates – Input Panel requires the coordinates of the active text field to determine its own relative position and to avoid overlapping the UI element that has focus.

Read/write state – If a text field is flagged as read-only, Input Panel does not appear. Consistently setting the read/write state of UI elements ensures correct Input Panel behavior.

Using Caret Tracking Functionality in MSAA

To support Input Panel, you must implement the following five functions, which represent the core caret tracking functionality in MSAA:

CreateCaret creates a new shape for the system caret and assigns ownership of the caret to the specified window.

SetCaretPos moves the caret to the specified coordinates.

ShowCaret makes the caret visible on the screen at the caret's current position.

HideCaret removes the caret from the screen, but does not invalidate the insertion point.

DestroyCaret destroys the caret's current shape, frees the caret from the window, and removes the caret from the screen.

For more information about MSAA system caret tracking, see an overview of carets.

Using Custom Caret Tracking

Although you can use custom caret tracking, it is not recommended because Input Panel is not available in an application that uses custom caret tracking and implements no other caret tracking API. However, if your application already uses custom caret tracking, you can implement MSAA system caret tracking alongside a custom caret or selection.

If displaying the blinking MSAA system caret line or block creates a visual problem, you can create the caret by using an empty bitmap. MSAA is then able to communicate the necessary caret tracking information to Input Panel without the caret showing. Simply call the CreateCaret function with the second parameter, hBitmap, set as an empty bitmap.

Troubleshooting

If Input Panel does not appear in your application when you use MSAA to provide caret tracking information, verify that your application does the following:

Generates accurate EVENT_OBJECT_FOCUS calls for the object that has keyboard focus. Calls are generated automatically if you do not use windowless controls and you use SetFocus() to give a window keyboard focus. Input Panel uses these calls to determine which application has focus.

Updates the caret position promptly after moving the caret. A long delay between Input Panel closing, the caret moving, and the caret position updating prevents Input Panel from appearing when and where the user expects. Such a delay often occurs when an application hides the system caret and does expensive processing without reshowing the caret until the processing is completed. Your application should never keep the caret hidden for more than 100 milliseconds, and it should always update the caret position upon showing it.

Has the associated STATE_SYSTEM_READONLY flag set to read-only for uneditable text fields. It is also advisable that the ROLE_SYSTEM_TEXT flag is set for standard editable text fields.

Does not hide the system caret on selection. It should show the system caret next to the highlighted selection.

Conclusion

Input Panel depends on your application generating accurate and timely caret tracking events. MSAA includes an API that, when implemented, provides Input Panel with the required information about your application's caret position and state. Having full MSAA support in your application is the simplest way to ensure Tablet PC users can fully use the features of your application.