1XCURSOR(3) Keith Packard XCURSOR(3)
2
6 XCURSOR - Cursor management library
7
10 #include <X11/Xcursor/Xcursor.h>
11
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
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 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 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 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 Each table of contents entry looks like:
51 type: CARD32 entry type
53 subtype: CARD32 type-specific label - size for images
54 position: CARD32 absolute byte position of table in file
55 Each chunk in the file has set of common header fields followed by
57 additional type-specific fields:
58 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 There are currently two chunk types defined for cursor files; comments
65 and images. Comments look like:
66 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 Images look like:
75 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 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 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 If no theme is set, or if no cursor is found for the specified theme,
101 Xcursor checks the "default" theme.
102
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 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 XcursorImages
120 holds multiple XcursorImage structures. They're all freed when
121 the XcursorImages is freed.
122 typedef struct _XcursorImages {
124 int nimage; /∗ number of images */
125 XcursorImage **images; /∗ array of XcursorImage pointers */
126 } XcursorImages;
127 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 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 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 typedef struct _XcursorAnimate {
149 XcursorCursors *cursors; /∗ list of cursors to use */
150 int sequence; /∗ which cursor is next */
151 } XcursorAnimate;
152 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 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
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 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 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 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 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 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 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 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 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 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 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 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 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 int XcursorGetDefaultSize (Display *dpy)
283 Gets the default cursor size.
284 XcursorBool XcursorSetTheme (Display *dpy, const char *theme)
287 Sets the current theme name.
288 char *XcursorGetTheme (Display *dpy)
291 Gets the current theme name.
292
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
301 Xcursor will probably change radically in the future; weak attempts
302 will be made to retain some level of source-file compatibility.
303
306 Keith Packard
307X Version 11 libXcursor 1.1.14 XCURSOR(3)