Undocumented Goodness: CGSSetSystemDefinedCursor

2010-04-03 22:52:10 UTC

As with all undocumented private APIs, this one may change or go away any time. Use with extreme caution or, better yet, not at all.

As you’d expect from a CGS function, you’ll need a CGSConnection to use this one:

typedef void *CGSConnectionRef;
extern CGSConnectionRef _CGSDefaultConnection(void);
extern unsigned CGSSetSystemDefinedCursor(CGSConnectionRef connection, unsigned cursorID);

(I am, of course, not sure of the correct type for cursorID, although it is 32-bit.)

The valid cursor IDs range from 0 to 8; for anything else, CGSSetSystemDefinedCursor returns kCGErrorIllegalArgument. You’ll also get that error if you pass a bogus connection ref.

Here are the cursor IDs, as I’ve named them:

enum {
    kCGCursorIDArrow,
    kCGCursorIDIBeamComposite,
    kCGCursorIDIBeamInvert,
    kCGCursorIDLink,
    kCGCursorIDCopy,
    kCGCursorIDArrowWhite,
    kCGCursorIDContextualMenu,
    kCGCursorIDPinwheel,
    kCGCursorIDHidden,
};

IBeamComposite is the normal I-beam cursor. IBeamInvert is a variation that inverts what’s underneath it, instead of compositing over it. The benefit is that this shows up well on dark backgrounds (it appears white), whereas IBeamComposite blends in.

Link and Copy are the Mac OS 8.5 versions of those cursors, not the larger full-color ones introduced in Mac OS X 10.2.

ArrowWhite is exactly what it says on the box: A white-with-black-outline version of the standard Mac arrow cursor. The colors of the Windows arrow cursor with the stem length of the Mac arrow cursor.

ContextualMenu is my rough interpretation, as the stack of white rectangles next to the (black) arrow cursor looks only vaguely like a series of menu items. To my eyes, it looks more like a stack of giant hard disk platters (like the standard icon for a database that has become common recently) than a contextual menu, but I doubt that this was what they meant. This is not the contextual menu cursor from Mac OS 8 and 9.

Pinwheel is exactly what it says on the box. It’s even animated. This is the prize of the collection: If you ever want to deliberately put on the pinwheel cursor (which you should NEVER EVER DO), this is the way to do it.

Hidden is also exactly what it says on the box: A fully-transparent cursor image.

So, there you go, for your information, entertainment, and hopefully not use.

2 Responses to “Undocumented Goodness: CGSSetSystemDefinedCursor”

  1. Uli Kusterer Says:

    So “pinwheel” is the colorful beach-ball cursor, also known as the Spinning Pizza of Death? Or is it the blue-and-white one that Java shows?

  2. Peter Hosey Says:

    It’s the colorful (and distinctly non-pizza-like) cursor. I don’t think I’ve ever seen the blue-and-white one.

Leave a Reply

Do not delete the second sentence.