Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XCURSOR(3)			 Keith Packard			    XCURSOR(3)

NAME
       XCURSOR - Cursor	management library

SYNOPSIS
       #include	<X11/Xcursor/Xcursor.h>

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  cur-
       sors  exists  which  map	 to  the standard X cursor names.  Cursors can
       exist in	several	sizes and the library  automatically  picks  the  best
       size.

FUNCTIONAL OVERVIEW
       Xcursor	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 FILES
       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 fol-
       lowed 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 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:

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

   THEMES
       Xcursor (mostly)	follows	the freedesktop.org spec  for  theming	icons.
       The  default  search  path it uses is ~/.icons, /usr/local/share/icons,
       /usr/local/share/pixmaps,  /usr/local/lib/X11/icons.   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 specified	theme,
       Xcursor checks the "default" theme.

DATATYPES
       XcursorImage
	      holds a single cursor image in memory.  Each pixel in the	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	when the Xcur-
	      sorCursors is freed.  These are reference	counted	so that	multi-
	      ple 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  that  set.
	      Multiple	XcursorAnimate structures may reference	the same Xcur-
	      sorCursors; 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;

       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  additional 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 Management
       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 alloca-
	      tion, ncursor is set to zero, ref	is set to one.

   Reading and writing images.
       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	 *com-
       ments, 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 (FILE *file)
       XcursorBool  XcursorFilenameLoad	 (const	 char  *file,  XcursorComments
       **commentsp, XcursorImages **imagesp)
       XcursorBool  XcursorFilenameSaveImages  (const  char  *filename,	 const
       XcursorImages *images)
       XcursorBool  XcursorFilenameSave	 (const	 char *file, const XcursorCom-
       ments *comments,	const XcursorImages *images)
	      These parallel the stdio FILE interfaces above, but  take	 file-
	      names.

   Reading library images
       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.  If
	      'theme' is not NULL, these functions first try appending	-theme
	      to name and then name alone.

   Cursor APIs
       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.

   X Cursor Name APIs
       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.

   Display Information APIs
       XcursorBool 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 VARIABLES
       XCURSOR_PATH   This variable sets the list of paths to look for cursors
		      in.  Directories in this path are	 separated  by	colons
		      (:).

RESTRICTIONS
       Xcursor	will  probably	change	radically in the future; weak attempts
       will be made to retain some level of source-file	compatibility.

AUTHOR
       Keith Packard

X Version 11		       libXcursor 1.1.14		    XCURSOR(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONAL OVERVIEW | DATATYPES | FUNCTIONS | ENVIRONMENT VARIABLES | RESTRICTIONS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Xcursor&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help