1XCURSOR(3)                       X Version 11                       XCURSOR(3)
2
3
4

NAME

6       Xcursor - Cursor management library
7

SYNOPSIS

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

DESCRIPTION

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

FUNCTIONAL OVERVIEW

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
29   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
36       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
41         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
47       Each table of contents entry looks like:
48
49         type:     CARD32 entry type
50         subtype:  CARD32 type-specific label - size for images
51         position: CARD32 absolute byte position of table in file
52
53       Each chunk in the file has set of  common  header  fields  followed  by
54       additional type-specific fields:
55
56         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
61       There  are currently two chunk types defined for cursor files; comments
62       and images.  Comments look like:
63
64         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
71       Images look like:
72
73         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
84   THEMES
85       Xcursor (mostly) follows the freedesktop.org spec  for  theming  icons.
86       The default search path it uses is
87
88              ~/.local/share/icons,         ~/.icons,        /usr/share/icons,
89              /usr/share/pixmaps
90
91       Within each of these directories, it searches for a directory using the
92       theme name:
93
94       •   Within  the  theme  directory,  it  looks  for  cursor files in the
95           “cursors” subdirectory.
96
97           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
101       •   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
106           Inherits = theme-name
107
108           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
115           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
122       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
125       When Xcursor finds a cursor file, it stops searching.  It  always  uses
126       the first cursor file found while searching along the path.
127

DATATYPES

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
133                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
142       XcursorImages
143              holds multiple XcursorImage structures.  They are all freed when
144              the XcursorImages is freed in XcursorImagesDestroy.
145
146                typedef struct _XcursorImages {
147                    int              nimage;  /* number of images */
148                    XcursorImage    **images; /* array of XcursorImage pointers */
149                } XcursorImages;
150
151       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
157                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
164       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
170                typedef struct _XcursorAnimate {
171                    XcursorCursors  *cursors; /* list of cursors to use */
172                    int              sequence; /* which cursor is next */
173                } XcursorAnimate;
174
175       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
183                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

FUNCTIONS

191   Object Management
192       XcursorImage *XcursorImageCreate (
193                      int                    width,
194                      int                    height)
195
196       void XcursorImageDestroy (
197                      XcursorImage          *image)
198
199              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
203       XcursorImages *XcursorImagesCreate (
204                      int                    size)
205
206       void XcursorImagesDestroy (
207                      XcursorImages         *images)
208
209              Allocate and free arrays to hold  multiple  cursor  images.   On
210              allocation, nimage is set to zero.
211
212       XcursorCursors *XcursorCursorsCreate (
213                      Display               *dpy,
214                      int                    size)
215
216       void XcursorCursorsDestroy (
217                      XcursorCursors        *cursors)
218
219              Allocate   and   free  arrays  to  hold  multiple  cursors.   On
220              allocation, ncursor is set to zero, ref is set to one.
221
222   Reading and writing images.
223       XcursorImage *XcursorXcFileLoadImage (
224                      XcursorFile           *file,
225                      int                    size)
226
227       XcursorImages *XcursorXcFileLoadImages (
228                      XcursorFile           *file,
229                      int                    size)
230
231       XcursorImages *XcursorXcFileLoadAllImages (
232                      XcursorFile           *file)
233
234       XcursorBool XcursorXcFileLoad (
235                      XcursorFile           *file,
236                      XcursorComments       **commentsp,
237                      XcursorImages         **imagesp)
238
239       XcursorBool XcursorXcFileSave (
240                      XcursorFile           *file,
241                      const XcursorComments *comments,
242                      const XcursorImages   *images)
243
244              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
248       XcursorImage *XcursorFileLoadImage (
249                      FILE                  *file,
250                      int                    size)
251
252       XcursorImages *XcursorFileLoadImages (
253                      FILE                  *file,
254                      int                    size)
255
256       XcursorImages *XcursorFileLoadAllImages (
257                      FILE                  *file)
258
259       XcursorBool XcursorFileLoad (
260                      FILE                  *file,
261                      XcursorComments       **commentsp,
262                      XcursorImages         **imagesp)
263
264       XcursorBool XcursorFileSaveImages (
265                      FILE                  *file,
266                      const XcursorImages   *images)
267
268       XcursorBool XcursorFileSave (
269                      FILE                  *file,
270                      const XcursorComments *comments,
271                      const XcursorImages   *images)
272
273              These read and write cursors from a stdio FILE handle.   Writing
274              flushes before returning so that any errors should be detected.
275
276       XcursorImage *XcursorFilenameLoadImage (
277                      const char            *filename,
278                      int                    size)
279
280       XcursorImages *XcursorFilenameLoadImages (
281                      const char            *filename,
282                      int                    size)
283
284       XcursorImages *XcursorFilenameLoadAllImages (
285                      const char            *file)
286
287       XcursorBool XcursorFilenameLoad (
288                      const char            *file,
289                      XcursorComments       **commentsp,
290                      XcursorImages         **imagesp)
291
292       XcursorBool XcursorFilenameSaveImages (
293                      const char            *filename,
294                      const XcursorImages   *images)
295
296       XcursorBool XcursorFilenameSave (
297                      const char            *file,
298                      const XcursorComments *comments,
299                      const XcursorImages   *images)
300
301              These  parallel  the  stdio  FILE  interfaces  above,  but  take
302              filenames.
303
304   Reading library images
305       XcursorImage *XcursorLibraryLoadImage (
306                      const char            *name,
307                      const char            *theme,
308                      int                    size)
309
310       XcursorImages *XcursorLibraryLoadImages (
311                      const char            *name,
312                      const char            *theme,
313                      int                    size)
314
315              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
319              •   If theme is not NULL, use that.
320
321              •   If theme is NULL, or if there was no match for  the  desired
322                  theme, use “default” for the theme name.
323
324              •   If neither search succeeds, these functions return NULL.
325
326              The  two  functions  differ  by  more  than the number of images
327              loaded:
328
329              •   XcursorLibraryLoadImage calls XcursorFileLoadImage but
330
331              •   XcursorLibraryLoadImages  calls  XcursorFileLoadImages,  and
332                  (on success) it calls XcursorImagesSetName to associate name
333                  with the result.
334
335   Library attributes
336       const char * XcursorLibraryPath (void)
337
338              Returns the library search path:
339
340              •   If the environment variable XCURSOR_PATH is set, return that
341                  value.
342
343              •   Otherwise, return the compiled-in search path.
344
345       int XcursorLibraryShape (
346                      const char            *library)
347
348              Search Xcursor's table of cursor font names for the given “shape
349              name” (library):
350
351              •   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
355              •   If not found, return -1.
356
357   Cursor APIs
358       Cursor XcursorFilenameLoadCursor (
359                      Display               *dpy,
360                      const char            *file)
361
362       XcursorCursors *XcursorFilenameLoadCursors (
363                      Display               *dpy,
364                      const char            *file)
365
366              These load cursors from the specified file.
367
368       Cursor XcursorLibraryLoadCursor (
369                      Display               *dpy,
370                      const char            *name)
371
372       XcursorCursors *XcursorLibraryLoadCursors (
373                      Display               *dpy,
374                      const char            *name)
375
376              These load cursors using the specified library name.  The  theme
377              comes from the display.
378
379       Cursor XcursorImageLoadCursor(
380                      Display               *dpy,
381                      const XcursorImage    *image)
382
383              This  creates  a  cursor,  given the image to display.  It calls
384              XcursorSupportsARGB to decide what type of cursor to create:
385
386              •   XRenderCreateCursor is used if  ARGB  is  supported  on  the
387                  display, and
388
389              •   XCreatePixmapCursor is used otherwise.
390
391       Cursor XcursorImagesLoadCursor(
392                      Display               *dpy,
393                      const XcursorImages   *images)
394
395              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
400       XcursorCursors *XcursorImagesLoadCursors(
401                      Display               *dpy,
402                      const XcursorImages   *images)
403
404              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
409              Normally  it  returns  the  resulting  array  pointer.   On  any
410              failure,  it  discards  the  result  XcursorCursorsDestroy,  and
411              returns NULL.
412
413   X Cursor Name APIs
414       XcursorImage *XcursorShapeLoadImage (
415                      unsigned int           shape,
416                      const char            *theme,
417                      int                    size)
418
419       XcursorImages *XcursorShapeLoadImages (
420                      unsigned int           shape,
421                      const char            *theme,
422                      int                    size)
423
424              These  map  shape  to a library name using the standard X cursor
425              names and then load the images.
426
427       Cursor XcursorShapeLoadCursor (
428                      Display               *dpy,
429                      unsigned int           shape)
430
431       XcursorCursors *XcursorShapeLoadCursors (
432                      Display               *dpy,
433                      unsigned int           shape)
434
435              These map shape to a library name and then load the cursors.
436
437   X Cursor Comment APIs
438       XcursorComment *XcursorCommentCreate (
439                      XcursorUInt            comment_type,
440                      int                    length)
441
442              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
447       void XcursorCommentDestroy(
448                      XcursorComment        *comment)
449
450              Deallocates the given XcursorComment structure.
451
452       XcursorComments * XcursorCommentsCreate (
453                      int                    size)
454
455              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
459       void XcursorCommentsDestroy (
460                      XcursorComments       *comments)
461
462              Deallocates  the  given XcursorComments structure as well as the
463              XcursorComment structures which it points to.
464
465   Animated Cursors
466       XcursorAnimate * XcursorAnimateCreate (
467                      XcursorCursors        *cursors)
468
469              Wrap  the  given  array  of  cursors  in   a   newly   allocated
470              XcursorAnimate  structure,  which adds a sequence number used in
471              XcursorAnimateNext.
472
473       void XcursorAnimateDestroy (
474                      XcursorAnimate        *animate)
475
476              Discards the given animate data, freeing both the XcursorCursors
477              array of cursors as well as the XcursorAnimate structure.
478
479       Cursor XcursorAnimateNext (
480                      XcursorAnimate        *animate)
481
482              Cyclically  returns  the  next Cursor in the array, incrementing
483              the sequence number to prepare for the next call.
484
485              The caller is responsible for displaying the  series  of  Cursor
486              images.  Xcursor does not do that.
487
488   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
492       void XcursorImageHash (
493                      XImage                *image,
494                      unsigned char          hash[XCURSOR_BITMAP_HASH_SIZE])
495
496              Compute a hash of the image, to  display  when  the  environment
497              variable XCURSOR_DISCOVER is set.
498
499       void XcursorImagesSetName (
500                      XcursorImages         *images,
501                      const char            *name)
502
503              Associates the given name with the images.
504
505       void XcursorNoticeCreateBitmap (
506                      Display               *dpy,
507                      Pixmap                 pid,
508                      unsigned int           width,
509                      unsigned int           height)
510
511              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
517       void XcursorNoticePutBitmap (
518                      Display               *dpy,
519                      Drawable               draw,
520                      XImage                *image)
521
522              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
526       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
535              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
540       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
549              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
553              •   the default size from XcursorGetDefaultSize,
554
555              •   the default theme from XcursorGetTheme, and
556
557              •   the source_char parameter as a shape,
558
559              Xcursor calls XcursorShapeLoadImages to load the cursor  images.
560              If  successful, Xcursor uses XcursorImagesLoadCursor to load the
561              cursor information.
562
563   Display Information APIs
564       XcursorBool XcursorSupportsARGB (
565                      Display               *dpy)
566
567              Returns true if the display supports ARGB  cursors.   Otherwise,
568              cursors will be mapped to a core X cursor.
569
570       XcursorBool XcursorSupportsAnim (
571                      Display               *dpy)
572
573              Returns   true   if   the  display  supports  animated  cursors.
574              Otherwise, cursors will be mapped to a core X cursor.
575
576       XcursorBool XcursorSetDefaultSize (
577                      Display               *dpy,
578                      int                    size)
579
580              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
584       int XcursorGetDefaultSize (
585                      Display               *dpy)
586
587              Gets the default cursor size.
588
589       XcursorBool XcursorSetTheme (
590                      Display               *dpy,
591                      const char            *theme)
592
593              Sets the current theme name.
594
595       char *XcursorGetTheme (
596                      Display               *dpy)
597
598              Gets the current theme name.
599
600       XcursorBool XcursorGetThemeCore (
601                      Display               *dpy)
602
603       XcursorBool XcursorSetThemeCore (
604                      Display               *dpy,
605                      XcursorBool            theme_core)
606
607              Get or set property which tells Xcursor whether to enable themes
608              for core cursors.
609

ENVIRONMENT VARIABLES

611       Environment  variables can be used to override resource settings, which
612       in turn override compiled-in default values.
613
614       Some of the environment variables recognized by Xcursor  are  booleans,
615       specified as follows:
616
617          true for “t”, “1”, “y” or “on”
618
619          false for “f”, “0”, “n” or “off”
620
621       Xcursor ignores other values for these booleans.
622
623       HOME           Xcursor  interprets  “~”  in the search list as the home
624                      directory, using this variable rather than the  password
625                      database.
626
627       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
631                      If  the  environment variable is not given, Xcursor uses
632                      the resource Xcursor.anim.
633
634       XCURSOR_CORE   If the display supports the Render CreateCursor  request
635                      disable  the  Render feature if the environment variable
636                      is false.
637
638                      If the environment variable is not given,  Xcursor  uses
639                      the resource Xcursor.core.
640
641       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
647                      There is no corresponding resource setting.
648
649       XCURSOR_DITHER This variable sets the desired dither.
650
651                      If the environment variable is not given,  Xcursor  uses
652                      the resource Xcursor.dither.
653
654                      If  neither  environment  variable or resource is found,
655                      Xcursor uses “threshold”
656
657                      These are the recognized values:
658
659                         diffuse
660
661                         median
662
663                         ordered
664
665                         threshold
666
667       XCURSOR_PATH   This variable sets the list of paths in which to  search
668                      for cursors, rather than the compiled-in default list.
669
670                      Directories in this path are separated by colons (:).
671
672       XCURSOR_SIZE   This variable sets the desired cursor size, in pixels.
673
674                      If  the environment variable is not given, Xcursor tries
675                      the Xcursor.size resource.
676
677                      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
681                      Finally, if Xft.dpi is not set, Xcursor uses the display
682                      height,  dividing  by  48  (assuming  that the height is
683                      768).
684
685       XCURSOR_THEME  This variable selects the desired theme.
686
687                      If the environment variable is not given, Xcursor  tries
688                      the Xcursor.theme resource.
689
690                      If  neither  environment  variable or resource is found,
691                      Xcursor uses the default theme.
692
693       XCURSOR_THEME_CORE
694                      Enables themes  for  core  cursors  if  the  environment
695                      variable is true.
696
697                      If  the environment variable is not given, Xcursor tries
698                      the Xcursor.theme_core resource.
699
700                      An  application  can  enable  or  disable  themes  using
701                      XcursorSetThemeCore.
702

SEE ALSO

704       XCreateRenderCursor(3), XCreatePixmapCursor(3), and
705       XCreateFontCursor(3)
706
707       as well as
708
709              Icon Theme Specification
710              https://specifications.freedesktop.org/icon-theme-spec/
711

RESTRICTIONS

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

AUTHOR

717       Keith Packard
718
719
720
721X Version 11                   libXcursor 1.2.1                     XCURSOR(3)
Impressum