1XCURSOR(3)                       Keith Packard                      XCURSOR(3)
2
3
4

NAME

6       XCURSOR - Cursor management library
7
8

SYNOPSIS

10       #include <X11/Xcursor/Xcursor.h>
11

DESCRIPTION

13       Xcursor  is  a simple library designed to help locate and load cursors.
14       Cursors can be loaded from files or memory.  A library of  common  cur‐
15       sors  exists  which  map  to  the standard X cursor names.  Cursors can
16       exist in several sizes and the library  automatically  picks  the  best
17       size.
18
19

FUNCTIONAL OVERVIEW

21       Xcursor  is  built  in  a couple of layers; at the bottom layer is code
22       which can load cursor images from files.  Above that is a  layer  which
23       locates  cursor  files based on the library path and theme.  At the top
24       is a layer which builds cursors either out of an image  loaded  from  a
25       file  or  one of the standard X cursors.  When using images loaded from
26       files, Xcursor prefers to use the Render extension CreateCursor request
27       if  supported  by  the X server.  Where not supported, Xcursor maps the
28       cursor image to a standard X cursor  and  uses  the  core  CreateCursor
29       request.
30
31
32   CURSOR FILES
33       Xcursor  defines a new format for cursors on disk.  Each file holds one
34       or more cursor images.  Each cursor image is tagged with a nominal size
35       so  that the best size can be selected automatically.  Multiple cursors
36       of the same nominal size  can  be  loaded  together;  applications  are
37       expected to use them as an animated sequence.
38
39       Cursor files are stored as a header containing a table of contents fol‐
40       lowed by a sequence of chunks.  The table  of  contents  indicates  the
41       type,  subtype and position in the file of each chunk.  The file header
42       looks like:
43
44         magic: CARD32 'Xcur' (0x58, 0x63, 0x75, 0x72)
45         header: CARD32 bytes in this header
46         version: CARD32 file version number
47         ntoc: CARD32 number of toc entries
48         toc: LISTofTOC table of contents
49
50       Each table of contents entry looks like:
51
52         type: CARD32 entry type
53         subtype: CARD32 type-specific label - size for images
54         position: CARD32 absolute byte position of table in file
55
56       Each chunk in the file has set of  common  header  fields  followed  by
57       additional type-specific fields:
58
59         header: CARD32 bytes in chunk header (including type-specific fields)
60         type: CARD32 must match type in TOC for this chunk
61         subtype: CARD32 must match subtype in TOC for this chunk
62         version: CARD32 version number for this chunk type
63
64       There  are currently two chunk types defined for cursor files; comments
65       and images.  Comments look like:
66
67         header: 20 Comment headers are 20 bytes
68         type: 0xfffe0001 Comment type is 0xfffe0001
69         subtype: { 1 (COPYRIGHT), 2 (LICENSE), 3 (OTHER) }
70         version: 1
71         length: CARD32 byte length of UTF-8 string
72         string: LISTofCARD8 UTF-8 string
73
74       Images look like:
75
76         header: 36 Image headers are 36 bytes
77         type: 0xfffd0002 Image type is 0xfffd0002
78         subtype: CARD32 Image subtype is the nominal size
79         version: 1
80         width: CARD32 Must be less than or equal to 0x7fff
81         height: CARD32 Must be less than or equal to 0x7fff
82         xhot: CARD32 Must be less than or equal to width
83         yhot: CARD32 Must be less than or equal to height
84         delay: CARD32 Delay between animation frames in milliseconds
85         pixels: LISTofCARD32 Packed ARGB format pixels
86
87
88   THEMES
89       Xcursor (mostly) follows the freedesktop.org spec  for  theming  icons.
90       The   default  search  path  it  uses  is  ~/.icons,  /usr/share/icons,
91       /usr/share/pixmaps.  Within each of these directories, it searches  for
92       a directory using the theme name.  Within the theme directory, it looks
93       for cursor files in the 'cursors' subdirectory.  It uses the first cur‐
94       sor file found along  the path.
95
96       If necessary, Xcursor also looks for a "index.theme" file in each theme
97       directory to find inherited themes and  searches  along  the  path  for
98       those themes as well.
99
100       If  no  theme is set, or if no cursor is found for the specified theme,
101       Xcursor checks the "default" theme.
102
103

DATATYPES

105       XcursorImage
106              holds a single cursor image in memory.  Each pixel in the cursor
107              is a 32-bit value containing ARGB with A in the high byte.
108
109                  typedef struct _XcursorImage {
110                      XcursorDim  size;         /∗ nominal size for matching */
111                      XcursorDim  width;        /∗ actual width */
112                      XcursorDim  height;       /∗ actual height */
113                      XcursorDim  xhot;         /∗ hot spot x (must be inside image) */
114                      XcursorDim  yhot;       /∗ hot spot y (must be inside image) */
115                      XcursorPixel    *pixels;    /∗ pointer to pixels */
116                  } XcursorImage;
117
118
119       XcursorImages
120              holds  multiple XcursorImage structures.  They're all freed when
121              the XcursorImages is freed.
122
123                  typedef struct _XcursorImages {
124                      int             nimage;        /∗ number of images */
125                      XcursorImage    **images;   /∗ array of XcursorImage pointers */
126                  } XcursorImages;
127
128
129       XcursorCursors
130              Holds multiple Cursor objects.  They're all freed when the Xcur‐
131              sorCursors is freed.  These are reference counted so that multi‐
132              ple XcursorAnimate structures can use the same XcursorCursors.
133
134                  typedef struct _XcursorCursors {
135                      Display     *dpy;     /∗ Display holding cursors */
136                      int        ref;  /∗ reference count */
137                      int        ncursor;   /∗ number of cursors */
138                      Cursor     *cursors;  /∗ array of cursors */
139                  } XcursorCursors;
140
141
142       XcursorAnimate
143              References a set of cursors and  a  sequence  within  that  set.
144              Multiple  XcursorAnimate structures may reference the same Xcur‐
145              sorCursors; each holds a reference which  is  removed  when  the
146              XcursorAnimate is freed.
147
148                  typedef struct _XcursorAnimate {
149                      XcursorCursors   *cursors;  /∗ list of cursors to use */
150                      int          sequence;  /∗ which cursor is next */
151                  } XcursorAnimate;
152
153
154       XcursorFile
155              Xcursor  provides  an  abstract API for accessing the file data.
156              Xcursor provides a stdio implementation of  this  abstract  API;
157              applications  are  free  to  create  additional implementations.
158              These functions parallel the stdio functions in return value and
159              expected  argument values; the read and write functions flip the
160              arguments around to match the POSIX versions.
161
162                  typedef struct _XcursorFile {
163                      void   *closure;
164                      int    (*read)  (XcursorFile *file, unsigned char *buf, int len);
165                      int    (*write) (XcursorFile *file, unsigned char *buf, int len);
166                      int    (*seek)  (XcursorFile *file, long offset, int whence);
167                  };
168
169

FUNCTIONS

171   Object Management
172       XcursorImage *XcursorImageCreate (int width, int height)
173       void XcursorImageDestroy (XcursorImage *image)
174              Allocate and free images.  On allocation, the  hotspot  and  the
175              pixels  are  left uninitialized.  The size is set to the maximum
176              of width and height.
177
178
179       XcursorImages *XcursorImagesCreate (int size)
180       void XcursorImagesDestroy (XcursorImages *images)
181              Allocate and free arrays to hold  multiple  cursor  images.   On
182              allocation, nimage is set to zero.
183
184
185       XcursorCursors *XcursorCursorsCreate (Display *dpy, int size)
186       void XcursorCursorsDestroy (XcursorCursors *cursors)
187              Allocate  and  free arrays to hold multiple cursors.  On alloca‐
188              tion, ncursor is set to zero, ref is set to one.
189
190
191   Reading and writing images.
192       XcursorImage *XcursorXcFileLoadImage (XcursorFile *file, int size)
193       XcursorImages *XcursorXcFileLoadImages (XcursorFile *file, int size)
194       XcursorImages *XcursorXcFileLoadAllImages (XcursorFile *file)
195       XcursorBool  XcursorXcFileLoad  (XcursorFile   *file,   XcursorComments
196       **commentsp, XcursorImages **imagesp)
197       XcursorBool XcursorXcFileSave (XcursorFile *file, const XcursorComments
198       *comments, const XcursorImages *images)
199              These read and write cursors from an XcursorFile handle.   After
200              reading,  the  file pointer will be left at some random place in
201              the file.
202
203
204       XcursorImage *XcursorFileLoadImage (FILE *file, int size)
205       XcursorImages *XcursorFileLoadImages (FILE *file, int size)
206       XcursorImages *XcursorFileLoadAllImages (FILE *file)
207       XcursorBool XcursorFileLoad (FILE *file,  XcursorComments  **commentsp,
208       XcursorImages **imagesp)
209       XcursorBool  XcursorFileSaveImages  (FILE  *file,  const  XcursorImages
210       *images)
211       XcursorBool XcursorFileSave (FILE * file, const  XcursorComments  *com‐
212       ments, const XcursorImages *images)
213              These  read and write cursors from a stdio FILE handle.  Writing
214              flushes before returning so that any errors should be detected.
215
216
217       XcursorImage *XcursorFilenameLoadImage (const char *filename, int size)
218       XcursorImages *XcursorFilenameLoadImages  (const  char  *filename,  int
219       size)
220       XcursorImages *XcursorFilenameLoadAllImages (FILE *file)
221       XcursorBool  XcursorFilenameLoad  (const  char  *file,  XcursorComments
222       **commentsp, XcursorImages **imagesp)
223       XcursorBool  XcursorFilenameSaveImages  (const  char  *filename,  const
224       XcursorImages *images)
225       XcursorBool  XcursorFilenameSave  (const  char *file, const XcursorCom‐
226       ments *comments, const XcursorImages *images)
227              These parallel the stdio FILE interfaces above, but  take  file‐
228              names.
229
230
231   Reading library images
232       XcursorImage  *XcursorLibraryLoadImage  (const  char  *name, const char
233       *theme, int size)
234       XcursorImages *XcursorLibraryLoadImages (const char *name,  const  char
235       *theme, int size)
236              These search the library path, loading the first file found.  If
237              'theme' is not NULL, these functions first try appending  -theme
238              to name and then name alone.
239
240
241   Cursor APIs
242       Cursor XcursorFilenameLoadCursor (Display *dpy, const char *file)
243       XcursorCursors  *XcursorFilenameLoadCursors  (Display  *dpy, const char
244       *file)
245              These load cursors from the specified file.
246
247
248       Cursor XcursorLibraryLoadCursor (Display *dpy, const char *name)
249       XcursorCursors *XcursorLibraryLoadCursors  (Display  *dpy,  const  char
250       *name)
251              These  load cursors using the specified library name.  The theme
252              comes from the display.
253
254
255   X Cursor Name APIs
256       XcursorImage *XcursorShapeLoadImage (unsigned  int  shape,  const  char
257       *theme, int size)
258       XcursorImages  *XcursorShapeLoadImages  (unsigned int shape, const char
259       *theme, int size)
260              These map 'shape' to a library name using the standard X  cursor
261              names and then load the images.
262
263
264       Cursor XcursorShapeLoadCursor (Display *dpy, unsigned int shape)
265       XcursorCursors  *XcursorShapeLoadCursors  (Display  *dpy,  unsigned int
266       shape)
267              These map 'shape' to a library name and then load the cursors.
268
269
270   Display Information APIs
271       XcursorBool XcursorSupportsARGB (Display *dpy)
272              Returns whether the display supports  ARGB  cursors  or  whether
273              cursors will be mapped to a core X cursor.
274
275
276       XcursorBool XcursorSetDefaultSize (Display *dpy, int size)
277              Sets the default size for cursors on the specified display. When
278              loading cursors, those whose nominal size  is  closest  to  this
279              size will be preferred.
280
281
282       int XcursorGetDefaultSize (Display *dpy)
283              Gets the default cursor size.
284
285
286       XcursorBool XcursorSetTheme (Display *dpy, const char *theme)
287              Sets the current theme name.
288
289
290       char *XcursorGetTheme (Display *dpy)
291              Gets the current theme name.
292
293

ENVIRONMENT VARIABLES

295       XCURSOR_PATH   This variable sets the list of paths to look for cursors
296                      in.  Directories in this path are  separated  by  colons
297                      (:).
298
299

RESTRICTIONS

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

AUTHOR

306       Keith Packard
307
308
309
310X Version 11                   libXcursor 1.1.15                    XCURSOR(3)
Impressum