Creating and Using a Custom Caret

• Microsoft Windows Software Development Kit (SDK) versions 3.0 and 3.1
• Microsoft Win32 Application Programming Interface (API) included with:

      - Microsoft Windows NT versions 3.5 and 3.51
      - Microsoft Windows 95 version 4.0
  

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);

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.