document the animation support functions

Signed-off-by: Thomas E. Dickey <dickey@invisible-island.net>

5 files changed, 70 insertions, 39 deletions

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__