Carets

A caret is a flashing line or block in the client area of a window that indicates the place at which the user will insert text or graphics. To display a solid caret, Windows CE inverts every pixel in the window rectangle. Windows CE does not support bitmap carets. The following screen shot illustrates a caret as it appears in text.

Caret

    To create and display a caret

1. Call the CreateCaret function.

   Windows CE formats a caret by inverting the pixel color within the rectangle specified by the caret's position, width, and height.

2. Call the SetCaretPos function to set the caret's position.
3. Call the ShowCaret function to make the caret visible. When the caret appears, it automatically begins flashing.

The system sends the WM_SETFOCUS message to the window receiving keyboard focus; therefore, an application should create and display the caret while processing this message.

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

The flash time is the elapsed time, in milliseconds, required to display, invert, and restore the caret's display. The flash time of a caret is twice as much as the blink time.

You can determine the position of the caret using 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 it is visible or not.

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 your application must redraw the screen while processing a message, but must keep the caret out of the way. 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.