INF: Creating and Using a Custom Caret

ID Number: Q74514

3.00

WINDOWS

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 functions), 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 reference words: 3.00