diff options
Diffstat (limited to 'man/Xcursor.man')
| -rw-r--r-- | man/Xcursor.man | 379 |
1 files changed, 379 insertions, 0 deletions
diff --git a/man/Xcursor.man b/man/Xcursor.man new file mode 100644 index 0000000..90fa534 --- /dev/null +++ b/man/Xcursor.man @@ -0,0 +1,379 @@ +.\" +.\" $XFree86: xc/lib/Xcursor/Xcursor.man,v 1.2 2003/02/13 03:09:04 dawes Exp $ +.\" +.\" Copyright © 2002 Keith Packard, member of The XFree86 Project, Inc. +.\" +.\" Permission to use, copy, modify, distribute, and sell this software and its +.\" documentation for any purpose is hereby granted without fee, provided that +.\" the above copyright notice appear in all copies and that both that +.\" copyright notice and this permission notice appear in supporting +.\" documentation, and that the name of Keith Packard not be used in +.\" advertising or publicity pertaining to distribution of the software without +.\" specific, written prior permission. Keith Packard makes no +.\" representations about the suitability of this software for any purpose. It +.\" is provided "as is" without express or implied warranty. +.\" +.\" KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO +.\" EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR +.\" CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, +.\" DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER +.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +.\" PERFORMANCE OF THIS SOFTWARE. +.\" +.de TQ +.br +.ns +.TP \\$1 +.. +.TH XCURSOR 3 "Version 1.0" "XFree86" + +.SH NAME +XCURSOR \- Cursor management library + +.SH SYNOPSIS +.nf +.B #include <X11/Xcursor/Xcursor.h> +.fi +.SH DESCRIPTION +.B Xcursor +is a simple library designed to help locate and load cursors. Cursors can +be loaded from files or memory. A library of common cursors exists which +map to the standard X cursor names. Cursors can exist in several sizes and +the library automatically picks the best size. + +.SH FUNCTIONAL OVERVIEW +Xcursor is built in a couple of layers; at the bottom layer is code which +can load cursor images from files. Above that is a layer which locates +cursor files based on the library path and theme. At the top is a layer +which builds cursors either out of an image loaded from a file or one of the +standard X cursors. When using images loaded from files, Xcursor prefers +to use the Render extension CreateCursor request if supported by the X +server. Where not supported, Xcursor maps the cursor image to a standard X +cursor and uses the core CreateCursor request. + +.SS CURSOR FILES +Xcursor defines a new format for cursors on disk. Each file holds +one or more cursor images. Each cursor image is tagged with a nominal size +so that the best size can be selected automatically. Multiple cursors of +the same nominal size can be loaded together; applications are expected to +use them as an animated sequence. +.P +Cursor files are stored as a header containing a table of contents followed +by a sequence of chunks. The table of contents indicates the type, subtype +and position in the file of each chunk. The file header looks like: +.LP +.in +.2i +\fImagic\fP\^: CARD32 'Xcur' (0x58, 0x63, 0x75, 0x72) +.br +\fIheader\fP\^: CARD32 bytes in this header +.br +\fIversion\fP\^: CARD32 file version number +.br +\fIntoc\fP\^: CARD32 number of toc entries +\fItoc\fP\^: LISTofTOC table of contents +.in -.2i +.P +Each table of contents entry looks like: +.LP +.in +.2i +\fItype\fP\^: CARD32 entry type +\fIsubtype\fP\^: CARD32 type-specific label - size for images +\fIposition\fP\^: CARD32 absolute byte position of table in file +.in -.2i +.P +.P +Each chunk in the file has set of common header fields followed by +additional type-specific fields: +.LP +.in +.2i +\fIheader\fP\^: CARD32 bytes in chunk header (including type-specific fields) +.br +\fItype\fP\^: CARD32 must match type in TOC for this chunk +.br +\fIsubtype\fP\^: CARD32 must match subtype in TOC for this chunk +.br +\fIversion\fP\^: CARD32 version number for this chunk type +.in -.2i +.P +There are currently two chunk types defined for cursor files; comments and +images. Comments look like: +.LP +.in +.2i +\fIheader\fP\^: 20 Comment headers are 20 bytes +.br +\fItype\fP\^: 0xfffe0001 Comment type is 0xfffe0001 +.br +\fIsubtype\fP\^: { 1 (COPYRIGHT), 2 (LICENSE), 3 (OTHER) } +.br +\fIversion\fP\^: 1 +.br +\fIlength\fP\^: CARD32 byte length of UTF-8 string +.br +\fIstring\fP\^: LISTofCARD8 UTF-8 string +.in -.2i +.P +Images look like: +.LP +.in +.2i +\fIheader\fP\^: 36 Image headers are 36 bytes +.br +\fItype\fP\^: 0xfffd0002 Image type is 0xfffd0002 +.br +\fIsubtype\fP\^: CARD32 Image subtype is the nominal size +.br +\fIversion\fP\^: 1 +.br +\fIwidth\fP\^: CARD32 Must be less than or equal to 0x7fff +.br +\fIheight\fP\^: CARD32 Must be less than or equal to 0x7fff +.br +\fIxhot\fP\^: CARD32 Must be less than or equal to width +.br +\fIyhot\fP\^: CARD32 Must be less than or equal to height +.br +\fIdelay\fP\^: CARD32 Delay between animation frames in milliseconds +.br +\fIpixels\fP\^: LISTofCARD32 Packed ARGB format pixels +.in -.2i + +.SS THEMES +Xcursor (mostly) follows the freedesktop.org spec for theming icons. The +default search path it uses is $HOME/.icons, /usr/share/icons, +/usr/share/pimaps, /usr/X11R6/lib/X11/icons. Within each of these +directorys, it searches for a directory using the theme name. Within the +theme directory, it looks for cursor files in the 'cursors' subdirectory. +It uses the first cursor file found along the path. +.PP +If necessary, Xcursor also looks for a "index.theme" file in each theme +directory to find inherited themes and searches along the path for those +themes as well. +.PP +If no theme is set, or if no cursor is found for the specified theme, +Xcursor checks the "default" theme. + +.SH DATATYPES + +.TP +.B XcursorImage +holds a single cursor image in memory. Each pixel in the cursor is a 32-bit +value containing ARGB with A in the high byte. +.sp +.nf +.ft CR + typedef struct _XcursorImage { + XcursorDim size; /* nominal size for matching */ + XcursorDim width; /* actual width */ + XcursorDim height; /* actual height */ + XcursorDim xhot; /* hot spot x (must be inside image) */ + XcursorDim yhot; /* hot spot y (must be inside image) */ + XcursorPixel *pixels; /* pointer to pixels */ + } XcursorImage; +.ft +.fi + +.TP +.B XcursorImages +holds multiple XcursorImage structures. They're all freed when the +XcursorImages is freed. +.sp +.nf +.ft CR + typedef struct _XcursorImages { + int nimage; /* number of images */ + XcursorImage **images; /* array of XcursorImage pointers */ + } XcursorImages; +.ft +.fi + +.TP +.B XcursorCursors +Holds multiple Cursor objects. They're all freed when the XcursorCursors is +freed. These are reference counted so that multiple XcursorAnimate +structures can use the same XcursorCursors. +.sp +.nf +.ft CR + typedef struct _XcursorCursors { + Display *dpy; /* Display holding cursors */ + int ref; /* reference count */ + int ncursor; /* number of cursors */ + Cursor *cursors; /* array of cursors */ + } XcursorCursors; +.ft +.fi + +.TP +.B XcursorAnimate +References a set of cursors and a sequence within that set. Multiple +XcursorAnimate structures may reference the same XcursorCursors; each +holds a reference which is removed when the XcursorAnimate is freed. +.sp +.nf +.ft CR + typedef struct _XcursorAnimate { + XcursorCursors *cursors; /* list of cursors to use */ + int sequence; /* which cursor is next */ + } XcursorAnimate; +.ft +.fi + +.TP +.B XcursorFile +Xcursor provides an abstract API for accessing the file data. Xcursor +provides a stdio implementation of this abstract API; applications +are free to create additional implementations. These functions +parallel the stdio functions in return value and expected argument values; +the read and write functions flip the arguments around to match the POSIX +versions. +.sp +.nf +.ft CR + typedef struct _XcursorFile { + void *closure; + int (*read) (XcursorFile *file, unsigned char *buf, int len); + int (*write) (XcursorFile *file, unsigned char *buf, int len); + int (*seek) (XcursorFile *file, long offset, int whence); + }; +.ft +.fi + +.SH FUNCTIONS + +.SS Object Management +.TP +XcursorImage *XcursorImageCreate (int width, int height) +.TQ +void XcursorImageDestroy (XcursorImage *image) +Allocate and free images. On allocation, the hotspot and the pixels are +left uninitialized. The size is set to the maximum of width and height. + +.TP +XcursorImages *XcursorImagesCreate (int size) +.TQ +void XcursorImagesDestroy (XcursorImages *images) +Allocate and free arrays to hold multiple cursor images. On allocation, +nimage is set to zero. + +.TP +XcursorCursors *XcursorCursorsCreate (Display *dpy, int size) +.TQ +void XcursorCursorsDestroy (XcursorCursors *cursors) +Allocate and free arrays to hold multiple cursors. On allocation, +ncursor is set to zero, ref is set to one. + +.SS Reading and writing images. + +.TP +XcursorImage *XcursorXcFileLoadImage (XcursorFile *file, int size) +.TQ +XcursorImages *XcursorXcFileLoadImages (XcursorFile *file, int size) +.TQ +XcursorImages *XcursorXcFileLoadAllImages (XcursorFile *file) +.TQ +XcursorBool XcursorXcFileLoad (XcursorFile *file, XcursorComments **commentsp, XcursorImages **imagesp) +.TQ +XcursorBool XcursorXcFileSave (XcursorFile *file, const XcursorComments *comments, const XcursorImages *images) +These read and write cursors from an XcursorFile handle. After reading, the +file pointer will be left at some random place in the file. + +.TP +XcursorImage *XcursorFileLoadImage (FILE *file, int size) +.TQ +XcursorImages *XcursorFileLoadImages (FILE *file, int size) +.TQ +XcursorImages *XcursorFileLoadAllImages (FILE *file) +.TQ +XcursorBool XcursorFileLoad (FILE *file, XcursorComments **commentsp, XcursorImages **imagesp) +.TQ +XcursorBool XcursorFileSaveImages (FILE *file, const XcursorImages *images) +.TQ +XcursorBool XcursorFileSave (FILE * file, const XcursorComments *comments, const XcursorImages *images) +These read and write cursors from a stdio FILE handle. Writing flushes +before returning so that any errors should be detected. + +.TP +XcursorImage *XcursorFilenameLoadImage (const char *filename, int size) +.TQ +XcursorImages *XcursorFilenameLoadImages (const char *filename, int size) +.TQ +XcursorImages *XcursorFilenameLoadAllImages (FILE *file) +.TQ +XcursorBool XcursorFilenameLoad (const char *file, XcursorComments **commentsp, XcursorImages **imagesp) +.TQ +XcursorBool XcursorFilenameSaveImages (const char *filename, const XcursorImages *images) +.TQ +XcursorBool XcursorFilenameSave (const char *file, const XcursorComments *comments, const XcursorImages *images) +These parallel the stdio FILE interfaces above, but take filenames. + +.SS Reading library images +.TP +XcursorImage *XcursorLibraryLoadImage (const char *name, const char *theme, int size) +.TQ +XcursorImages *XcursorLibraryLoadImages (const char *name, const char *theme, int size) +These search the library path, loading the first file found. If 'theme' is +not NULL, these functions first try appending -theme to name and then +name alone. + +.SS Cursor APIs + +.TP +Cursor XcursorFilenameLoadCursor (Display *dpy, const char *file) +.TQ +XcursorCursors *XcursorFilenameLoadCursors (Display *dpy, const char *file) +These load cursors from the specified file. + +.TP +Cursor XcursorLibraryLoadCursor (Display *dpy, const char *name) +.TQ +XcursorCursors *XcursorLibraryLoadCursors (Display *dpy, const char *name) +These load cursors using the specified library name. The theme +comes from the display. + +.SS X Cursor Name APIs + +.TP +XcursorImage *XcursorShapeLoadImage (unsigned int shape, const char *theme, int size) +.TQ +XcursorImages *XcursorShapeLoadImages (unsigned int shape, const char *theme, int size) +These map 'shape' to a library name using the standard X cursor names and +then load the images. + +.TP +Cursor XcursorShapeLoadCursor (Display *dpy, unsigned int shape) +.TQ +XcursorCursors *XcursorShapeLoadCursors (Display *dpy, unsigned int shape) +These map 'shape' to a library name and then load the cursors. + +.SS Display Information APIs + +.TP +XcursorBool XcursorSupportsARGB (Display *dpy) +Returns whether the display supports ARGB cursors or whether cursors will be +mapped to a core X cursor. + +.TP +XcursorBool XcursorSetDefaultSize (Display *dpy, int size) +Sets the default size for cursors on the specified display. When loading +cursors, those who's nominal size is closest to this size will be preferred. + +.TP +int XcursorGetDefaultSize (Display *dpy) +Gets the default cursor size. + +.TP +XcursorBool +XcursorSetTheme (Display *dpy, const char *theme) +Sets the current theme name. + +char * +XcursorGetTheme (Display *dpy) +Gets the current theme name. + +.SH RESTRICTIONS +.B Xcursor +will probably change radically in the future; weak attempts will be made to +retain some level of source-file compatibility. + +.SH AUTHOR +Keith Packard, member of the XFree86 Project, Inc. |