1XCURSOR(3) X Version 11 XCURSOR(3)
2
6 Xcursor - Cursor management library
7
9 #include <X11/Xcursor/Xcursor.h>
10
12 Xcursor is a simple library designed to help locate and load cursors.
13 Cursors can be loaded from files or memory. A library of common
14 cursors exists which map to the standard X cursor names. Cursors can
15 exist in several sizes and the library automatically picks the best
16 size.
17
19 Xcursor is built in a couple of layers; at the bottom layer is code
20 which can load cursor images from files. Above that is a layer which
21 locates cursor files based on the library path and theme. At the top
22 is a layer which builds cursors either out of an image loaded from a
23 file or one of the standard X cursors. When using images loaded from
24 files, Xcursor prefers to use the Render extension CreateCursor request
25 if supported by the X server. Where not supported, Xcursor maps the
26 cursor image to a standard X cursor and uses the core CreateCursor
27 request.
28 CURSOR FILES
30 Xcursor defines a new format for cursors on disk. Each file holds one
31 or more cursor images. Each cursor image is tagged with a nominal size
32 so that the best size can be selected automatically. Multiple cursors
33 of the same nominal size can be loaded together; applications are
34 expected to use them as an animated sequence.
35 Cursor files are stored as a header containing a table of contents
37 followed by a sequence of chunks. The table of contents indicates the
38 type, subtype and position in the file of each chunk. The file header
39 looks like:
40 magic: CARD32 "Xcur" (0x58, 0x63, 0x75, 0x72)
42 header: CARD32 bytes in this header
43 version: CARD32 file version number
44 ntoc: CARD32 number of toc entries
45 toc: LISTofTOC table of contents
46 Each table of contents entry looks like:
48 type: CARD32 entry type
50 subtype: CARD32 type-specific label - size for images
51 position: CARD32 absolute byte position of table in file
52 Each chunk in the file has set of common header fields followed by
54 additional type-specific fields:
55 header: CARD32 bytes in chunk header (including type-specific fields)
57 type: CARD32 must match type in TOC for this chunk
58 subtype: CARD32 must match subtype in TOC for this chunk
59 version: CARD32 version number for this chunk type
60 There are currently two chunk types defined for cursor files; comments
62 and images. Comments look like:
63 header: 20 Comment headers are 20 bytes
65 type: 0xfffe0001 Comment type is 0xfffe0001
66 subtype: { 1 (COPYRIGHT), 2 (LICENSE), 3 (OTHER) }
67 version: 1
68 length: CARD32 byte length of UTF-8 string
69 string: LISTofCARD8 UTF-8 string
70 Images look like:
72 header: 36 Image headers are 36 bytes
74 type: 0xfffd0002 Image type is 0xfffd0002
75 subtype: CARD32 Image subtype is the nominal size
76 version: 1
77 width: CARD32 Must be less than or equal to 0x7fff
78 height: CARD32 Must be less than or equal to 0x7fff
79 xhot: CARD32 Must be less than or equal to width
80 yhot: CARD32 Must be less than or equal to height
81 delay: CARD32 Delay between animation frames in milliseconds
82 pixels: LISTofCARD32 Packed ARGB format pixels
83 THEMES
85 Xcursor (mostly) follows the freedesktop.org spec for theming icons.
86 The default search path it uses is
87 ~/.local/share/icons, ~/.icons, /usr/share/icons,
89 /usr/share/pixmaps
90 Within each of these directories, it searches for a directory using the
92 theme name:
93 • Within the theme directory, it looks for cursor files in the
95 “cursors” subdirectory.
96 Xcursor looks for a specific file, which must be one of the cursor
98 shape names, e.g., as used in XcursorLibraryLoadImage or
99 XcursorLibraryShape.
100 • If it finds no matching cursor file in the “cursors” subdirectory,
102 Xcursor next looks for an “index.theme” file in each theme
103 directory to look for inherited themes. Those are lines in this
104 format:
105 Inherits = theme-name
107 Xcursor uses the first inherited theme-name, ignoring others which
109 may exist in a given “index.theme” file. If it finds an inherited
110 theme, Xcursor searches along the path to use that as well.
111 Xcursor ignores other keys in the “index.theme” file, including
112 “Name” (i.e., the name which a graphical application may use as the
113 presentation name).
114 More than one theme-name may be listed on the Inherits= line. The
116 freedesktop.org spec states that list items are separated by
117 commas. Xcursor also accepts semicolon, but translates both to
118 colon when searching the path. Xcursor expects only one Inherits=
119 line; the freedesktop.org spec is unclear whether multiple keys are
120 allowed.
121 If no theme is set, or if no cursor is found for the specified theme
123 anywhere along the path, Xcursor checks the “default” theme.
124 When Xcursor finds a cursor file, it stops searching. It always uses
126 the first cursor file found while searching along the path.
127
129 XcursorImage
130 holds a single cursor image in memory. Each pixel in the cursor
131 is a 32-bit value containing ARGB with A in the high byte.
132 typedef struct _XcursorImage {
134 XcursorDim size; /* nominal size for matching */
135 XcursorDim width; /* actual width */
136 XcursorDim height; /* actual height */
137 XcursorDim xhot; /* hot spot x (must be inside image) */
138 XcursorDim yhot; /* hot spot y (must be inside image) */
139 XcursorPixel *pixels; /* pointer to pixels */
140 } XcursorImage;
141 XcursorImages
143 holds multiple XcursorImage structures. They are all freed when
144 the XcursorImages is freed in XcursorImagesDestroy.
145 typedef struct _XcursorImages {
147 int nimage; /* number of images */
148 XcursorImage **images; /* array of XcursorImage pointers */
149 } XcursorImages;
150 XcursorCursors
152 Holds multiple Cursor objects. They are all freed when the
153 XcursorCursors is freed. These are reference counted so that
154 multiple XcursorAnimate structures can use the same
155 XcursorCursors.
156 typedef struct _XcursorCursors {
158 Display *dpy; /* Display holding cursors */
159 int ref; /* reference count */
160 int ncursor; /* number of cursors */
161 Cursor *cursors; /* array of cursors */
162 } XcursorCursors;
163 XcursorAnimate
165 References a set of cursors and a sequence within that set.
166 Multiple XcursorAnimate structures may reference the same
167 XcursorCursors; each holds a reference which is removed when the
168 XcursorAnimate is freed.
169 typedef struct _XcursorAnimate {
171 XcursorCursors *cursors; /* list of cursors to use */
172 int sequence; /* which cursor is next */
173 } XcursorAnimate;
174 XcursorFile
176 Xcursor provides an abstract API for accessing the file data.
177 Xcursor provides a stdio implementation of this abstract API;
178 applications are free to create additional implementations.
179 These functions parallel the stdio functions in return value and
180 expected argument values; the read and write functions flip the
181 arguments around to match the POSIX versions.
182 typedef struct _XcursorFile {
184 void *closure;
185 int (*read) (XcursorFile *file, unsigned char *buf, int len);
186 int (*write) (XcursorFile *file, unsigned char *buf, int len);
187 int (*seek) (XcursorFile *file, long offset, int whence);
188 };
189
191 Object Management
192 XcursorImage *XcursorImageCreate (
193 int width,
194 int height)
195 void XcursorImageDestroy (
197 XcursorImage *image)
198 Allocate and free images. On allocation, the hotspot and the
200 pixels are left uninitialized. The size is set to the maximum
201 of width and height.
202 XcursorImages *XcursorImagesCreate (
204 int size)
205 void XcursorImagesDestroy (
207 XcursorImages *images)
208 Allocate and free arrays to hold multiple cursor images. On
210 allocation, nimage is set to zero.
211 XcursorCursors *XcursorCursorsCreate (
213 Display *dpy,
214 int size)
215 void XcursorCursorsDestroy (
217 XcursorCursors *cursors)
218 Allocate and free arrays to hold multiple cursors. On
220 allocation, ncursor is set to zero, ref is set to one.
221 Reading and writing images.
223 XcursorImage *XcursorXcFileLoadImage (
224 XcursorFile *file,
225 int size)
226 XcursorImages *XcursorXcFileLoadImages (
228 XcursorFile *file,
229 int size)
230 XcursorImages *XcursorXcFileLoadAllImages (
232 XcursorFile *file)
233 XcursorBool XcursorXcFileLoad (
235 XcursorFile *file,
236 XcursorComments **commentsp,
237 XcursorImages **imagesp)
238 XcursorBool XcursorXcFileSave (
240 XcursorFile *file,
241 const XcursorComments *comments,
242 const XcursorImages *images)
243 These read and write cursors from an XcursorFile handle. After
245 reading, the file pointer will be left at some random place in
246 the file.
247 XcursorImage *XcursorFileLoadImage (
249 FILE *file,
250 int size)
251 XcursorImages *XcursorFileLoadImages (
253 FILE *file,
254 int size)
255 XcursorImages *XcursorFileLoadAllImages (
257 FILE *file)
258 XcursorBool XcursorFileLoad (
260 FILE *file,
261 XcursorComments **commentsp,
262 XcursorImages **imagesp)
263 XcursorBool XcursorFileSaveImages (
265 FILE *file,
266 const XcursorImages *images)
267 XcursorBool XcursorFileSave (
269 FILE *file,
270 const XcursorComments *comments,
271 const XcursorImages *images)
272 These read and write cursors from a stdio FILE handle. Writing
274 flushes before returning so that any errors should be detected.
275 XcursorImage *XcursorFilenameLoadImage (
277 const char *filename,
278 int size)
279 XcursorImages *XcursorFilenameLoadImages (
281 const char *filename,
282 int size)
283 XcursorImages *XcursorFilenameLoadAllImages (
285 const char *file)
286 XcursorBool XcursorFilenameLoad (
288 const char *file,
289 XcursorComments **commentsp,
290 XcursorImages **imagesp)
291 XcursorBool XcursorFilenameSaveImages (
293 const char *filename,
294 const XcursorImages *images)
295 XcursorBool XcursorFilenameSave (
297 const char *file,
298 const XcursorComments *comments,
299 const XcursorImages *images)
300 These parallel the stdio FILE interfaces above, but take
302 filenames.
303 Reading library images
305 XcursorImage *XcursorLibraryLoadImage (
306 const char *name,
307 const char *theme,
308 int size)
309 XcursorImages *XcursorLibraryLoadImages (
311 const char *name,
312 const char *theme,
313 int size)
314 These search the library path, loading the first file found of
316 the desired size, using a private function (XcursorScanTheme) to
317 find the appropriate theme:
318 • If theme is not NULL, use that.
320 • If theme is NULL, or if there was no match for the desired
322 theme, use “default” for the theme name.
323 • If neither search succeeds, these functions return NULL.
325 The two functions differ by more than the number of images
327 loaded:
328 • XcursorLibraryLoadImage calls XcursorFileLoadImage but
330 • XcursorLibraryLoadImages calls XcursorFileLoadImages, and
332 (on success) it calls XcursorImagesSetName to associate name
333 with the result.
334 Library attributes
336 const char * XcursorLibraryPath (void)
337 Returns the library search path:
339 • If the environment variable XCURSOR_PATH is set, return that
341 value.
342 • Otherwise, return the compiled-in search path.
344 int XcursorLibraryShape (
346 const char *library)
347 Search Xcursor's table of cursor font names for the given “shape
349 name” (library):
350 • If found, return the index into that table, multiplied by
352 two (to account for the source- and mask-values used in an X
353 cursor font).
354 • If not found, return -1.
356 Cursor APIs
358 Cursor XcursorFilenameLoadCursor (
359 Display *dpy,
360 const char *file)
361 XcursorCursors *XcursorFilenameLoadCursors (
363 Display *dpy,
364 const char *file)
365 These load cursors from the specified file.
367 Cursor XcursorLibraryLoadCursor (
369 Display *dpy,
370 const char *name)
371 XcursorCursors *XcursorLibraryLoadCursors (
373 Display *dpy,
374 const char *name)
375 These load cursors using the specified library name. The theme
377 comes from the display.
378 Cursor XcursorImageLoadCursor(
380 Display *dpy,
381 const XcursorImage *image)
382 This creates a cursor, given the image to display. It calls
384 XcursorSupportsARGB to decide what type of cursor to create:
385 • XRenderCreateCursor is used if ARGB is supported on the
387 display, and
388 • XCreatePixmapCursor is used otherwise.
390 Cursor XcursorImagesLoadCursor(
392 Display *dpy,
393 const XcursorImages *images)
394 This provides an interface for creating animated cursors, if the
396 images array contains multiple images, and if
397 XcursorSupportsAnim returns true. Otherwise, it calls
398 XcursorImageLoadCursor.
399 XcursorCursors *XcursorImagesLoadCursors(
401 Display *dpy,
402 const XcursorImages *images)
403 This calls XcursorCursorsCreate to create an array of
405 XcursorCursors, to correspond to the XcursorImages images array,
406 and uses XcursorImageLoadCursor to load the corresponding cursor
407 data.
408 Normally it returns the resulting array pointer. On any
410 failure, it discards the result XcursorCursorsDestroy, and
411 returns NULL.
412 X Cursor Name APIs
414 XcursorImage *XcursorShapeLoadImage (
415 unsigned int shape,
416 const char *theme,
417 int size)
418 XcursorImages *XcursorShapeLoadImages (
420 unsigned int shape,
421 const char *theme,
422 int size)
423 These map shape to a library name using the standard X cursor
425 names and then load the images.
426 Cursor XcursorShapeLoadCursor (
428 Display *dpy,
429 unsigned int shape)
430 XcursorCursors *XcursorShapeLoadCursors (
432 Display *dpy,
433 unsigned int shape)
434 These map shape to a library name and then load the cursors.
436 X Cursor Comment APIs
438 XcursorComment *XcursorCommentCreate (
439 XcursorUInt comment_type,
440 int length)
441 XcursorXcFileLoad uses this function to allocate an
443 XcursorComment structure for a single cursor. The comment_type
444 parameter is used as the subtype field, e.g., COPYRIGHT. The
445 length is the number of bytes to allocate for the comment text.
446 void XcursorCommentDestroy(
448 XcursorComment *comment)
449 Deallocates the given XcursorComment structure.
451 XcursorComments * XcursorCommentsCreate (
453 int size)
454 XcursorXcFileLoad uses this function to allocate an index of
456 XcursorComment structure pointers. The size parameter tells it
457 how many pointers will be in the index.
458 void XcursorCommentsDestroy (
460 XcursorComments *comments)
461 Deallocates the given XcursorComments structure as well as the
463 XcursorComment structures which it points to.
464 Animated Cursors
466 XcursorAnimate * XcursorAnimateCreate (
467 XcursorCursors *cursors)
468 Wrap the given array of cursors in a newly allocated
470 XcursorAnimate structure, which adds a sequence number used in
471 XcursorAnimateNext.
472 void XcursorAnimateDestroy (
474 XcursorAnimate *animate)
475 Discards the given animate data, freeing both the XcursorCursors
477 array of cursors as well as the XcursorAnimate structure.
478 Cursor XcursorAnimateNext (
480 XcursorAnimate *animate)
481 Cyclically returns the next Cursor in the array, incrementing
483 the sequence number to prepare for the next call.
484 The caller is responsible for displaying the series of Cursor
486 images. Xcursor does not do that.
487 Glyph Cursor APIs
489 The X11 XCreateFontCursor and XCreateGlyphCursor functions use this
490 part of the API to extend the X core cursors feature to use themes.
491 void XcursorImageHash (
493 XImage *image,
494 unsigned char hash[XCURSOR_BITMAP_HASH_SIZE])
495 Compute a hash of the image, to display when the environment
497 variable XCURSOR_DISCOVER is set.
498 void XcursorImagesSetName (
500 XcursorImages *images,
501 const char *name)
502 Associates the given name with the images.
504 void XcursorNoticeCreateBitmap (
506 Display *dpy,
507 Pixmap pid,
508 unsigned int width,
509 unsigned int height)
510 Check if the display supports either ARGB or themes, and also if
512 the image size fits within the maximum cursor size (64 pixels).
513 If so, create a bitmap of the specified size, and cache the
514 result in Xcursor, identifying it with the Pixmap-id (pid)
515 value.
516 void XcursorNoticePutBitmap (
518 Display *dpy,
519 Drawable draw,
520 XImage *image)
521 Update the image contents in the bitmap specified by the draw
523 value (a Pixmap-id). The bitmap must have been created by
524 XcursorNoticeCreateBitmap.
525 Cursor XcursorTryShapeBitmapCursor (
527 Display *dpy,
528 Pixmap source,
529 Pixmap mask,
530 XColor *foreground,
531 XColor *background,
532 unsigned int x,
533 unsigned int y)
534 If the display supports either ARGB or themes, try to load a
536 cursor into Xcursor's cache using the source parameter as a
537 Pixmap-id. The source may no longer be in the cache. Xcursor
538 uses the hash value to identify the desired image.
539 Cursor XcursorTryShapeCursor (
541 Display *dpy,
542 Font source_font,
543 Font mask_font,
544 unsigned int source_char,
545 unsigned int mask_char,
546 XColor _Xconst *foreground,
547 XColor _Xconst *background)
548 If the display supports either ARGB or themes, try to load a
550 cursor into Xcursor's cache using the source_char parameter as a
551 shape. Using
552 • the default size from XcursorGetDefaultSize,
554 • the default theme from XcursorGetTheme, and
556 • the source_char parameter as a shape,
558 Xcursor calls XcursorShapeLoadImages to load the cursor images.
560 If successful, Xcursor uses XcursorImagesLoadCursor to load the
561 cursor information.
562 Display Information APIs
564 XcursorBool XcursorSupportsARGB (
565 Display *dpy)
566 Returns true if the display supports ARGB cursors. Otherwise,
568 cursors will be mapped to a core X cursor.
569 XcursorBool XcursorSupportsAnim (
571 Display *dpy)
572 Returns true if the display supports animated cursors.
574 Otherwise, cursors will be mapped to a core X cursor.
575 XcursorBool XcursorSetDefaultSize (
577 Display *dpy,
578 int size)
579 Sets the default size for cursors on the specified display.
581 When loading cursors, those whose nominal size is closest to
582 this size will be preferred.
583 int XcursorGetDefaultSize (
585 Display *dpy)
586 Gets the default cursor size.
588 XcursorBool XcursorSetTheme (
590 Display *dpy,
591 const char *theme)
592 Sets the current theme name.
594 char *XcursorGetTheme (
596 Display *dpy)
597 Gets the current theme name.
599 XcursorBool XcursorGetThemeCore (
601 Display *dpy)
602 XcursorBool XcursorSetThemeCore (
604 Display *dpy,
605 XcursorBool theme_core)
606 Get or set property which tells Xcursor whether to enable themes
608 for core cursors.
609
611 Environment variables can be used to override resource settings, which
612 in turn override compiled-in default values.
613 Some of the environment variables recognized by Xcursor are booleans,
615 specified as follows:
616 true for “t”, “1”, “y” or “on”
618 false for “f”, “0”, “n” or “off”
620 Xcursor ignores other values for these booleans.
622 HOME Xcursor interprets “~” in the search list as the home
624 directory, using this variable rather than the password
625 database.
626 XCURSOR_ANIM If the display supports the Render CreateCursor request,
628 and the Render feature is enabled, disable animated
629 cursors if the environment variable is false.
630 If the environment variable is not given, Xcursor uses
632 the resource Xcursor.anim.
633 XCURSOR_CORE If the display supports the Render CreateCursor request
635 disable the Render feature if the environment variable
636 is false.
637 If the environment variable is not given, Xcursor uses
639 the resource Xcursor.core.
640 XCURSOR_DISCOVER
642 If the variable is set, Xcursor turns on a logging
643 feature. It displays the hash value and the image so
644 that users can see which cursor name is associated with
645 each image.
646 There is no corresponding resource setting.
648 XCURSOR_DITHER This variable sets the desired dither.
650 If the environment variable is not given, Xcursor uses
652 the resource Xcursor.dither.
653 If neither environment variable or resource is found,
655 Xcursor uses “threshold”
656 These are the recognized values:
658 diffuse
660 median
662 ordered
664 threshold
666 XCURSOR_PATH This variable sets the list of paths in which to search
668 for cursors, rather than the compiled-in default list.
669 Directories in this path are separated by colons (:).
671 XCURSOR_SIZE This variable sets the desired cursor size, in pixels.
673 If the environment variable is not given, Xcursor tries
675 the Xcursor.size resource.
676 If no size is given, whether by environment variable or
678 resource setting, Xcursor next tries the Xft.dpi
679 resource setting to guess the size of a 16-point cursor.
680 Finally, if Xft.dpi is not set, Xcursor uses the display
682 height, dividing by 48 (assuming that the height is
683 768).
684 XCURSOR_THEME This variable selects the desired theme.
686 If the environment variable is not given, Xcursor tries
688 the Xcursor.theme resource.
689 If neither environment variable or resource is found,
691 Xcursor uses the default theme.
692 XCURSOR_THEME_CORE
694 Enables themes for core cursors if the environment
695 variable is true.
696 If the environment variable is not given, Xcursor tries
698 the Xcursor.theme_core resource.
699 An application can enable or disable themes using
701 XcursorSetThemeCore.
702
704 XCreateRenderCursor(3), XCreatePixmapCursor(3), and
705 XCreateFontCursor(3)
706 as well as
708 Icon Theme Specification
710 https://specifications.freedesktop.org/icon-theme-spec/
711
713 Xcursor will probably change radically in the future; weak attempts
714 will be made to retain some level of source-file compatibility.
715
717 Keith Packard
718X Version 11 libXcursor 1.2.1 XCURSOR(3)