fdo-mirrors/xorg-libxcursor
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/xorg/lib/libxcursor.git synced 2025-12-20 05:50:14 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

fix raggedy prototypes and structure declarations using tabstops in appropriate macros

Browse source 
Signed-off-by: Thomas E. Dickey <dickey@invisible-island.net>
This commit is contained in:
Thomas E. Dickey 2021-03-17 18:52:16 -04:00
parent 8560016436
commit d64dda62de
No known key found for this signature in database
GPG key ID: 702353E0F7E48EDB
1 changed files with 311 additions and 287 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

440
man/Xcursor.man
View file

@ -19,18 +19,45 @@
.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
.\" PERFORMANCE OF THIS SOFTWARE.
.\"
.de NS
.de TA
.ie n .ta 0.8i 1.6i 2.4i 3.2i
.el .ta 0.5i 1.0i 1.5i 2.0i
..
.de PS
.sp
.ns
.TP \\$1
.na
.nf
.ie n .ta 0.8i 3.0i
.el .ta 0.5i 2.0i
..
.de NE
.de PE
.br
.ad
.fi
.sp
.TA
..
.de QS
.in +.2i
.nf
.na
.ie n .ta 1.0i 3.0i
.el .ta 0.6i 2.0i
..
.de QC
.QS
.ie n .ta 2.0i 3.0i
.el .ta 1.6i 2.6i
.ft CR
..
.de QE
.in -.2i
.ft
.fi
.ad
.TA
..
.de bP
.ie n .IP \(bu 4
@ -79,62 +106,48 @@ 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
.QS
\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
.br
\fItoc\fP\^: LISTofTOC table of contents
.in -.2i
.P
Each table of contents entry looks like:
.LP
.in +.2i
.QS
\fItype\fP\^: CARD32 entry type
.br
\fIsubtype\fP\^: CARD32 type-specific label - size for images
.br
\fIposition\fP\^: CARD32 absolute byte position of table in file
.in -.2i
.QE
.P
.P
Each chunk in the file has set of common header fields followed by
additional type-specific fields:
.LP
.in +.2i
.QS
\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
.QE
.P
There are currently two chunk types defined for cursor files; comments and
images. Comments look like:
.LP
.in +.2i
.QS
\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
.QE
.P
Images look like:
.LP
.in +.2i
.QS
\fIheader\fP\^: 36 Image headers are 36 bytes
.br
\fItype\fP\^: 0xfffd0002 Image type is 0xfffd0002
@ -154,7 +167,7 @@ Images look like:
\fIdelay\fP\^: CARD32 Delay between animation frames in milliseconds
.br
\fIpixels\fP\^: LISTofCARD32 Packed ARGB format pixels
.in -.2i
.QE
.
.SS THEMES
Xcursor (mostly) follows the freedesktop.org spec for theming icons. The
@ -205,33 +218,29 @@ It always uses the first cursor file found while searching along the path.
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 {
.QC
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
} XcursorImage;
.QE
.
.TP
.B XcursorImages
holds multiple XcursorImage structures.
They are all freed when the
XcursorImages is freed.
XcursorImages is freed in XcursorImagesDestroy.
.sp
.nf
.ft CR
typedef struct _XcursorImages {
.QC
typedef struct _XcursorImages {
int nimage; /\(** number of images */
XcursorImage **images; /\(** array of XcursorImage pointers */
} XcursorImages;
.ft
.fi
} XcursorImages;
.QE
.
.TP
.B XcursorCursors
@ -239,16 +248,14 @@ 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 {
.QC
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
} XcursorCursors;
.QE
.
.TP
.B XcursorAnimate
@ -256,14 +263,12 @@ 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 {
.QC
typedef struct _XcursorAnimate {
XcursorCursors *cursors; /\(** list of cursors to use */
int sequence; /\(** which cursor is next */
} XcursorAnimate;
.ft
.fi
} XcursorAnimate;
.QE
.
.TP
.B XcursorFile
@ -274,139 +279,149 @@ 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 {
.QC
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
};
.QE
.fi
.
.SH FUNCTIONS
.
.SS Object Management
.NS
.PS
XcursorImage *XcursorImageCreate (
int \fIwidth\fP,
int \fIheight\fP)
.NS
.PS
void XcursorImageDestroy (
XcursorImage *\fIimage\fP)
.NE
.PE
Allocate and free images. On allocation, the hotspot and the pixels are
left uninitialized.
The size is set to the maximum of \fIwidth\fP and \fIheight\fP.
.
.NS
.PS
XcursorImages *XcursorImagesCreate (
int \fIsize\fP)
.NS
.PS
void XcursorImagesDestroy (
XcursorImages *\fIimages\fP)
.NE
.PE
Allocate and free arrays to hold multiple cursor images. On allocation,
\fInimage\fP is set to zero.
.
.NS
.PS
XcursorCursors *XcursorCursorsCreate (
Display *\fIdpy\fP,
int \fIsize\fP)
.NS
.PS
void XcursorCursorsDestroy (
XcursorCursors *\fIcursors\fP)
.NE
.PE
Allocate and free arrays to hold multiple cursors. On allocation,
\fIncursor\fP is set to zero, \fIref\fP is set to one.
.
.
.SS Reading and writing images.
.
.NS
XcursorImage *XcursorXcFileLoadImage (XcursorFile *\fIfile\fP, int \fIsize\fP)
.NS
XcursorImages *XcursorXcFileLoadImages (XcursorFile *\fIfile\fP, int \fIsize\fP)
.NS
XcursorImages *XcursorXcFileLoadAllImages (XcursorFile *\fIfile\fP)
.NS
.PS
XcursorImage *XcursorXcFileLoadImage (
XcursorFile *\fIfile\fP,
int \fIsize\fP)
.PS
XcursorImages *XcursorXcFileLoadImages (
XcursorFile *\fIfile\fP,
int \fIsize\fP)
.PS
XcursorImages *XcursorXcFileLoadAllImages (
XcursorFile *\fIfile\fP)
.PS
XcursorBool XcursorXcFileLoad (
XcursorFile *\fIfile\fP,
XcursorComments **\fIcommentsp\fP,
XcursorImages **\fIimagesp\fP)
.NS
.PS
XcursorBool XcursorXcFileSave (
XcursorFile *\fIfile\fP,
const XcursorComments *\fIcomments\fP,
const XcursorImages *\fIimages\fP)
.NE
.PE
These read and write cursors from an XcursorFile handle. After reading, the
file pointer will be left at some random place in the file.
.
.NS
XcursorImage *XcursorFileLoadImage (FILE *\fIfile\fP, int \fIsize\fP)
.NS
XcursorImages *XcursorFileLoadImages (FILE *\fIfile\fP, int \fIsize\fP)
.NS
XcursorImages *XcursorFileLoadAllImages (FILE *\fIfile\fP)
.NS
.PS
XcursorImage *XcursorFileLoadImage (
FILE *\fIfile\fP,
int \fIsize\fP)
.PS
XcursorImages *XcursorFileLoadImages (
FILE *\fIfile\fP,
int \fIsize\fP)
.PS
XcursorImages *XcursorFileLoadAllImages (
FILE *\fIfile\fP)
.PS
XcursorBool XcursorFileLoad (
FILE *\fIfile\fP,
XcursorComments **\fIcommentsp\fP,
XcursorImages **\fIimagesp\fP)
.NS
.PS
XcursorBool XcursorFileSaveImages (
FILE *\fIfile\fP,
const XcursorImages *\fIimages\fP)
.NS
.PS
XcursorBool XcursorFileSave (
FILE * \fIfile\fP,
FILE *\fIfile\fP,
const XcursorComments *\fIcomments\fP,
const XcursorImages *\fIimages\fP)
.NE
.PE
These read and write cursors from a stdio FILE handle. Writing flushes
before returning so that any errors should be detected.
.
.NS
.PS
XcursorImage *XcursorFilenameLoadImage (
const char *\fIfilename\fP,
int \fIsize\fP)
.NS
.PS
XcursorImages *XcursorFilenameLoadImages (
const char *\fIfilename\fP,
int \fIsize\fP)
.NS
XcursorImages *XcursorFilenameLoadAllImages (const char *\fIfile\fP)
.NS
.PS
XcursorImages *XcursorFilenameLoadAllImages (
const char *\fIfile\fP)
.PS
XcursorBool XcursorFilenameLoad (
const char *\fIfile\fP,
XcursorComments **\fIcommentsp\fP,
XcursorImages **\fIimagesp\fP)
.NS
.PS
XcursorBool XcursorFilenameSaveImages (
const char *\fIfilename\fP,
const XcursorImages *\fIimages\fP)
.NS
.PS
XcursorBool XcursorFilenameSave (
const char *\fIfile\fP,
const XcursorComments *\fIcomments\fP,
const XcursorImages *\fIimages\fP)
.NE
.PE
These parallel the stdio FILE interfaces above, but take filenames.
.
.SS Reading library images
.NS
.PS
XcursorImage *XcursorLibraryLoadImage (
const char *\fIname\fP,
const char *\fItheme\fP,
int \fIsize\fP)
.NS
.PS
XcursorImages *XcursorLibraryLoadImages (
const char *\fIname\fP,
const char *\fItheme\fP,
int \fIsize\fP)
.NE
.PE
These search the library path, loading the first file found
of the desired \fIsize\fP,
using a private function (XcursorScanTheme) to find the appropriate theme:
@ -432,9 +447,9 @@ it calls XcursorImagesSetName to associate \fIname\fP with the result.
.RE
.
.SS Library attributes
.NS
.PS
const char * XcursorLibraryPath (void)
.NE
.PE
Returns the library search path:
.RS
.bP
@ -444,9 +459,10 @@ return that value.
Otherwise, return the compiled-in search path.
.RE
.
.NS
int XcursorLibraryShape (const char *\fIlibrary\fP)
.NE
.PS
int XcursorLibraryShape (
const char *\fIlibrary\fP)
.PE
Search Xcursor's table of cursor font names for the given
\*(``shape name\*('' (\fIlibrary\fP):
.RS
@ -460,34 +476,34 @@ If not found, return -1.
.
.SS Cursor APIs
.
.NS
.PS
Cursor XcursorFilenameLoadCursor (
Display *\fIdpy\fP,
const char *\fIfile\fP)
.NS
.PS
XcursorCursors *XcursorFilenameLoadCursors (
Display *\fIdpy\fP,
const char *\fIfile\fP)
.NE
.PE
These load cursors from the specified file.
.
.NS
.PS
Cursor XcursorLibraryLoadCursor (
Display *\fIdpy\fP,
const char *\fIname\fP)
.NS
.PS
XcursorCursors *XcursorLibraryLoadCursors (
Display *\fIdpy\fP,
const char *\fIname\fP)
.NE
.PE
These load cursors using the specified library \fIname\fP. The theme
comes from the display.
.
.NS
.PS
Cursor XcursorImageLoadCursor(
Display *dpy,
const XcursorImage *image)
.NE
Display *\fIdpy\fP,
const XcursorImage *\fIimage\fP)
.PE
This creates a cursor, given the image to display.
It calls XcursorSupportsARGB to decide what type of cursor to create:
.RS
@ -497,21 +513,21 @@ XRenderCreateCursor is used if ARGB is supported on the display, and
XCreatePixmapCursor is used otherwise.
.RE
.
.NS
.PS
Cursor XcursorImagesLoadCursor(
Display *dpy,
const XcursorImages *images)
.NE
Display *\fIdpy\fP,
const XcursorImages *\fIimages\fP)
.PE
This provides an interface for creating animated cursors,
if the \fIimages\fP array contains multiple images, and
if XcursorSupportsAnim returns true.
Otherwise, it calls XcursorImageLoadCursor.
.
.NS
.PS
XcursorCursors *XcursorImagesLoadCursors(
Display *dpy,
const XcursorImages *images)
.NE
Display *\fIdpy\fP,
const XcursorImages *\fIimages\fP)
.PE
This calls XcursorCursorsCreate to create an array of XcursorCursors,
to correspond to the XcursorImages \fIimages\fP array,
and uses XcursorImageLoadCursor to load the corresponding cursor data.
@ -522,84 +538,84 @@ and returns NULL.
.
.SS X Cursor Name APIs
.
.NS
.PS
XcursorImage *XcursorShapeLoadImage (
unsigned int \fIshape\fP,
const char *\fItheme\fP,
int \fIsize\fP)
.NS
.PS
XcursorImages *XcursorShapeLoadImages (
unsigned int \fIshape\fP,
const char *\fItheme\fP,
int \fIsize\fP)
.NE
.PE
These map \fIshape\fP to a library name using the standard X cursor names and
then load the images.
.
.NS
.PS
Cursor XcursorShapeLoadCursor (
Display *\fIdpy\fP,
unsigned int \fIshape\fP)
.NS
.PS
XcursorCursors *XcursorShapeLoadCursors (
Display *\fIdpy\fP,
unsigned int \fIshape\fP)
.NE
.PE
These map \fIshape\fP to a library name and then load the cursors.
.
.SS X Cursor Comment APIs
.NS
.PS
XcursorComment *XcursorCommentCreate (
XcursorUInt comment_type,
int length)
.NE
XcursorUInt \fIcomment_type\fP,
int \fIlength\fP)
.PE
XcursorXcFileLoad uses this function to allocate an XcursorComment
structure for a single cursor.
The \fIcomment_type\fP parameter is used as the \fIsubtype\fP field,
e.g., COPYRIGHT.
The \fIlength\fP is the number of bytes to allocate for the comment text.
.
.NS
.PS
void XcursorCommentDestroy(
XcursorComment *comment)
.NE
XcursorComment *\fIcomment\fP)
.PE
Deallocates the given XcursorComment structure.
.
.NS
.PS
XcursorComments * XcursorCommentsCreate (
int size)
.NE
int \fIsize\fP)
.PE
XcursorXcFileLoad uses this function to allocate an index of
XcursorComment structure pointers.
The \fIsize\fP parameter tells it how many pointers will be in the index.
.
.NS
.PS
void XcursorCommentsDestroy (
XcursorComments *comments)
.NE
XcursorComments *\fIcomments\fP)
.PE
Deallocates the given XcursorComments structure
as well as the XcursorComment structures which it points to.
.
.SS Animated Cursors
.NS
.PS
XcursorAnimate * XcursorAnimateCreate (
XcursorCursors *cursors)
.NE
XcursorCursors *\fIcursors\fP)
.PE
Wrap the given array of cursors in a newly allocated XcursorAnimate structure,
which adds a sequence number used in XcursorAnimateNext.
.
.NS
.PS
void XcursorAnimateDestroy (
XcursorAnimate *animate)
.NE
XcursorAnimate *\fIanimate\fP)
.PE
Discards the given \fIanimate\fP data,
freeing both the XcursorCursors array of cursors
as well as the XcursorAnimate structure.
.
.NS
.PS
Cursor XcursorAnimateNext (
XcursorAnimate *animate)
.NE
XcursorAnimate *\fIanimate\fP)
.PE
Cyclically returns the next Cursor in the array,
incrementing the sequence number to prepare for the next call.
.IP
@ -609,73 +625,73 @@ Xcursor does not do that.
.SS Glyph Cursor APIs
The X11 XCreateFontCursor and XCreateGlyphCursor functions use
this part of the API to extend the X core cursors feature to use themes.
.NS
.PS
void XcursorImageHash (
XImage *image,
unsigned char hash[XCURSOR_BITMAP_HASH_SIZE])
.NE
XImage *\fIimage\fP,
unsigned char \fIhash\fP[XCURSOR_BITMAP_HASH_SIZE])
.PE
Compute a hash of the image,
to display when the environment variable XCURSOR_DISCOVER is set.
.
.NS
.PS
void XcursorImagesSetName (
XcursorImages *images,
const char *name)
.NE
XcursorImages *\fIimages\fP,
const char *\fIname\fP)
.PE
Associates the given name with the images.
.
.NS
.PS
void XcursorNoticeCreateBitmap (
Display *dpy,
Pixmap pid,
unsigned int width,
unsigned int height)
.NE
Display *\fIdpy\fP,
Pixmap \fIpid\fP,
unsigned int \fIwidth\fP,
unsigned int \fIheight\fP)
.PE
Check if the display supports either ARGB or themes,
and also if the image size fits within the maximum cursor size (64 pixels).
If so, create a bitmap of the specified size,
and cache the result in Xcursor,
identifying it with the Pixmap-id (pid) value.
.
.NS
.PS
void XcursorNoticePutBitmap (
Display *dpy,
Drawable draw,
XImage *image)
.NE
Display *\fIdpy\fP,
Drawable \fIdraw\fP,
XImage *\fIimage\fP)
.PE
Update the image contents in the bitmap specified by the draw value
(a Pixmap-id).
The bitmap must have been created by XcursorNoticeCreateBitmap.
.
.NS
.PS
Cursor XcursorTryShapeBitmapCursor (
Display *dpy,
Pixmap source,
Pixmap mask,
XColor *foreground,
XColor *background,
unsigned int x,
unsigned int y)
.NE
Display *\fIdpy\fP,
Pixmap \fIsource\fP,
Pixmap \fImask\fP,
XColor *\fIforeground\fP,
XColor *\fIbackground\fP,
unsigned int \fIx\fP,
unsigned int \fIy\fP)
.PE
If the display supports either ARGB or themes,
try to load a cursor into Xcursor's cache
using the source parameter as a Pixmap-id.
using the \fIsource\fP parameter as a Pixmap-id.
The source may no longer be in the cache.
Xcursor uses the hash value to identify the desired image.
.
.NS
.PS
Cursor XcursorTryShapeCursor (
Display *dpy,
Font source_font,
Font mask_font,
unsigned int source_char,
unsigned int mask_char,
XColor _Xconst *foreground,
XColor _Xconst *background)
.NE
Display *\fIdpy\fP,
Font \fIsource_font\fP,
Font \fImask_font\fP,
unsigned int \fIsource_char\fP,
unsigned int \fImask_char\fP,
XColor _Xconst *\fIforeground\fP,
XColor _Xconst *\fIbackground\fP)
.PE
If the display supports either ARGB or themes,
try to load a cursor into Xcursor's cache
using the source_char parameter as a shape.
using the \fIsource_char\fP parameter as a shape.
Using
.RS
.bP
@ -683,7 +699,7 @@ the default size from XcursorGetDefaultSize,
.bP
the default theme from XcursorGetTheme, and
.bP
the source_char parameter as a shape,
the \fIsource_char\fP parameter as a shape,
.RE
.IP
Xcursor calls XcursorShapeLoadImages to load the cursor images.
@ -692,48 +708,56 @@ to load the cursor information.
.
.SS Display Information APIs
.
.NS
XcursorBool XcursorSupportsARGB (Display *\fIdpy\fP)
.NE
.PS
XcursorBool XcursorSupportsARGB (
Display *\fIdpy\fP)
.PE
Returns true if the display supports ARGB cursors.
Otherwise, cursors will be mapped to a core X cursor.
.
.NS
XcursorBool XcursorSupportsAnim (Display *\fIdpy\fP)
.NE
.PS
XcursorBool XcursorSupportsAnim (
Display *\fIdpy\fP)
.PE
Returns true if the display supports animated cursors.
Otherwise, cursors will be mapped to a core X cursor.
.
.NS
XcursorBool XcursorSetDefaultSize (Display *\fIdpy\fP, int \fIsize\fP)
.NE
.PS
XcursorBool XcursorSetDefaultSize (
Display *\fIdpy\fP,
int \fIsize\fP)
.PE
Sets the default size for cursors on the specified display. When loading
cursors, those whose nominal size is closest to this size will be preferred.
.
.NS
int XcursorGetDefaultSize (Display *\fIdpy\fP)
.NE
.PS
int XcursorGetDefaultSize (
Display *\fIdpy\fP)
.PE
Gets the default cursor size.
.
.NS
XcursorBool XcursorSetTheme (Display *\fIdpy\fP, const char *\fItheme\fP)
.NE
.PS
XcursorBool XcursorSetTheme (
Display *\fIdpy\fP,
const char *\fItheme\fP)
.PE
Sets the current theme name.
.
.NS
char *XcursorGetTheme (Display *\fIdpy\fP)
.NE
.PS
char *XcursorGetTheme (
Display *\fIdpy\fP)
.PE
Gets the current theme name.
.
.NS
.PS
XcursorBool XcursorGetThemeCore (
Display *\fIdpy\fP)
.NS
.PS
XcursorBool XcursorSetThemeCore (
Display *\fIdpy\fP,
XcursorBool \fItheme_core\fP)
.NE
Get or set property which tells Xcurses whether to
.PE
Get or set property which tells Xcursor whether to
enable themes for core cursors.
.
.SH "ENVIRONMENT VARIABLES"