From 821254578e15440d2177fff0b61f73590ae29869 Mon Sep 17 00:00:00 2001 From: "Thomas E. Dickey" Date: Tue, 16 Mar 2021 18:21:47 -0400 Subject: document the animation support functions Signed-off-by: Thomas E. Dickey --- man/Makefile.am | 3 ++ man/Xcursor.man | 103 ++++++++++++++++++++++++++---------------- man/XcursorAnimateCreate.man | 1 + man/XcursorAnimateDestroy.man | 1 + man/XcursorAnimateNext.man | 1 + 5 files changed, 70 insertions(+), 39 deletions(-) create mode 100644 man/XcursorAnimateCreate.man create mode 100644 man/XcursorAnimateDestroy.man create mode 100644 man/XcursorAnimateNext.man diff --git a/man/Makefile.am b/man/Makefile.am index 06f5f14..d998eeb 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -5,6 +5,9 @@ libman_PRE = \ $(Xcursor_shadows:=.man) Xcursor_shadows = \ + XcursorAnimateCreate \ + XcursorAnimateDestroy \ + XcursorAnimateNext \ XcursorCursorsCreate \ XcursorCursorsDestroy \ XcursorFileLoad \ diff --git a/man/Xcursor.man b/man/Xcursor.man index 72dc6f9..a366312 100644 --- a/man/Xcursor.man +++ b/man/Xcursor.man @@ -185,7 +185,7 @@ Inherits = \fItheme-name\fP Xcursor uses the first inherited \fItheme-name\fP, ignoring others which may exist in a given \*(``index.theme\*('' file. If it finds an inherited them, Xcursor searches along the path to use -those as well. +that as well. Xcursor ignores other \fIkeys\fP in the \*(``index.theme\*('' file, including \*(``Name\*('' (i.e., the name which a graphical application may use as the \fIpresentation name\fP). @@ -321,44 +321,6 @@ void XcursorCursorsDestroy ( Allocate and free arrays to hold multiple cursors. On allocation, \fIncursor\fP is set to zero, \fIref\fP is set to one. . -.SS Reading cursors. -. -.NS -Cursor XcursorImageLoadCursor( - Display *dpy, - const XcursorImage *image) -.NE -This creates a cursor, given the image to display. -It calls XcursorSupportsARGB to decide what type of cursor to create: -.RS -.bP -XRenderCreateCursor is used if ARGB is supported on the display, and -.bP -XCreatePixmapCursor is used otherwise. -.RE -. -.NS -Cursor XcursorImagesLoadCursor( - Display *dpy, - const XcursorImages *images) -.NE -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 -XcursorCursors *XcursorImagesLoadCursors( - Display *dpy, - const XcursorImages *images) -.NE -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. -.IP -Normally it returns the resulting array pointer. -On any failure, it discards the result XcursorCursorsDestroy, -and returns NULL. . .SS Reading and writing images. . @@ -520,6 +482,43 @@ XcursorCursors *XcursorLibraryLoadCursors ( These load cursors using the specified library \fIname\fP. The theme comes from the display. . +.NS +Cursor XcursorImageLoadCursor( + Display *dpy, + const XcursorImage *image) +.NE +This creates a cursor, given the image to display. +It calls XcursorSupportsARGB to decide what type of cursor to create: +.RS +.bP +XRenderCreateCursor is used if ARGB is supported on the display, and +.bP +XCreatePixmapCursor is used otherwise. +.RE +. +.NS +Cursor XcursorImagesLoadCursor( + Display *dpy, + const XcursorImages *images) +.NE +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 +XcursorCursors *XcursorImagesLoadCursors( + Display *dpy, + const XcursorImages *images) +.NE +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. +.IP +Normally it returns the resulting array pointer. +On any failure, it discards the result XcursorCursorsDestroy, +and returns NULL. +. .SS X Cursor Name APIs . .NS @@ -547,6 +546,32 @@ XcursorCursors *XcursorShapeLoadCursors ( .NE These map \fIshape\fP to a library name and then load the cursors. . +.SS Animated Cursors +.NS +XcursorAnimate * XcursorAnimateCreate ( + XcursorCursors *cursors) +.NE +Wrap the given array of cursors in a newly allocated XcursorAnimate structure, +which adds a sequence number used in XcursorAnimateNext. +. +.NS +void XcursorAnimateDestroy ( + XcursorAnimate *animate) +.NE +Discards the given \fIanimate\fP data, +freeing both the XcursorCursors array of cursors +as well as the XcursorAnimate structure. +. +.NS +Cursor XcursorAnimateNext ( + XcursorAnimate *animate) +.NE +Cyclically returns the next Cursor in the array, +incrementing the sequence number to prepare for the next call. +.IP +The caller is responsible for displaying the series of Cursor images. +Xcursor does not do that. +. .SS Display Information APIs . .NS diff --git a/man/XcursorAnimateCreate.man b/man/XcursorAnimateCreate.man new file mode 100644 index 0000000..690dab2 --- /dev/null +++ b/man/XcursorAnimateCreate.man @@ -0,0 +1 @@ +.so man__libmansuffix__/Xcursor.__libmansuffix__ diff --git a/man/XcursorAnimateDestroy.man b/man/XcursorAnimateDestroy.man new file mode 100644 index 0000000..690dab2 --- /dev/null +++ b/man/XcursorAnimateDestroy.man @@ -0,0 +1 @@ +.so man__libmansuffix__/Xcursor.__libmansuffix__ diff --git a/man/XcursorAnimateNext.man b/man/XcursorAnimateNext.man new file mode 100644 index 0000000..690dab2 --- /dev/null +++ b/man/XcursorAnimateNext.man @@ -0,0 +1 @@ +.so man__libmansuffix__/Xcursor.__libmansuffix__ -- cgit v1.2.3