Microsoft KB Archive/74514

{|
 * width="100%"|

HOWTO: Create and Use a Custom Caret

 * }

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 kbOSWinNT kbOSWin2000 kbSDKWin32 kbGrpDSUser kbOSWin

Issue type : kbhowto

Technology : kbWin32SDKSearch kbAudDeveloper kbWin3xSearch kbSDKSearch kbWin32sSearch kbWinSDKSearch kbWinSDK300 kbWinSDK310