1XCURSOR(3)                 Library Functions Manual                 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 $HOME/.icons, /usr/share/icons,
91       /usr/share/pixmaps, /usr/share/icons.  Within each  of  these  directo‐
92       ries,  it  searches  for  a directory using the theme name.  Within the
93       theme directory, it looks for cursor files in the  'cursors'  subdirec‐
94       tory.  It uses the first cursor 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       XcursorImage *XcursorFileLoadImage (FILE *file, int size)
204       XcursorImages *XcursorFileLoadImages (FILE *file, int size)
205       XcursorImages *XcursorFileLoadAllImages (FILE *file)
206       XcursorBool XcursorFileLoad (FILE *file,  XcursorComments  **commentsp,
207       XcursorImages **imagesp)
208       XcursorBool  XcursorFileSaveImages  (FILE  *file,  const  XcursorImages
209       *images)
210       XcursorBool XcursorFileSave (FILE * file, const  XcursorComments  *com‐
211       ments, const XcursorImages *images)
212              These  read and write cursors from a stdio FILE handle.  Writing
213              flushes before returning so that any errors should be detected.
214
215
216       XcursorImage *XcursorFilenameLoadImage (const char *filename, int size)
217       XcursorImages *XcursorFilenameLoadImages  (const  char  *filename,  int
218       size)
219       XcursorImages *XcursorFilenameLoadAllImages (FILE *file)
220       XcursorBool  XcursorFilenameLoad  (const  char  *file,  XcursorComments
221       **commentsp, XcursorImages **imagesp)
222       XcursorBool  XcursorFilenameSaveImages  (const  char  *filename,  const
223       XcursorImages *images)
224       XcursorBool  XcursorFilenameSave  (const  char *file, const XcursorCom‐
225       ments *comments, const XcursorImages *images)
226              These parallel the stdio FILE interfaces above, but  take  file‐
227              names.
228
229
230   Reading library images
231       XcursorImage  *XcursorLibraryLoadImage  (const  char  *name, const char
232       *theme, int size)
233       XcursorImages *XcursorLibraryLoadImages (const char *name,  const  char
234       *theme, int size)
235              These search the library path, loading the first file found.  If
236              'theme' is not NULL, these functions first try appending  -theme
237              to name and then name alone.
238
239
240   Cursor APIs
241       Cursor XcursorFilenameLoadCursor (Display *dpy, const char *file)
242       XcursorCursors  *XcursorFilenameLoadCursors  (Display  *dpy, const char
243       *file)
244              These load cursors from the specified file.
245
246
247       Cursor XcursorLibraryLoadCursor (Display *dpy, const char *name)
248       XcursorCursors *XcursorLibraryLoadCursors  (Display  *dpy,  const  char
249       *name)
250              These  load cursors using the specified library name.  The theme
251              comes from the display.
252
253
254   X Cursor Name APIs
255       XcursorImage *XcursorShapeLoadImage (unsigned  int  shape,  const  char
256       *theme, int size)
257       XcursorImages  *XcursorShapeLoadImages  (unsigned int shape, const char
258       *theme, int size)
259              These map 'shape' to a library name using the standard X  cursor
260              names and then load the images.
261
262
263       Cursor XcursorShapeLoadCursor (Display *dpy, unsigned int shape)
264       XcursorCursors  *XcursorShapeLoadCursors  (Display  *dpy,  unsigned int
265       shape)
266              These map 'shape' to a library name and then load the cursors.
267
268
269   Display Information APIs
270       XcursorBool XcursorSupportsARGB (Display *dpy)
271              Returns whether the display supports  ARGB  cursors  or  whether
272              cursors will be mapped to a core X cursor.
273
274
275       XcursorBool XcursorSetDefaultSize (Display *dpy, int size)
276              Sets the default size for cursors on the specified display. When
277              loading cursors, those who's nominal size  is  closest  to  this
278              size will be preferred.
279
280
281       int XcursorGetDefaultSize (Display *dpy)
282              Gets the default cursor size.
283
284
285       XcursorBool XcursorSetTheme (Display *dpy, const char *theme)
286              Sets the current theme name.
287
288
289       char *XcursorGetTheme (Display *dpy)
290              Gets the current theme name.
291
292

RESTRICTIONS

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

AUTHOR

299       Keith Packard
300
301
302
303Keith Packard                  libXcursor 1.1.8                     XCURSOR(3)
Impressum