Delphi - Cursors

Cursors are transparent images attached to the mouse pointer. Using the standard Windows cursors is pretty simple

For controls, just set the Cursor property
For the entire application, set Screen.Cursor

This page discusses how to create and use your own cursors.

In addition to this page, I have the following

Basics

Cursors are images with a designated hot spot (tip of the arrow, center of a bull's eye, ...) and are controlled by a pointing device (like a mouse). Windows provides a number of default cursors (arrow, hourglass, hand, etc) and programs can add their own. They can be stored as *.cur files or placed in the resource section of an exe or a dll file.

Windows identifies a cursor with a handle, Delphi apps use an index into the TScreen.Cursors[] "array" (actually, a linked list of TCursorRec records) to get the handles. In the "array", the predefined Windows cursors have negative indices and your custom cursors should have positive (reduces conflicts). The only real problem will be if you have more than one dcu with cursors. In that case, you need to do something to avoid conflicts.

Note: Besides reducing conflicts, when the application terminates, the Screen object automatically releases all cursors with positive indices.

Using the built-in cursors is trivial and well documented, however, creating and including custom cursors is very poorly documented. I assume that you are supposed to use a provided tool and just follow the instructions. Unfortunately, the only tool I have is fairly old and does not support any of the new features.

What Microsoft says

According to Microsoft

Cursors can be either monochrome or color, and either static or animated.

Well - that's cool. How do I create them?

Microsoft does not appear to have an answer. I was not able to determine a single technical detail. They don't even bother to suggest what size to use!

After many hours of digging, I stumbled onto the following CURSORDIR help in the Windows 32 Developers Reference supplied with Delphi 5.

The CURSORDIR structure contains the dimensions of an individual cursor image in a resource group. 

Width 
  Specifies the width of the cursor, in pixels. Acceptable values are 16, 32, and 64. 

Height 
  Specifies the height of the cursor, in pixels. Acceptable values are 16, 32, and 64.

The CreateCursor help (same source) allows the hotspot to be set and requires both an AND bitmask and an XOR bitmask. It also says that the size is system dependent and must be determined via a function call.

The LoadCursor help (same source) says

The LoadCursor function searches the cursor resource most appropriate for the cursor for the current display device. The cursor resource can be a color or monochrome bitmap.

So the questions remain unanswered

How many different cursors should I make?
What are the correct sizes?
What tools can I use?
How do I add color?

After a week or so working on this, I finally found some of those answers .. at O'Reilly! I won't repeat their excellent article here - enjoy. Unfortunately, they only give half the answer - to actually use their information I would have to write a program to convert a gimp produced ico file into a cur file and then figure out how to use a resource script to add it to the program.

Steps to create a cursor

These are the steps to create a simple "bulls eye" cursor using the Delphi 5 Image Editor. This editor is old

It only allows one cursor size - 32x32
It only supports monochrome cursors (black and white)
I does not support cursor groups (actually, it supports groups that contain only one cursor)

(Which is why I was trying to find specs .. so I could use another tool.) Using, the Image Editor it is possible to create either a cur file or an res file. Other than copy and paste, that tool does not provide a way to import a cur file into a res file, and the Delphi 5 linker requires an res file.

How to create Target_Cursor.res using Delphi 5 Image Editor

From the Delphi 5 menu, select Tools / Image Editor
Select File / New... / Resource File (.res)
Right click in the window and select New... / Cursor
Right click the cursor name and select Rename - due to a design problem (feature?), you will not be able to access the cursor unless you rename it. The name is not case sensitive.
Double click the cursor name to open the edit window
With the Ellipse tool draw 2 concentric circles starting at 3x3 and 8x8
- For the first circle, leave 3 pixels on the left and top, 4 on the right and bottom
- For the second circle, leave 4 pixels on all sides inside outer circle
Using the Line tool, draw vertical and horizontal lines 1 pixel wide thru 15,15 (the center) - stop one pixel from the right and bottom
From the menu, select Cursor / Set Hot Spot... and set it to 15,15
Save the file
Hint - the cursor location is shown in the status bar

Note that these instructions make the icon 31x31 pixels even though the drawing area is 32x32. This is so that the hotspot will be in the middle. This is not a big deal, but if the circle diameter was an even number of pixels, then center would be at the corner between 4 pixels and not at a specific integer location.

Note that this tool only supports a black and white image, to add colors, you can handle the mouse movements yourself and draw anything you like.

Using the cursor

To use the cursor, it needs to be included in the application's resource section. By default, Delphi creates a resource file for every application (app_name.res) and automatically includes it when building the exe file. Several sources say NOT to place your cursor (or any other resource) there - instead you should create a new resource file and link it to your application.

In one of your source files (it does not matter which one) include the resource file. Do not use an asterisk - in the resource statement, the asterisk is not a generic wildcard. Instead, it is replaced by the name of the source file.

{$R Cursor_Custom_Name.res}
{$R C:\[full path]\xxCursor_CustomName.res} // use a path if necessary

Using the cursor in code is a bit more involved - the following code searches for an unused index, loads the cursor, and returns the index.

var
 cur: Integer; // sometimes this needs to be available later

procedure TForm1.FormCreate(Sender: TObject);
begin
  cur := 0;                               // very important when adding a cursor
  LoadCursor_xx (cur, 'MCCURSOR_TARGET'); // the name is not case sensitive
  Some_Control.cursor := cur;
end;

procedure LoadCursor_xx(var CursorID: Integer; CursorName: String);
var
 i, xx, yy : integer ;
begin
  if CursorID = 0 then begin   // If the ID is not assigned, find an empty index
    yy := Screen.Cursors[0] ;  // This speeds up the loop
    for i:=1 to 6000 do begin  // 6000 is just a big number, 10 should be enough
      xx := Screen.Cursors[i]; // This makes trouble shooting easier
      if xx = yy then begin    // if Screen.Cursors[0] = Screen.Cursors[i]
        CursorID := i;         // This is an unused value
        break;
      end;
    end ;

  end; // if CursorID = 0
  if CursorID = 0 then exit; // This is just a safety, it should never exit

  Screen.Cursors[CursorID] := LoadCursor(HInstance, PChar(CursorName));
end;

The following code allows an image to be replaced with a cursor. Note that it is important to first move the mouse location to the hotspot - otherwise, the cursor will appear where the mouse clicks instead of lined up where the initial image was (ie, it looks more professional).

procedure TForm1.Image1MouseDown(Sender: TObject; Button: TMouseButton;
  Shift: TShiftState; X, Y: Integer);
var
  p : Tpoint;
begin

  p.x := 15;                       // in this case, the hotspot is 15,15
  p.y := 15;
  p   := Image1.ClientToScreen(p); // the hotspot in screen coordinates
  SetCursorPos(p.x, p.y );         // move the mouse to that position

  Screen.Cursor  := cur;           // this is the custom cursor
  Image1.Visible := false;         // hide the image
end;

procedure TForm1.Image1MouseUp(Sender: TObject; Button: TMouseButton;
  Shift: TShiftState; X, Y: Integer);
begin
  Screen.Cursor  := crDefault;
  Image1.Visible := true;
end;

Screen.Cursor is a master override - it is initially set to crDefault (zero) and each control is able to control the displayed cursor just be moving the mouse. (No extra code needed.) When Screen.Cursor is changed to another value, then that overrides the cursors associated with individual controls until it is changed back to crDefault.

Displaying the cursor on a form

Cursors and icons have almost the exact same structures. If you want to use a cursor as an image on your form, you can

Copy it to the clipboard, paste it somewhere, and save that as an icon or bitmap (too much work)
Use the Windows LoadImage function to get a handle
Get the handle from Screen.Cursors[]

Once you have a handle, simply assign it to a TIcon handle (after releasing the previous handle .. if any). The following example uses a handle from Screen.Cursors[]. At design time, just set the button's Cursor property to one of the options and this will display it.

    Button1: TButton;
    Image1 : TImage;

procedure TForm1.Button1Click(Sender: TObject);
begin
  Image1.Picture.Icon.ReleaseHandle; // required before assigning a handle
  Image1.Picture.Icon.Handle := Screen.Cursors[Button1.Cursor];
end;

Since the index is just an integer, you could also use

  Image1.Picture.Icon.Handle := Screen.Cursors[-3];      // same as crCross
  Image1.Picture.Icon.Handle := Screen.Cursors[crCross]; // built-in constant = -3

I have looked at the Delphi 5 code and Icon.ReleaseHandle decrements a reference count and frees the handle when it reaches zero. When using Screen.Cursors[] to get handles, this is probably a nit since the application will release those handles when it terminates.

Finding the hotspot

This is how to find the hotspot of a cursor. From the Windows API help file.

BOOL GetIconInfo(
  HICON hIcon,         // icon handle
  PICONINFO piconinfo  // address of icon structure
);

typedef struct _ICONINFO { // ii  
  BOOL    fIcon;  
  DWORD   xHotspot; 
  DWORD   yHotspot; 
  HBITMAP hbmMask; 
  HBITMAP hbmColor; 
} ICONINFO;

From windows.pas - as you can see, the Delphi TIconInfo field names are the same.

type
  PIconInfo = ^TIconInfo;

  {$EXTERNALSYM _ICONINFO}
  _ICONINFO = packed record
    fIcon   : BOOL;
    xHotspot: DWORD;
    yHotspot: DWORD;
    hbmMask : HBITMAP;
    hbmColor: HBITMAP;
  end;

  TIconInfo = _ICONINFO;

  {$EXTERNALSYM ICONINFO}
  ICONINFO = _ICONINFO;

This code will get the hotspot of the specified cursor.

procedure TForm1.Button4Click(Sender: TObject);
var 
  IconInfo : TIconInfo ;
begin
  GetIconInfo(Screen.Cursors[SpinEdit1.Value], IconInfo);

  SpinEdit2.Value := IconInfo.xHotspot;
  SpinEdit3.Value := IconInfo.yHotspot;
end;

Using this code, I was surprised to learn that so many Windows icons had their hotspot at 10,10 - I was expecting 0,0 and 15,15.

Using TIconInfo and CreateIconIndirect, it is possible to create a cursor from an icon - just set fIcon false and define the hotspot. If fIcon if true, then the values you enter will be ignored and the hotspot will be the center.

procedure TForm1.Button6Click(Sender: TObject);
var
  IconInfo : TIconInfo ;
  cur      : HICON;
begin
  GetIconInfo(Application.Icon.Handle, IconInfo);

  IconInfo.fIcon    := false; // required to set the hotspot away from the center
  IconInfo.xHotspot := 15;
  IconInfo.yHotspot := 15;

  cur := CreateIconIndirect(IconInfo);

  Screen.Cursors[99] := cur;
  Button6.Cursor := 99;
end;

Adding a cursor to a component

When I first added cursors to my controls, I loaded the resource in the control's constructor. Eventually, I realized that that was creating a new instance for each control on the form. The better practice is to load the resource in the initialization section and then use the stored value for each control.

implementation

var
  myCursor :integer; // this must be located before it is used

    // The control's constructor must be after the variable is defined
constructor TmyControl.Create(AOwner: TComponent);
begin
  inherited;

  FPanel        := TPanel.Create(self);
  FPanel.Cursor := myCursor;

end;

initialization

   // must be here so only one copy will be loaded
  myCursor := 0;  // 0 means create a new index value
  Local_LoadCursor(myCursor, 'myCursor');

References

Customized cursors

Explains how to define and compile a resource script (*.rc file).

Microsoft Windows Cursor and Icon - Copyright � 1996, 1994 O'Reilly & Associates, Inc.

This is a very complete description of icons and cursors - explicitly explaining the similarities and differences. Basically, the files are identical except

The header indicates icon or cursor
Cursors have hotspots, icons don't

Author: Robert Clemenzi