The Caret (Not the Cursor)

When you type text into a program, generally a little underline, vertical bar, or box shows you where the next character you type will appear on the screen. You may know this as a “cursor,” but you’ll have to get out of that habit when programming for Windows. In Windows, it’s called the “caret.” The word “cursor” is reserved for the little bitmap image that represents the mouse position.

There are five essential caret functions:

• CreateCaret Creates a caret associated with a window.
• SetCaretPos Sets the position of the caret within the window.
• ShowCaret Shows the caret.
• HideCaret Hides the caret.
• DestroyCaret Destroys the caret.

There are also functions to get the current caret position (GetCaretPos) and to get and set the caret blink time (GetCaretBlinkTime and SetCaretBlinkTime).

In Windows, the caret is customarily a horizontal line or box that is the size of a character, or a vertical line that is the height of a character. The vertical line caret is recommended when you use a proportional font such as the Windows default system font. Because the characters in a proportional font are not of a fixed size, the horizontal line or box can’t be set to the size of a character.

If you need a caret in your program, you should not simply create it during the WM_CREATE message of your window procedure and destroy it during the WM_DESTROY message. The reason this is not advised is that a message queue can support only one caret. Thus, if your program has more than one window, the windows must effectively share the same caret.

This is not as restrictive as it sounds. When you think about it, the display of a caret in a window makes sense only when the window has the input focus. Indeed, the existence of a blinking caret is one of the visual cues that allows a user to recognize that he or she may type text into a program. Since only one window has the input focus at any time, it doesn’t make sense for multiple windows to have carets blinking all at the same time.

A program can determine if it has the input focus by processing the WM_SETFOCUS and WM_KILLFOCUS messages. As the names imply, a window procedure receives a WM_SETFOCUS message when it receives the input focus and a WM_KILLFOCUS message when it loses the input focus. These messages occur in pairs: A window procedure will always receive a WM_SETFOCUS message before it receives a WM_KILLFOCUS message, and it always receives an equal number of WM_SETFOCUS and WM_KILLFOCUS messages over the course of the window’s lifetime.

The main rule for using the caret is simple: a window procedure calls CreateCaret during the WM_SETFOCUS message and DestroyWindow during the WM_KILLFOCUS message.

There are a few other rules: The caret is created hidden. After calling CreateCaret, the window procedure must call ShowCaret for the caret to be visible. In addition, the window procedure must hide the caret by calling HideCaret whenever it draws something on its window during a message other than WM_PAINT. After it finishes drawing on the window, the program calls ShowCaret to display the caret again. The effect of HideCaret is additive: if you call HideCaret several times without calling ShowCaret, you must call ShowCaret the same number of times before the caret becomes visible again.