1/* include/X11/Xcursor/Xcursor.h. Generated from Xcursor.h.in by configure. */
2/*
3 * Copyright © 2002 Keith Packard
4 *
5 * Permission to use, copy, modify, distribute, and sell this software and its
6 * documentation for any purpose is hereby granted without fee, provided that
7 * the above copyright notice appear in all copies and that both that
8 * copyright notice and this permission notice appear in supporting
9 * documentation, and that the name of Keith Packard not be used in
10 * advertising or publicity pertaining to distribution of the software without
11 * specific, written prior permission. Keith Packard makes no
12 * representations about the suitability of this software for any purpose. It
13 * is provided "as is" without express or implied warranty.
14 *
15 * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
16 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
17 * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
18 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
19 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
20 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
21 * PERFORMANCE OF THIS SOFTWARE.
22 */
23
24#ifndef _XCURSOR_H_
25#define _XCURSOR_H_
26#include <stdio.h>
27#include <X11/Xfuncproto.h>
28#include <X11/Xlib.h>
29
30typedef int XcursorBool;
31typedef unsigned int XcursorUInt;
32
33typedef XcursorUInt XcursorDim;
34typedef XcursorUInt XcursorPixel;
35
36#define XcursorTrue 1
37#define XcursorFalse 0
38
39/*
40 * Cursor files start with a header. The header
41 * contains a magic number, a version number and a
42 * table of contents which has type and offset information
43 * for the remaining tables in the file.
44 *
45 * File minor versions increment for compatible changes
46 * File major versions increment for incompatible changes (never, we hope)
47 *
48 * Chunks of the same type are always upward compatible. Incompatible
49 * changes are made with new chunk types; the old data can remain under
50 * the old type. Upward compatible changes can add header data as the
51 * header lengths are specified in the file.
52 *
53 * File:
54 * FileHeader
55 * LISTofChunk
56 *
57 * FileHeader:
58 * CARD32 magic magic number
59 * CARD32 header bytes in file header
60 * CARD32 version file version
61 * CARD32 ntoc number of toc entries
62 * LISTofFileToc toc table of contents
63 *
64 * FileToc:
65 * CARD32 type entry type
66 * CARD32 subtype entry subtype (size for images)
67 * CARD32 position absolute file position
68 */
69
70#define XCURSOR_MAGIC 0x72756358 /* "Xcur" LSBFirst */
71
72/*
73 * Current Xcursor version number. Will be substituted by configure
74 * from the version in the libXcursor configure.ac file.
75 */
76
77#define XCURSOR_LIB_MAJOR 1
78#define XCURSOR_LIB_MINOR 2
79#define XCURSOR_LIB_REVISION 0
80#define XCURSOR_LIB_VERSION ((XCURSOR_LIB_MAJOR * 10000) + \
81 (XCURSOR_LIB_MINOR * 100) + \
82 (XCURSOR_LIB_REVISION))
83
84/*
85 * This version number is stored in cursor files; changes to the
86 * file format require updating this version number
87 */
88#define XCURSOR_FILE_MAJOR 1
89#define XCURSOR_FILE_MINOR 0
90#define XCURSOR_FILE_VERSION ((XCURSOR_FILE_MAJOR << 16) | (XCURSOR_FILE_MINOR))
91#define XCURSOR_FILE_HEADER_LEN (4 * 4)
92#define XCURSOR_FILE_TOC_LEN (3 * 4)
93
94typedef struct _XcursorFileToc {
95 XcursorUInt type; /* chunk type */
96 XcursorUInt subtype; /* subtype (size for images) */
97 XcursorUInt position; /* absolute position in file */
98} XcursorFileToc;
99
100typedef struct _XcursorFileHeader {
101 XcursorUInt magic; /* magic number */
102 XcursorUInt header; /* byte length of header */
103 XcursorUInt version; /* file version number */
104 XcursorUInt ntoc; /* number of toc entries */
105 XcursorFileToc *tocs; /* table of contents */
106} XcursorFileHeader;
107
108/*
109 * The rest of the file is a list of chunks, each tagged by type
110 * and version.
111 *
112 * Chunk:
113 * ChunkHeader
114 * <extra type-specific header fields>
115 * <type-specific data>
116 *
117 * ChunkHeader:
118 * CARD32 header bytes in chunk header + type header
119 * CARD32 type chunk type
120 * CARD32 subtype chunk subtype
121 * CARD32 version chunk type version
122 */
123
124#define XCURSOR_CHUNK_HEADER_LEN (4 * 4)
125
126typedef struct _XcursorChunkHeader {
127 XcursorUInt header; /* bytes in chunk header */
128 XcursorUInt type; /* chunk type */
129 XcursorUInt subtype; /* chunk subtype (size for images) */
130 XcursorUInt version; /* version of this type */
131} XcursorChunkHeader;
132
133/*
134 * Here's a list of the known chunk types
135 */
136
137/*
138 * Comments consist of a 4-byte length field followed by
139 * UTF-8 encoded text
140 *
141 * Comment:
142 * ChunkHeader header chunk header
143 * CARD32 length bytes in text
144 * LISTofCARD8 text UTF-8 encoded text
145 */
146
147#define XCURSOR_COMMENT_TYPE 0xfffe0001
148#define XCURSOR_COMMENT_VERSION 1
149#define XCURSOR_COMMENT_HEADER_LEN (XCURSOR_CHUNK_HEADER_LEN + (1 *4))
150#define XCURSOR_COMMENT_COPYRIGHT 1
151#define XCURSOR_COMMENT_LICENSE 2
152#define XCURSOR_COMMENT_OTHER 3
153#define XCURSOR_COMMENT_MAX_LEN 0x100000
154
155typedef struct _XcursorComment {
156 XcursorUInt version;
157 XcursorUInt comment_type;
158 char *comment;
159} XcursorComment;
160
161/*
162 * Each cursor image occupies a separate image chunk.
163 * The length of the image header follows the chunk header
164 * so that future versions can extend the header without
165 * breaking older applications
166 *
167 * Image:
168 * ChunkHeader header chunk header
169 * CARD32 width actual width
170 * CARD32 height actual height
171 * CARD32 xhot hot spot x
172 * CARD32 yhot hot spot y
173 * CARD32 delay animation delay
174 * LISTofCARD32 pixels ARGB pixels
175 */
176
177#define XCURSOR_IMAGE_TYPE 0xfffd0002
178#define XCURSOR_IMAGE_VERSION 1
179#define XCURSOR_IMAGE_HEADER_LEN (XCURSOR_CHUNK_HEADER_LEN + (5*4))
180#define XCURSOR_IMAGE_MAX_SIZE 0x7fff /* 32767x32767 max cursor size */
181
182typedef struct _XcursorImage {
183 XcursorUInt version; /* version of the image data */
184 XcursorDim size; /* nominal size for matching */
185 XcursorDim width; /* actual width */
186 XcursorDim height; /* actual height */
187 XcursorDim xhot; /* hot spot x (must be inside image) */
188 XcursorDim yhot; /* hot spot y (must be inside image) */
189 XcursorUInt delay; /* animation delay to next frame (ms) */
190 XcursorPixel *pixels; /* pointer to pixels */
191} XcursorImage;
192
193/*
194 * Other data structures exposed by the library API
195 */
196typedef struct _XcursorImages {
197 int nimage; /* number of images */
198 XcursorImage **images; /* array of XcursorImage pointers */
199 char *name; /* name used to load images */
200} XcursorImages;
201
202typedef struct _XcursorCursors {
203 Display *dpy; /* Display holding cursors */
204 int ref; /* reference count */
205 int ncursor; /* number of cursors */
206 Cursor *cursors; /* array of cursors */
207} XcursorCursors;
208
209typedef struct _XcursorAnimate {
210 XcursorCursors *cursors; /* list of cursors to use */
211 int sequence; /* which cursor is next */
212} XcursorAnimate;
213
214typedef struct _XcursorFile XcursorFile;
215
216struct _XcursorFile {
217 void *closure;
218 int (*read) (XcursorFile *file, unsigned char *buf, int len);
219 int (*write) (XcursorFile *file, unsigned char *buf, int len);
220 int (*seek) (XcursorFile *file, long offset, int whence);
221};
222
223typedef struct _XcursorComments {
224 int ncomment; /* number of comments */
225 XcursorComment **comments; /* array of XcursorComment pointers */
226} XcursorComments;
227
228#define XCURSOR_CORE_THEME "core"
229
230_XFUNCPROTOBEGIN
231
232/*
233 * Manage Image objects
234 */
235XcursorImage *
236XcursorImageCreate (int width, int height);
237
238void
239XcursorImageDestroy (XcursorImage *image);
240
241/*
242 * Manage Images objects
243 */
244XcursorImages *
245XcursorImagesCreate (int size);
246
247void
248XcursorImagesDestroy (XcursorImages *images);
249
250void
251XcursorImagesSetName (XcursorImages *images, const char *name);
252
253/*
254 * Manage Cursor objects
255 */
256XcursorCursors *
257XcursorCursorsCreate (Display *dpy, int size);
258
259void
260XcursorCursorsDestroy (XcursorCursors *cursors);
261
262/*
263 * Manage Animate objects
264 */
265XcursorAnimate *
266XcursorAnimateCreate (XcursorCursors *cursors);
267
268void
269XcursorAnimateDestroy (XcursorAnimate *animate);
270
271Cursor
272XcursorAnimateNext (XcursorAnimate *animate);
273
274/*
275 * Manage Comment objects
276 */
277XcursorComment *
278XcursorCommentCreate (XcursorUInt comment_type, int length);
279
280void
281XcursorCommentDestroy (XcursorComment *comment);
282
283XcursorComments *
284XcursorCommentsCreate (int size);
285
286void
287XcursorCommentsDestroy (XcursorComments *comments);
288
289/*
290 * XcursorFile/Image APIs
291 */
292XcursorImage *
293XcursorXcFileLoadImage (XcursorFile *file, int size);
294
295XcursorImages *
296XcursorXcFileLoadImages (XcursorFile *file, int size);
297
298XcursorImages *
299XcursorXcFileLoadAllImages (XcursorFile *file);
300
301XcursorBool
302XcursorXcFileLoad (XcursorFile *file,
303 XcursorComments **commentsp,
304 XcursorImages **imagesp);
305
306XcursorBool
307XcursorXcFileSave (XcursorFile *file,
308 const XcursorComments *comments,
309 const XcursorImages *images);
310
311/*
312 * FILE/Image APIs
313 */
314XcursorImage *
315XcursorFileLoadImage (FILE *file, int size);
316
317XcursorImages *
318XcursorFileLoadImages (FILE *file, int size);
319
320XcursorImages *
321XcursorFileLoadAllImages (FILE *file);
322
323XcursorBool
324XcursorFileLoad (FILE *file,
325 XcursorComments **commentsp,
326 XcursorImages **imagesp);
327
328XcursorBool
329XcursorFileSaveImages (FILE *file, const XcursorImages *images);
330
331XcursorBool
332XcursorFileSave (FILE * file,
333 const XcursorComments *comments,
334 const XcursorImages *images);
335
336/*
337 * Filename/Image APIs
338 */
339XcursorImage *
340XcursorFilenameLoadImage (const char *filename, int size);
341
342XcursorImages *
343XcursorFilenameLoadImages (const char *filename, int size);
344
345XcursorImages *
346XcursorFilenameLoadAllImages (const char *filename);
347
348XcursorBool
349XcursorFilenameLoad (const char *file,
350 XcursorComments **commentsp,
351 XcursorImages **imagesp);
352
353XcursorBool
354XcursorFilenameSaveImages (const char *filename, const XcursorImages *images);
355
356XcursorBool
357XcursorFilenameSave (const char *file,
358 const XcursorComments *comments,
359 const XcursorImages *images);
360
361/*
362 * Library/Image APIs
363 */
364XcursorImage *
365XcursorLibraryLoadImage (const char *library, const char *theme, int size);
366
367XcursorImages *
368XcursorLibraryLoadImages (const char *library, const char *theme, int size);
369
370/*
371 * Library/shape API
372 */
373
374const char *
375XcursorLibraryPath (void);
376
377int
378XcursorLibraryShape (const char *library);
379
380/*
381 * Image/Cursor APIs
382 */
383
384Cursor
385XcursorImageLoadCursor (Display *dpy, const XcursorImage *image);
386
387XcursorCursors *
388XcursorImagesLoadCursors (Display *dpy, const XcursorImages *images);
389
390Cursor
391XcursorImagesLoadCursor (Display *dpy, const XcursorImages *images);
392
393/*
394 * Filename/Cursor APIs
395 */
396Cursor
397XcursorFilenameLoadCursor (Display *dpy, const char *file);
398
399XcursorCursors *
400XcursorFilenameLoadCursors (Display *dpy, const char *file);
401
402/*
403 * Library/Cursor APIs
404 */
405Cursor
406XcursorLibraryLoadCursor (Display *dpy, const char *file);
407
408XcursorCursors *
409XcursorLibraryLoadCursors (Display *dpy, const char *file);
410
411/*
412 * Shape/Image APIs
413 */
414
415XcursorImage *
416XcursorShapeLoadImage (unsigned int shape, const char *theme, int size);
417
418XcursorImages *
419XcursorShapeLoadImages (unsigned int shape, const char *theme, int size);
420
421/*
422 * Shape/Cursor APIs
423 */
424Cursor
425XcursorShapeLoadCursor (Display *dpy, unsigned int shape);
426
427XcursorCursors *
428XcursorShapeLoadCursors (Display *dpy, unsigned int shape);
429
430/*
431 * This is the function called by Xlib when attempting to
432 * load cursors from XCreateGlyphCursor. The interface must
433 * not change as Xlib loads 'libXcursor.so' instead of
434 * a specific major version
435 */
436Cursor
437XcursorTryShapeCursor (Display *dpy,
438 Font source_font,
439 Font mask_font,
440 unsigned int source_char,
441 unsigned int mask_char,
442 XColor _Xconst *foreground,
443 XColor _Xconst *background);
444
445void
446XcursorNoticeCreateBitmap (Display *dpy,
447 Pixmap pid,
448 unsigned int width,
449 unsigned int height);
450
451void
452XcursorNoticePutBitmap (Display *dpy,
453 Drawable draw,
454 XImage *image);
455
456Cursor
457XcursorTryShapeBitmapCursor (Display *dpy,
458 Pixmap source,
459 Pixmap mask,
460 XColor *foreground,
461 XColor *background,
462 unsigned int x,
463 unsigned int y);
464
465#define XCURSOR_BITMAP_HASH_SIZE 16
466
467void
468XcursorImageHash (XImage *image,
469 unsigned char hash[XCURSOR_BITMAP_HASH_SIZE]);
470
471/*
472 * Display information APIs
473 */
474XcursorBool
475XcursorSupportsARGB (Display *dpy);
476
477XcursorBool
478XcursorSupportsAnim (Display *dpy);
479
480XcursorBool
481XcursorSetDefaultSize (Display *dpy, int size);
482
483int
484XcursorGetDefaultSize (Display *dpy);
485
486XcursorBool
487XcursorSetTheme (Display *dpy, const char *theme);
488
489char *
490XcursorGetTheme (Display *dpy);
491
492XcursorBool
493XcursorGetThemeCore (Display *dpy);
494
495XcursorBool
496XcursorSetThemeCore (Display *dpy, XcursorBool theme_core);
497
498_XFUNCPROTOEND
499
500#endif
501