Xcursor - Man Page

Xcursor 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 be selected automatically. Multiple cursors of the same nominal 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:

Each table of contents entry looks like:

type:	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:

There are currently two chunk types defined for cursor files; comments and images. Comments look like:

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 height
delay:	CARD32 Delay between animation frames in milliseconds
pixels:	LISTofCARD32 Packed ARGB format pixels

Xcursor (mostly) follows the freedesktop.org spec for theming icons. The default search path it uses is

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.

  Xcursor looks for a specific file, which must be one of the cursor shape names,  e.g., as used in XcursorLibraryLoadImage or XcursorLibraryShape.

• If it finds no matching cursor file in the “cursors” subdirectory, Xcursor next looks for an “index.theme” file in each theme directory to look for inherited themes. Those are lines in this format:

  Inherits = theme-name

  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.

    XcursorImage *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.

    XcursorImage *XcursorXcFileLoadImage (
    	XcursorFile 	*file,
    	int 	 size)

    XcursorImages *XcursorXcFileLoadImages (
    	XcursorFile 	*file,
    	int 	 size)

    XcursorImages *XcursorXcFileLoadAllImages (
    	XcursorFile 	*file)

    XcursorBool XcursorXcFileLoad (
    	XcursorFile 	*file,
    	XcursorComments 	**commentsp,
    	XcursorImages 	**imagesp)

    XcursorBool XcursorXcFileSave (
    	XcursorFile 	*file,
    	const XcursorComments 	*comments,
    	const XcursorImages 	*images)

These read and write cursors from an XcursorFile handle. After reading, the file pointer will be left at some random place in the file.

    XcursorImage *XcursorFileLoadImage (
    	FILE 	*file,
    	int 	 size)

    XcursorImages *XcursorFileLoadImages (
    	FILE 	*file,
    	int 	 size)

    XcursorImages *XcursorFileLoadAllImages (
    	FILE 	*file)

    XcursorBool XcursorFileLoad (
    	FILE 	*file,
    	XcursorComments 	**commentsp,
    	XcursorImages 	**imagesp)

    XcursorBool XcursorFileSaveImages (
    	FILE 	*file,
    	const XcursorImages 	*images)

    XcursorBool XcursorFileSave (
    	FILE 	*file,
    	const XcursorComments 	*comments,
    	const XcursorImages 	*images)

These read and write cursors from a stdio FILE handle. Writing flushes before returning so that any errors should be detected.

    XcursorImage *XcursorFilenameLoadImage (
    	const char 	*filename,
    	int 	 size)

    XcursorImages *XcursorFilenameLoadImages (
    	const char 	*filename,
    	int 	 size)

    XcursorImages *XcursorFilenameLoadAllImages (
    	const char 	*file)

    XcursorBool XcursorFilenameLoad (
    	const char 	*file,
    	XcursorComments 	**commentsp,
    	XcursorImages 	**imagesp)

    XcursorBool XcursorFilenameSaveImages (
    	const char 	*filename,
    	const XcursorImages 	*images)

    XcursorBool XcursorFilenameSave (
    	const char 	*file,
    	const XcursorComments 	*comments,
    	const XcursorImages 	*images)

These parallel the stdio FILE interfaces above, but take filenames.

    XcursorImage *XcursorLibraryLoadImage (
    	const char 	*name,
    	const char 	*theme,
    	int 	 size)

    XcursorImages *XcursorLibraryLoadImages (
    	const char 	*name,
    	const char 	*theme,
    	int 	 size)

These search the library path, loading the first file found of the desired size, using a private function (XcursorScanTheme) to find the appropriate theme:

• If theme is not NULL, use that.
• If theme is NULL, or if there was no match for the desired theme, use “default” for the theme name.
• If neither search succeeds, these functions return NULL.

The two functions differ by more than the number of images loaded:

• XcursorLibraryLoadImage calls XcursorFileLoadImage but
• XcursorLibraryLoadImages calls XcursorFileLoadImages, and (on success) it calls XcursorImagesSetName to associate name with the result.

    const char * XcursorLibraryPath (void)

Returns the library search path:

• If the environment variable XCURSOR_PATH is set, return that value.
• Otherwise, return the compiled-in search path.

    int XcursorLibraryShape (
    	const char 	*library)

Search Xcursor's table of cursor font names for the given “shape name” (library):

• If found, return the index into that table, multiplied by two (to account for the source- and mask-values used in an X cursor font).
• If not found, return -1.

    Cursor XcursorFilenameLoadCursor (
    	Display 	*dpy,
    	const char 	*file)

    XcursorCursors *XcursorFilenameLoadCursors (
    	Display 	*dpy,
    	const char 	*file)

These load cursors from the specified file.

    Cursor XcursorLibraryLoadCursor (
    	Display 	*dpy,
    	const char 	*name)

    XcursorCursors *XcursorLibraryLoadCursors (
    	Display 	*dpy,
    	const char 	*name)

These load cursors using the specified library name.  The theme comes from the display.

    Cursor XcursorImageLoadCursor(
    	Display 	*dpy,
    	const XcursorImage 	*image)

This creates a cursor, given the image to display. It calls XcursorSupportsARGB to decide what type of cursor to create:

• XRenderCreateCursor is used if ARGB is supported on the display, and
• XCreatePixmapCursor is used otherwise.

    Cursor XcursorImagesLoadCursor(
    	Display 	*dpy,
    	const XcursorImages 	*images)

This provides an interface for creating animated cursors, if the images array contains multiple images, and if XcursorSupportsAnim returns true. Otherwise, it calls XcursorImageLoadCursor.

    XcursorCursors *XcursorImagesLoadCursors(
    	Display 	*dpy,
    	const XcursorImages 	*images)

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.

Normally it returns the resulting array pointer. On any failure, it discards the result XcursorCursorsDestroy, and returns NULL.

    XcursorImage *XcursorShapeLoadImage (
    	unsigned int 	 shape,
    	const char 	*theme,
    	int 	 size)

    XcursorImages *XcursorShapeLoadImages (
    	unsigned int 	 shape,
    	const char 	*theme,
    	int 	 size)

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)

    XcursorCursors *XcursorShapeLoadCursors (
    	Display 	*dpy,
    	unsigned int 	 shape)

These map shape to a library name and then load the cursors.

    XcursorComment *XcursorCommentCreate (
    	XcursorUInt 	 comment_type,
    	int 	 length)

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.

    void XcursorCommentDestroy(
    	XcursorComment 	*comment)

Deallocates the given XcursorComment structure.

    XcursorComments * XcursorCommentsCreate (
    	int 	 size)

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.

    void XcursorCommentsDestroy (
    	XcursorComments 	*comments)

Deallocates the given XcursorComments structure as well as the XcursorComment structures which it points to.

    XcursorAnimate * XcursorAnimateCreate (
    	XcursorCursors 	*cursors)

Wrap the given array of cursors in a newly allocated XcursorAnimate structure, which adds a sequence number used in XcursorAnimateNext.

    void XcursorAnimateDestroy (
    	XcursorAnimate 	*animate)

Discards the given animate data, freeing both the XcursorCursors array of cursors as well as the XcursorAnimate structure.

    Cursor XcursorAnimateNext (
    	XcursorAnimate 	*animate)

Cyclically returns the next Cursor in the array, incrementing the sequence number to prepare for the next call.

The caller is responsible for displaying the series of Cursor images. Xcursor does not do that.

The X11 XCreateFontCursor and XCreateGlyphCursor functions use this part of the API to extend the X core cursors feature to use themes.

    void XcursorImageHash (
    	XImage 	*image,
    	unsigned char 	 hash[XCURSOR_BITMAP_HASH_SIZE])

Compute a hash of the image, to display when the environment variable XCURSOR_DISCOVER is set.

    void XcursorImagesSetName (
    	XcursorImages 	*images,
    	const char 	*name)

Associates the given name with the images.

    void XcursorNoticeCreateBitmap (
    	Display 	*dpy,
    	Pixmap 	 pid,
    	unsigned int 	 width,
    	unsigned int 	 height)

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.

    void XcursorNoticePutBitmap (
    	Display 	*dpy,
    	Drawable 	 draw,
    	XImage 	*image)

Update the image contents in the bitmap specified by the draw value (a Pixmap-id). The bitmap must have been created by XcursorNoticeCreateBitmap.

    Cursor XcursorTryShapeBitmapCursor (
    	Display 	*dpy,
    	Pixmap 	 source,
    	Pixmap 	 mask,
    	XColor 	*foreground,
    	XColor 	*background,
    	unsigned int 	 x,
    	unsigned int 	 y)

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.

    Cursor XcursorTryShapeCursor (
    	Display 	*dpy,
    	Font 	 source_font,
    	Font 	 mask_font,
    	unsigned int 	 source_char,
    	unsigned int 	 mask_char,
    	XColor _Xconst 	*foreground,
    	XColor _Xconst 	*background)

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

• the default size from XcursorGetDefaultSize,
• the default theme from XcursorGetTheme, and
• the source_char parameter as a shape,

Xcursor calls XcursorShapeLoadImages to load the cursor images. If successful, Xcursor uses XcursorImagesLoadCursor to load the cursor information.

    XcursorBool XcursorSupportsARGB (
    	Display 	*dpy)

Returns true if the display supports ARGB cursors. Otherwise, cursors will be mapped to a core X cursor.

    XcursorBool XcursorSupportsAnim (
    	Display 	*dpy)

Returns true if the display supports animated cursors. Otherwise, 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.

    XcursorBool XcursorGetThemeCore (
    	Display 	*dpy)

    XcursorBool XcursorSetThemeCore (
    	Display 	*dpy,
    	XcursorBool 	 theme_core)

Get or set property which tells Xcursor whether to  enable themes for core cursors.