#include <X11/Xcursor/Xcursor.h>
Cursor files are stored as a header containing a table of contents followed by a sequence of chunks. The table of contents indicates the type, subtype and position in the file of each chunk. The file header looks like:
.ta 1.0i 3.0imagic: CARD32 "Xcur" (0x58, 0x63, 0x75, 0x72) header: CARD32 bytes in this header version: CARD32 file version number ntoc: CARD32 number of toc entries toc: LISTofTOC table of contents Each table of contents entry looks like: .ta 1.0i 3.0itype: CARD32 entry type subtype: CARD32 type-specific label - size for images position: CARD32 absolute byte position of table in file
Each chunk in the file has set of common header fields followed by additional type-specific fields:
.ta 1.0i 3.0iheader: CARD32 bytes in chunk header (including type-specific fields) type: CARD32 must match type in TOC for this chunk subtype: CARD32 must match subtype in TOC for this chunk version: CARD32 version number for this chunk type
There are currently two chunk types defined for cursor files; comments and images. Comments look like:
.ta 1.0i 3.0iheader: 20 Comment headers are 20 bytes
type: 0xfffe0001 Comment type is 0xfffe0001
subtype: { 1 (COPYRIGHT), 2 (LICENSE), 3 (OTHER) }
version: 1
length: CARD32 byte length of UTF-8 string
string: LISTofCARD8 UTF-8 string
Images look like:
.ta 1.0i 3.0iheader: 36 Image headers are 36 bytes
type: 0xfffd0002 Image type is 0xfffd0002
subtype: CARD32 Image subtype is the nominal size
version: 1
width: CARD32 Must be less than or equal to 0x7fff
height: CARD32 Must be less than or equal to 0x7fff
xhot: CARD32 Must be less than or equal to width
yhot: CARD32 Must be less than or equal to height
delay: CARD32 Delay between animation frames in milliseconds
pixels: LISTofCARD32 Packed ARGB format pixels
Within each of these directories,
it searches for a directory using the theme name:
.IP • 4
Within the theme directory,
it looks for cursor files in the ``cursors'' subdirectory.
Xcursor uses the first inherited theme-name, ignoring others which may exist in a given ``index.theme'' file. If it finds an inherited theme, Xcursor searches along the path to use that as well. Xcursor ignores other keys in the ``index.theme'' file, including ``Name'' (i.e., the name which a graphical application may use as the presentation name).
More than one theme-name may be listed on the Inherits= line. The freedesktop.org spec states that list items are separated by commas. Xcursor also accepts semicolon, but translates both to colon when searching the path. Xcursor expects only one Inherits= line; the freedesktop.org spec is unclear whether multiple keys are allowed.
If no theme is set, or if no cursor is found for the specified theme anywhere along the path, Xcursor checks the ``default'' theme.
When Xcursor finds a cursor file, it stops searching. It always uses the first cursor file found while searching along the path.
.ta 1.0i 3.0i .ta 2.0i 3.0itypedef struct _XcursorImage {
XcursorDim size; /* nominal size for matching */
XcursorDim width; /* actual width */
XcursorDim height; /* actual height */
XcursorDim xhot; /* hot spot x (must be inside image) */
XcursorDim yhot; /* hot spot y (must be inside image) */
XcursorPixel *pixels; /* pointer to pixels */
} XcursorImage;
.ta 1.0i 3.0i .ta 2.0i 3.0itypedef struct _XcursorImages {
int nimage; /* number of images */
XcursorImage **images; /* array of XcursorImage pointers */
} XcursorImages;
.ta 1.0i 3.0i .ta 2.0i 3.0itypedef struct _XcursorCursors {
Display *dpy; /* Display holding cursors */
int ref; /* reference count */
int ncursor; /* number of cursors */
Cursor *cursors; /* array of cursors */
} XcursorCursors;
.ta 1.0i 3.0i .ta 2.0i 3.0itypedef struct _XcursorAnimate {
XcursorCursors *cursors; /* list of cursors to use */
int sequence; /* which cursor is next */
} XcursorAnimate;
.ta 1.0i 3.0i .ta 2.0i 3.0itypedef struct _XcursorFile {
void *closure;
int (*read) (XcursorFile *file, unsigned char *buf, int len);
int (*write) (XcursorFile *file, unsigned char *buf, int len);
int (*seek) (XcursorFile *file, long offset, int whence);
};
.ta 0.8i 3.0iXcursorImage *XcursorImageCreate (
int width,
int height)
.ta 0.8i 1.6i 2.4i 3.2i
Allocate and free images.
On allocation, the hotspot and the pixels are left uninitialized.
The size is set to the maximum of width and height.
.ta 0.8i 3.0iXcursorImages *XcursorImagesCreate (
int size)
.ta 0.8i 1.6i 2.4i 3.2i
Allocate and free arrays to hold multiple cursor images.
On allocation, nimage is set to zero.
.ta 0.8i 3.0iXcursorCursors *XcursorCursorsCreate (
Display *dpy,
int size)
.ta 0.8i 1.6i 2.4i 3.2i
Allocate and free arrays to hold multiple cursors.
On allocation, ncursor is set to zero, ref is set to one.
.ta 0.8i 3.0iXcursorImage *XcursorXcFileLoadImage (
XcursorFile *file,
int size)
.ta 0.8i 1.6i 2.4i 3.2i
These read and write cursors from an XcursorFile handle.
After reading, the file pointer will be left at some random place in the file.
.ta 0.8i 3.0iXcursorImage *XcursorFileLoadImage (
FILE *file,
int size)
.ta 0.8i 1.6i 2.4i 3.2i
These read and write cursors from a stdio FILE handle.
Writing flushes before returning so that any errors should be detected.
.ta 0.8i 3.0iXcursorImage *XcursorFilenameLoadImage (
const char *filename,
int size)
.ta 0.8i 1.6i 2.4i 3.2i
These parallel the stdio FILE interfaces above, but take filenames.
.ta 0.8i 3.0iXcursorImage *XcursorLibraryLoadImage (
const char *name,
const char *theme,
int size)
.ta 0.8i 1.6i 2.4i 3.2i
These search the library path, loading the first file found
of the desired size,
using a private function (XcursorScanTheme) to find the appropriate theme:
.ta 0.8i 3.0iconst char * XcursorLibraryPath (void)
.ta 0.8i 1.6i 2.4i 3.2i
Returns the library search path:
.ta 0.8i 3.0iint XcursorLibraryShape (
const char *library)
.ta 0.8i 1.6i 2.4i 3.2i
Search Xcursor's table of cursor font names for the given
``shape name'' (library):
.ta 0.8i 3.0iCursor XcursorFilenameLoadCursor (
Display *dpy,
const char *file)
.ta 0.8i 1.6i 2.4i 3.2i
These load cursors from the specified file.
.ta 0.8i 3.0iCursor XcursorLibraryLoadCursor (
Display *dpy,
const char *name)
.ta 0.8i 1.6i 2.4i 3.2i
These load cursors using the specified library name. The theme
comes from the display.
.ta 0.8i 3.0iCursor XcursorImageLoadCursor(
Display *dpy,
const XcursorImage *image)
.ta 0.8i 1.6i 2.4i 3.2i
This creates a cursor, given the image to display.
It calls XcursorSupportsARGB to decide what type of cursor to create:
.ta 0.8i 3.0iCursor XcursorImagesLoadCursor(
Display *dpy,
const XcursorImages *images)
.ta 0.8i 1.6i 2.4i 3.2i
This provides an interface for creating animated cursors,
if the images array contains multiple images, and
if XcursorSupportsAnim returns true.
Otherwise, it calls XcursorImageLoadCursor.
.ta 0.8i 3.0iXcursorCursors *XcursorImagesLoadCursors(
Display *dpy,
const XcursorImages *images)
.ta 0.8i 1.6i 2.4i 3.2i
This calls XcursorCursorsCreate to create an array of XcursorCursors,
to correspond to the XcursorImages images array,
and uses XcursorImageLoadCursor to load the corresponding cursor data.
.ta 0.8i 3.0iXcursorImage *XcursorShapeLoadImage (
unsigned int shape,
const char *theme,
int size)
.ta 0.8i 1.6i 2.4i 3.2i
These map shape to a library name using the standard X cursor names and
then load the images.
.ta 0.8i 3.0iCursor XcursorShapeLoadCursor (
Display *dpy,
unsigned int shape)
.ta 0.8i 1.6i 2.4i 3.2i
These map shape to a library name and then load the cursors.
.ta 0.8i 3.0iXcursorComment *XcursorCommentCreate (
XcursorUInt comment_type,
int length)
.ta 0.8i 1.6i 2.4i 3.2i
XcursorXcFileLoad uses this function to allocate an XcursorComment
structure for a single cursor.
The comment_type parameter is used as the subtype field,
e.g., COPYRIGHT.
The length is the number of bytes to allocate for the comment text.
.ta 0.8i 3.0ivoid XcursorCommentDestroy(
XcursorComment *comment)
.ta 0.8i 1.6i 2.4i 3.2i
Deallocates the given XcursorComment structure.
.ta 0.8i 3.0iXcursorComments * XcursorCommentsCreate (
int size)
.ta 0.8i 1.6i 2.4i 3.2i
XcursorXcFileLoad uses this function to allocate an index of
XcursorComment structure pointers.
The size parameter tells it how many pointers will be in the index.
.ta 0.8i 3.0ivoid XcursorCommentsDestroy (
XcursorComments *comments)
.ta 0.8i 1.6i 2.4i 3.2i
Deallocates the given XcursorComments structure
as well as the XcursorComment structures which it points to.
.ta 0.8i 3.0iXcursorAnimate * XcursorAnimateCreate (
XcursorCursors *cursors)
.ta 0.8i 1.6i 2.4i 3.2i
Wrap the given array of cursors in a newly allocated XcursorAnimate structure,
which adds a sequence number used in XcursorAnimateNext.
.ta 0.8i 3.0ivoid XcursorAnimateDestroy (
XcursorAnimate *animate)
.ta 0.8i 1.6i 2.4i 3.2i
Discards the given animate data,
freeing both the XcursorCursors array of cursors
as well as the XcursorAnimate structure.
.ta 0.8i 3.0iCursor XcursorAnimateNext (
XcursorAnimate *animate)
.ta 0.8i 1.6i 2.4i 3.2i
Cyclically returns the next Cursor in the array,
incrementing the sequence number to prepare for the next call.
.ta 0.8i 3.0ivoid XcursorImageHash (
XImage *image,
unsigned char hash[XCURSOR_BITMAP_HASH_SIZE])
.ta 0.8i 1.6i 2.4i 3.2i
Compute a hash of the image,
to display when the environment variable XCURSOR_DISCOVER is set.
.ta 0.8i 3.0ivoid XcursorImagesSetName (
XcursorImages *images,
const char *name)
.ta 0.8i 1.6i 2.4i 3.2i
Associates the given name with the images.
.ta 0.8i 3.0ivoid XcursorNoticeCreateBitmap (
Display *dpy,
Pixmap pid,
unsigned int width,
unsigned int height)
.ta 0.8i 1.6i 2.4i 3.2i
Check if the display supports either ARGB or themes,
and also if the image size fits within the maximum cursor size (64 pixels).
If so, create a bitmap of the specified size,
and cache the result in Xcursor,
identifying it with the Pixmap-id (pid) value.
.ta 0.8i 3.0ivoid XcursorNoticePutBitmap (
Display *dpy,
Drawable draw,
XImage *image)
.ta 0.8i 1.6i 2.4i 3.2i
Update the image contents in the bitmap specified by the draw value
(a Pixmap-id).
The bitmap must have been created by XcursorNoticeCreateBitmap.
.ta 0.8i 3.0iCursor XcursorTryShapeBitmapCursor (
Display *dpy,
Pixmap source,
Pixmap mask,
XColor *foreground,
XColor *background,
unsigned int x,
unsigned int y)
.ta 0.8i 1.6i 2.4i 3.2i
If the display supports either ARGB or themes,
try to load a cursor into Xcursor's cache
using the source parameter as a Pixmap-id.
The source may no longer be in the cache.
Xcursor uses the hash value to identify the desired image.
.ta 0.8i 3.0iCursor XcursorTryShapeCursor (
Display *dpy,
Font source_font,
Font mask_font,
unsigned int source_char,
unsigned int mask_char,
XColor _Xconst *foreground,
XColor _Xconst *background)
.ta 0.8i 1.6i 2.4i 3.2i
If the display supports either ARGB or themes,
try to load a cursor into Xcursor's cache
using the source_char parameter as a shape.
Using
.ta 0.8i 3.0iXcursorBool XcursorSupportsARGB (
Display *dpy)
.ta 0.8i 1.6i 2.4i 3.2i
Returns true if the display supports ARGB cursors.
Otherwise, cursors will be mapped to a core X cursor.
.ta 0.8i 3.0iXcursorBool XcursorSupportsAnim (
Display *dpy)
.ta 0.8i 1.6i 2.4i 3.2i
Returns true if the display supports animated cursors.
Otherwise, cursors will be mapped to a core X cursor.
.ta 0.8i 3.0iXcursorBool XcursorSetDefaultSize (
Display *dpy,
int size)
.ta 0.8i 1.6i 2.4i 3.2i
Sets the default size for cursors on the specified display.
When loading cursors,
those whose nominal size is closest to this size will be preferred.
.ta 0.8i 3.0iint XcursorGetDefaultSize (
Display *dpy)
.ta 0.8i 1.6i 2.4i 3.2i
Gets the default cursor size.
.ta 0.8i 3.0iXcursorBool XcursorSetTheme (
Display *dpy,
const char *theme)
.ta 0.8i 1.6i 2.4i 3.2i
Sets the current theme name.
.ta 0.8i 3.0ichar *XcursorGetTheme (
Display *dpy)
.ta 0.8i 1.6i 2.4i 3.2i
Gets the current theme name.
.ta 0.8i 3.0iXcursorBool XcursorGetThemeCore (
Display *dpy)
.ta 0.8i 1.6i 2.4i 3.2i
Get or set property which tells Xcursor whether to
enable themes for core cursors.
Some of the environment variables recognized by Xcursor are booleans, specified as follows:
Xcursor ignores other values for these booleans.
as well as