Misc. Reference Manual Pages XCURSOR(3xcursor)
NAME
XCURSOR - Cursor management library
SYNOPSIS
cc [ flag... ] file... -lXcursor [ library... ]
#include
DESCRIPTION
Xcursor is a simple library designed to help locate and load
cursors. Cursors can be loaded from files or memory. A library of common cursors exists which map to the standard X cursor names. Cursors can exist in several sizes and the library automatically picks the best size. FUNCTIONAL OVERVIEWXcursor is built in a couple of layers; at the bottom layer
is code which can load cursor images from files. Above that is a layer which locates cursor files based on the library path and theme. At the top is a layer which builds cursors either out of an image loaded from a file or one of the standard X cursors. When using images loaded from files,Xcursor prefers to use the Render extension CreateCursor
request if supported by the X server. Where not supported,Xcursor maps the cursor image to a standard X cursor and
uses the core CreateCursor request. CURSOR FILESXcursor defines a new format for cursors on disk. Each file
holds one or more cursor images. Each cursor image is tagged with a nominal size so that the best size can beselected automatically. Multiple cursors of the same nomi-
nal size can be loaded together; applications are expected to use them as an animated sequence. 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: magic: 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: type: CARD32 entry typesubtype: CARD32 type-specific label - size for images
Keith Packard Last change: libXcursor 1.1.10 1
Misc. Reference Manual Pages XCURSOR(3xcursor) position: CARD32 absolute byte position of table in fileEach chunk in the file has set of common header fields fol-
lowed by additional type-specific fields:
header: 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: header: 20 Comment headers are 20 bytes type: 0xfffe0001 Comment type is 0xfffe0001 subtype: { 1 (COPYRIGHT), 2 (LICENSE), 3 (OTHER) } version: 1length: CARD32 byte length of UTF-8 string
string: LISTofCARD8 UTF-8 string
Images look like: header: 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 heightdelay: CARD32 Delay between animation frames in mil-
liseconds pixels: LISTofCARD32 Packed ARGB format pixels THEMESXcursor (mostly) follows the freedesktop.org spec for them-
ing icons. The default search path it uses is ~/.icons, /usr/share/icons, /usr/share/pixmaps. Within each of these directories, it searches for a directory using the theme name. Within the theme directory, it looks for cursor files in the 'cursors' subdirectory. It uses the first cursor file found along the path.If necessary, Xcursor also looks for a "index.theme" file in
each theme directory to find inherited themes and searches along the path for those themes as well.If no theme is set, or if no cursor is found for the speci-
fied theme, Xcursor checks the "default" theme.
Keith Packard Last change: libXcursor 1.1.10 2
Misc. Reference Manual Pages XCURSOR(3xcursor) DATATYPESXcursorImage
holds a single cursor image in memory. Each pixel inthe cursor is a 32-bit value containing ARGB with A in
the high byte.typedef 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;
XcursorImages
holds multiple XcursorImage structures. They're all
freed when the XcursorImages is freed.
typedef struct _XcursorImages {
int nimage; /* number of images */XcursorImage **images; /* array of XcursorImage pointers */
} XcursorImages;
XcursorCursors
Holds multiple Cursor objects. They're all freed whenthe XcursorCursors is freed. These are reference
counted so that multiple XcursorAnimate structures can
use the same XcursorCursors.
typedef struct _XcursorCursors {
Display *dpy; /* Display holding cursors */ int ref; /* reference count */ int ncursor; /* number of cursors */ Cursor *cursors; /* array of cursors */} XcursorCursors;
XcursorAnimate
References a set of cursors and a sequence within thatset. Multiple XcursorAnimate structures may reference
the same XcursorCursors; each holds a reference which
is removed when the XcursorAnimate is freed.
typedef struct _XcursorAnimate {
XcursorCursors *cursors; /* list of cursors to use */
int sequence; /* which cursor is next */} XcursorAnimate;
Keith Packard Last change: libXcursor 1.1.10 3
Misc. Reference Manual Pages XCURSOR(3xcursor)XcursorFile
Xcursor provides an abstract API for accessing the file
data. Xcursor provides a stdio implementation of this
abstract API; applications are free to create addi-
tional implementations. These functions parallel the stdio functions in return value and expected argument values; the read and write functions flip the arguments around to match the POSIX versions.typedef 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);
}; FUNCTIONS Object ManagementXcursorImage *XcursorImageCreate (int width, int height)
void XcursorImageDestroy (XcursorImage *image)
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.XcursorImages *XcursorImagesCreate (int size)
void XcursorImagesDestroy (XcursorImages *images)
Allocate and free arrays to hold multiple cursor images. On allocation, nimage is set to zero.XcursorCursors *XcursorCursorsCreate (Display *dpy, int size)
void XcursorCursorsDestroy (XcursorCursors *cursors)
Allocate and free arrays to hold multiple cursors. On allocation, ncursor is set to zero, ref is set to one. Reading and writing images. size)XcursorImage *XcursorXcFileLoadImage (XcursorFile *file, int
size)XcursorImages *XcursorXcFileLoadImages (XcursorFile *file, int
XcursorImages *XcursorXcFileLoadAllImages (XcursorFile *file)
**commentsp, XcursorImages **imagesp)
XcursorBool XcursorXcFileLoad (XcursorFile *file, XcursorComments
Comments *comments, const XcursorImages *images)
XcursorBool XcursorXcFileSave (XcursorFile *file, const Xcursor-
These read and write cursors from an XcursorFile han-
dle. After reading, the file pointer will be left at some random place in the file.Keith Packard Last change: libXcursor 1.1.10 4
Misc. Reference Manual Pages XCURSOR(3xcursor)XcursorImage *XcursorFileLoadImage (FILE *file, int size)
XcursorImages *XcursorFileLoadImages (FILE *file, int size)
XcursorImages *XcursorFileLoadAllImages (FILE *file)
mentsp, XcursorImages **imagesp)
XcursorBool XcursorFileLoad (FILE *file, XcursorComments **com-
ages *images)XcursorBool XcursorFileSaveImages (FILE *file, const XcursorIm-
*comments, const XcursorImages *images)
XcursorBool XcursorFileSave (FILE * file, const XcursorComments
These read and write cursors from a stdio FILE handle. Writing flushes before returning so that any errors should be detected. size)XcursorImage *XcursorFilenameLoadImage (const char *filename, int
int size)XcursorImages *XcursorFilenameLoadImages (const char *filename,
XcursorImages *XcursorFilenameLoadAllImages (FILE *file)
ments **commentsp, XcursorImages **imagesp)
XcursorBool XcursorFilenameLoad (const char *file, XcursorCom-
const XcursorImages *images)
XcursorBool XcursorFilenameSaveImages (const char *filename,
Comments *comments, const XcursorImages *images)
XcursorBool XcursorFilenameSave (const char *file, const Xcursor-
These parallel the stdio FILE interfaces above, but take filenames. Reading library images char *theme, int size)XcursorImage *XcursorLibraryLoadImage (const char *name, const
char *theme, int size)XcursorImages *XcursorLibraryLoadImages (const char *name, const
These search the library path, loading the first file found. If 'theme' is not NULL, these functions firsttry appending -theme to name and then name alone.
Cursor APIsCursor XcursorFilenameLoadCursor (Display *dpy, const char *file)
char *file)XcursorCursors *XcursorFilenameLoadCursors (Display *dpy, const
These load cursors from the specified file.Cursor XcursorLibraryLoadCursor (Display *dpy, const char *name)
char *name)XcursorCursors *XcursorLibraryLoadCursors (Display *dpy, const
These load cursors using the specified library name. The theme comes from the display.Keith Packard Last change: libXcursor 1.1.10 5
Misc. Reference Manual Pages XCURSOR(3xcursor) X Cursor Name APIs char *theme, int size)XcursorImage *XcursorShapeLoadImage (unsigned int shape, const
char *theme, int size)XcursorImages *XcursorShapeLoadImages (unsigned int shape, const
These map 'shape' to a library name using the standard X cursor names and then load the images.Cursor XcursorShapeLoadCursor (Display *dpy, unsigned int shape)
int shape)XcursorCursors *XcursorShapeLoadCursors (Display *dpy, unsigned
These map 'shape' to a library name and then load the cursors. Display Information APIsXcursorBool XcursorSupportsARGB (Display *dpy)
Returns whether the display supports ARGB cursors or whether cursors will be mapped to a core X cursor.XcursorBool XcursorSetDefaultSize (Display *dpy, int size)
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.int XcursorGetDefaultSize (Display *dpy)
Gets the default cursor size.XcursorBool XcursorSetTheme (Display *dpy, const char *theme)
Sets the current theme name.char *XcursorGetTheme (Display *dpy)
Gets the current theme name. ENVIRONMENT VARIABLESXCURSOR_PATH This variable sets the list of paths to look
for cursors in. Directories in this path are separated by colons (:). RESTRICTIONSXcursor will probably change radically in the future; weak
attempts will be made to retain some level of source-file
compatibility.Keith Packard Last change: libXcursor 1.1.10 6
Misc. Reference Manual Pages XCURSOR(3xcursor) AUTHOR Keith PackardATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | x11/library/libxcursor ||_____________________________|_____________________________|
| Interface Stability | Uncommitted ||_____________________________|_____________________________|
| MT-Level | See XInitThreads(3X11) |
|_____________________________|_____________________________|
Keith Packard Last change: libXcursor 1.1.10 7