Creating a Caret

A caret is a flashing line or block in the window client area that indicates the place where text or graphics will be inserted. Windows CE provides one caret per message queue. You should create a caret only when its associated window has the keyboard focus or is active. You should destroy the caret before the window loses the keyboard focus or becomes inactive. Once you create a caret, you can change how frequently a caret blinks, modify the caret position within a window, or temporarily remove a caret from view by hiding it. An application should create and display a caret while processing the WM_SETFOCUS message. Windows CE sends the WM_SETFOCUS message to a window when it receives the keyboard focus.

    To create and display a caret in a window

1. Call the CreateCaret function when the window receives focus. Windows CE formats a caret by inverting the pixel color within the rectangle specified by the caret's position, width, and height.
2. Set the caret position by calling the SetCaretPos function.
3. Make the caret visible by calling the ShowCaret function. When the caret appears, it begins flashing.

The following screen shot shows a caret as it appears in text.

The elapsed time, in milliseconds, that is required to invert the caret is called the blink time. The flash time is the elapsed time, in milliseconds, that is required to display, invert, and restore the caret's display. The flash time of a caret is twice as much as the blink time. The caret will blink as long as the thread that owns the message queue processes messages. A user can set the blink time of the caret by using Control Panel, and applications should maintain the settings that the user has chosen. An application can determine the caret blink time by using the GetCaretBlinkTime function. If you are writing an application that enables the user to adjust the blink time, such as a Control Panel application, use the SetCaretBlinkTime function to set the blink time rate to a specified number of milliseconds.

To determine the caret position, use the GetCaretPos function. An application can move a caret in a window by using the SetCaretPos function. A window can move a caret only if it already owns the caret. SetCaretPos can move the caret whether or not it is visible.

You can temporarily remove a caret by hiding it, or you can permanently remove the caret by destroying it. To hide the caret, use the HideCaret function. This is useful when the application must redraw the screen while processing a message, but must keep the caret out of view. When the application finishes drawing, it can display the caret again by using the ShowCaret function. Hiding the caret does not destroy its shape or invalidate the insertion point. Hiding the caret is cumulative; that is, if the application calls HideCaret five times, it must also call ShowCaret five times before the caret will reappear.

To remove the caret from the screen and destroy its shape, use the DestroyCaret function. DestroyCaret destroys the caret only if the window involved in the current task owns the caret.