HOWTO: Create and Use a Custom Caret

ID: Q74514

The information in this article applies to:

Microsoft Win32 Software Development Kit (SDK)
Microsoft Windows Software Development Kit (SDK) versions 3.0, 3.1

SUMMARY

In the Microsoft Windows graphical environment, creating a custom caret is simple. Windows has a series of caret control, creation, and deletion functions specifically designed to make manipulating the caret easy.

MORE INFORMATION

The caret is a shared system resource. Unlike brushes, pens, device contexts and such, but like the cursor, only one caret is available under Windows. Also, like the cursor, an application can define a custom shape for the caret.

The CreateCaret() function creates a custom caret. Its syntax is as follows:


   void CreateCaret(HWND hWnd, HBITMAP hBitmap,
                    int nWidth, int nHeight);

The caret shape can be a line, a block, or a bitmap specified as the hBitmap parameter. If the hBitmap parameter contains a valid handle [a bitmap handle returned from the CreateBitmap(), CreateDIBitmap(), or LoadBitmap() function], CreateCaret() ignores the values of its nWidth and nHeight parameters and uses the dimensions of the bitmap. If hBitmap is NULL, the caret is a solid block; if hBitmap is one, the caret is a gray block. The nWidth and nHeight parameters specify the caret size in logical units. If either nWidth or nHeight is zero, the caret width or height is set to the window-border width or height.

If an application uses a bitmap for the caret shape, the caret can be in color; unlike the cursor, the caret is not restricted to monochrome.

CreateCaret() automatically destroys the previous caret shape, if any, regardless of which window owns the caret. The new caret is initially hidden; call the ShowCaret() function to display the caret.

Because the caret is a shared resource, a window should create a caret only when it has the input focus or is active. It should destroy the caret before it loses the input focus or becomes inactive. Only the window that owns the caret should move it, show it, hide it, or modify it in any way.

Other functions related to the caret are the following:

SetCaretPos()
This function moves the caret to the specified position (in logical coordinates).

GetCaretPos()
This function retrieves the caret's current position (in screen coordinates).

ShowCaret()
This function shows the caret on the display at the caret's current position. When shown, the caret flashes automatically. If the caret is not owned by the window specified in the call, the caret is not shown.

HideCaret()
This function hides the caret by removing it from the display screen. HideCaret() hides the caret only if the window handle specified in the call is the window that owns the caret. Hiding the caret does not destroy it.

NOTE: Hiding the caret is cumulative; ShowCaret() must be called once for every call to HideCaret(). For example, if HideCaret() is called five times, ShowCaret() must be called five times for the caret to be shown.

DestroyCaret()
This function removes the caret from the screen, frees the caret from the current owner-window, and destroys the current shape of the caret. It destroys the caret only if the current task owns the caret. This call should be used in conjunction with CreateCaret(). DestroyCaret() does not free or destroy a bitmap used to define the caret shape.

SetCaretBlinkTime()
This function sets the caret blink rate. After the blink rate is set, it remains the same until the same window changes it again, another window changes it, another application changes it, or Windows is rebooted.

GetCaretBlinkTime()
This function returns the current caret blink rate.

Additional query words: WIN16SDK


Keywords          : kbCaret kbNTOS kbGrpUser kbWinOS 
Version           : 
Platform          : 
Issue type        : kbhowto

Last Reviewed: March 7, 1999