summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThomas E. Dickey <dickey@invisible-island.net>2021-03-16 20:36:15 -0400
committerThomas E. Dickey <dickey@invisible-island.net>2021-03-17 19:10:22 -0400
commit8560016436dc521b373c5bb25860e009fa4e291d (patch)
tree2351cbb991a58e19910b30984426fa12b5570d71
parentbacd41c0c068c5f55b635a4887b4185ad2e3ea10 (diff)
document the API called from libX11
Signed-off-by: Thomas E. Dickey <dickey@invisible-island.net>
-rw-r--r--man/Makefile.am6
-rw-r--r--man/Xcursor.man101
-rw-r--r--man/XcursorImageHash.man1
-rw-r--r--man/XcursorImagesSetName.man1
-rw-r--r--man/XcursorNoticeCreateBitmap.man1
-rw-r--r--man/XcursorNoticePutBitmap.man1
-rw-r--r--man/XcursorTryShapeBitmapCursor.man1
-rw-r--r--man/XcursorTryShapeCursor.man1
8 files changed, 105 insertions, 8 deletions
diff --git a/man/Makefile.am b/man/Makefile.am
index 95e28ab..3f54985 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -33,17 +33,21 @@ Xcursor_shadows = \
XcursorGetThemeCore \
XcursorImageCreate \
XcursorImageDestroy \
+ XcursorImageHash \
XcursorImageLoadCursor \
XcursorImagesCreate \
XcursorImagesDestroy \
XcursorImagesLoadCursor \
XcursorImagesLoadCursors \
+ XcursorImagesSetName \
XcursorLibraryLoadCursor \
XcursorLibraryLoadCursors \
XcursorLibraryLoadImage \
XcursorLibraryLoadImages \
XcursorLibraryPath \
XcursorLibraryShape \
+ XcursorNoticeCreateBitmap \
+ XcursorNoticePutBitmap \
XcursorSetDefaultSize \
XcursorSetTheme \
XcursorSetThemeCore \
@@ -53,6 +57,8 @@ Xcursor_shadows = \
XcursorShapeLoadImages \
XcursorSupportsARGB \
XcursorSupportsAnim \
+ XcursorTryShapeBitmapCursor \
+ XcursorTryShapeCursor \
XcursorXcFileLoad \
XcursorXcFileLoadAllImages \
XcursorXcFileLoadImage \
diff --git a/man/Xcursor.man b/man/Xcursor.man
index d5450f6..34f84e7 100644
--- a/man/Xcursor.man
+++ b/man/Xcursor.man
@@ -398,14 +398,14 @@ These parallel the stdio FILE interfaces above, but take filenames.
.SS Reading library images
.NS
XcursorImage *XcursorLibraryLoadImage (
- const char *\fIname\fP,
- const char *\fItheme\fP,
- int \fIsize\fP)
+ const char *\fIname\fP,
+ const char *\fItheme\fP,
+ int \fIsize\fP)
.NS
XcursorImages *XcursorLibraryLoadImages (
- const char *\fIname\fP,
- const char *\fItheme\fP,
- int \fIsize\fP)
+ const char *\fIname\fP,
+ const char *\fItheme\fP,
+ int \fIsize\fP)
.NE
These search the library path, loading the first file found
of the desired \fIsize\fP,
@@ -426,8 +426,9 @@ The two functions differ by more than the number of images loaded:
.bP
XcursorLibraryLoadImage calls XcursorFileLoadImage but
.bP
-XcursorLibraryLoadImages calls XcursorFileLoadImages and
-on success calls XcursorImagesSetName to associate \fIname\fP with the result.
+XcursorLibraryLoadImages calls XcursorFileLoadImages,
+and (on success)
+it calls XcursorImagesSetName to associate \fIname\fP with the result.
.RE
.
.SS Library attributes
@@ -605,6 +606,90 @@ incrementing the sequence number to prepare for the next call.
The caller is responsible for displaying the series of Cursor images.
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
+void XcursorImageHash (
+ XImage *image,
+ unsigned char hash[XCURSOR_BITMAP_HASH_SIZE])
+.NE
+Compute a hash of the image,
+to display when the environment variable XCURSOR_DISCOVER is set.
+.
+.NS
+void XcursorImagesSetName (
+ XcursorImages *images,
+ const char *name)
+.NE
+Associates the given name with the images.
+.
+.NS
+void XcursorNoticeCreateBitmap (
+ Display *dpy,
+ Pixmap pid,
+ unsigned int width,
+ unsigned int height)
+.NE
+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
+void XcursorNoticePutBitmap (
+ Display *dpy,
+ Drawable draw,
+ XImage *image)
+.NE
+Update the image contents in the bitmap specified by the draw value
+(a Pixmap-id).
+The bitmap must have been created by XcursorNoticeCreateBitmap.
+.
+.NS
+Cursor XcursorTryShapeBitmapCursor (
+ Display *dpy,
+ Pixmap source,
+ Pixmap mask,
+ XColor *foreground,
+ XColor *background,
+ unsigned int x,
+ unsigned int y)
+.NE
+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.
+The source may no longer be in the cache.
+Xcursor uses the hash value to identify the desired image.
+.
+.NS
+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
+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
+.RS
+.bP
+the default size from XcursorGetDefaultSize,
+.bP
+the default theme from XcursorGetTheme, and
+.bP
+the source_char parameter as a shape,
+.RE
+.IP
+Xcursor calls XcursorShapeLoadImages to load the cursor images.
+If successful, Xcursor uses XcursorImagesLoadCursor
+to load the cursor information.
+.
.SS Display Information APIs
.
.NS
diff --git a/man/XcursorImageHash.man b/man/XcursorImageHash.man
new file mode 100644
index 0000000..690dab2
--- /dev/null
+++ b/man/XcursorImageHash.man
@@ -0,0 +1 @@
+.so man__libmansuffix__/Xcursor.__libmansuffix__
diff --git a/man/XcursorImagesSetName.man b/man/XcursorImagesSetName.man
new file mode 100644
index 0000000..690dab2
--- /dev/null
+++ b/man/XcursorImagesSetName.man
@@ -0,0 +1 @@
+.so man__libmansuffix__/Xcursor.__libmansuffix__
diff --git a/man/XcursorNoticeCreateBitmap.man b/man/XcursorNoticeCreateBitmap.man
new file mode 100644
index 0000000..690dab2
--- /dev/null
+++ b/man/XcursorNoticeCreateBitmap.man
@@ -0,0 +1 @@
+.so man__libmansuffix__/Xcursor.__libmansuffix__
diff --git a/man/XcursorNoticePutBitmap.man b/man/XcursorNoticePutBitmap.man
new file mode 100644
index 0000000..690dab2
--- /dev/null
+++ b/man/XcursorNoticePutBitmap.man
@@ -0,0 +1 @@
+.so man__libmansuffix__/Xcursor.__libmansuffix__
diff --git a/man/XcursorTryShapeBitmapCursor.man b/man/XcursorTryShapeBitmapCursor.man
new file mode 100644
index 0000000..690dab2
--- /dev/null
+++ b/man/XcursorTryShapeBitmapCursor.man
@@ -0,0 +1 @@
+.so man__libmansuffix__/Xcursor.__libmansuffix__
diff --git a/man/XcursorTryShapeCursor.man b/man/XcursorTryShapeCursor.man
new file mode 100644
index 0000000..690dab2
--- /dev/null
+++ b/man/XcursorTryShapeCursor.man
@@ -0,0 +1 @@
+.so man__libmansuffix__/Xcursor.__libmansuffix__