diff options
| author | Walter Harms <wharms@bfs.de> | 2019-12-24 17:20:09 +0100 |
|---|---|---|
| committer | Walter Harms <wharms@bfs.de> | 2019-12-24 17:20:09 +0100 |
| commit | e48e649eb04f95ffbdbd0c8bb77d7131142f5e9a (patch) | |
| tree | 12061a9b802462749a6e3e06511ab9027a17952c | |
| parent | b0fc485495a694816d76a43978e2cfd5575c554d (diff) | |
add man pages based on doc/xpm.PS
More or less hand crafted man pages based on xpm.PS.
Prototypes are still in K&R, see also is a dud
Signed-off-by: Walter Harms <wharms@bfs.de>
43 files changed, 1023 insertions, 4 deletions
diff --git a/man/Makefile.am b/man/Makefile.am index 5734e51..b422a50 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -22,13 +22,82 @@ # appmandir = $(APP_MAN_DIR) -appman_PRE = sxpm.man cxpm.man +libmandir = $(LIB_MAN_DIR) +libman_PRE=$(all_shadows:=.man) \ + xpmmisc.man \ + xpmcreatepixmap.man \ + xpmwrite.man \ + xpmcreateimage.man \ + xpmcreatebuffer.man \ + xpmread.man \ + xpmcreatedata.man \ + xpmcreatexpmimage.man + +libman_DATA = $(libman_PRE:man=$(LIB_MAN_SUFFIX)) + +appman_PRE = sxpm.man cxpm.man appman_DATA = $(appman_PRE:man=$(APP_MAN_SUFFIX)) -EXTRA_DIST = $(appman_PRE) -CLEANFILES = $(appman_DATA) -SUFFIXES = .$(APP_MAN_SUFFIX) .man +EXTRA_DIST = $(appman_PRE) $(libman_PRE) +CLEANFILES = $(appman_DATA) $(libman_DATA) +SUFFIXES = .$(APP_MAN_SUFFIX) .$(LIB_MAN_SUFFIX) .man + +all_shadows = \ + $(xpmcreatebuffer_shadows) \ + $(xpmcreatedata_shadows) \ + $(xpmcreateimage_shadows) \ + $(xpmcreatepixmap_shadows) \ + $(xpmcreatexpmimage_shadows) \ + $(xpmmisc_shadows) \ + $(xpmread_shadows) \ + $(xpmwrite_shadows) + +xpmcreatebuffer_shadows = \ + XpmCreateBufferFromImage \ + XpmCreateBufferFromPixmap \ + XpmCreateBufferFromXpmImage +xpmcreatedata_shadows = \ + XpmCreateDataFromImage \ + XpmCreateDataFromPixmap \ + XpmCreateDataFromXpmImage +xpmcreateimage_shadows = \ + XpmCreateImageFromBuffer \ + XpmCreateImageFromData \ + XpmCreateImageFromXpmImage +xpmcreatepixmap_shadows = \ + XpmCreatePixmapFromBuffer \ + XpmCreatePixmapFromData \ + XpmCreatePixmapFromXpmImage +xpmcreatexpmimage_shadows = \ + XpmCreateXpmImageFromBuffer \ + XpmCreateXpmImageFromData \ + XpmCreateXpmImageFromImage \ + XpmCreateXpmImageFromPixmap +xpmmisc_shadows = \ + XpmLibraryVersion \ + XpmGetErrorString \ + XpmFree \ + XpmFreeExtensions \ + XpmAttributesSize \ + XpmFreeAttributes \ + XpmFreeXpmImage \ + XpmFreeXpmInfo +xpmread_shadows = \ + XpmReadFileToImage \ + XpmReadFileToPixmap \ + XpmReadFileToBuffer \ + XpmReadFileToData \ + XpmReadFileToXpmImage + +xpmwrite_shadows = \ + XpmWriteFileFromPixmap \ + XpmWriteFileFromImage \ + XpmWriteFileFromXpmImage \ + XpmWriteFileFromBuffer # String replacements in MAN_SUBSTS now come from xorg-macros.m4 via configure .man.$(APP_MAN_SUFFIX): $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@ + +.man.$(LIB_MAN_SUFFIX): + $(AM_V_GEN)$(SED) $(MAN_SUBSTS) < $< > $@ diff --git a/man/XpmAttributesSize.man b/man/XpmAttributesSize.man new file mode 100644 index 0000000..2cc73fa --- /dev/null +++ b/man/XpmAttributesSize.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmAttributesSize.__libmansuffix__ diff --git a/man/XpmCreateBufferFromImage.man b/man/XpmCreateBufferFromImage.man new file mode 100644 index 0000000..5742ed7 --- /dev/null +++ b/man/XpmCreateBufferFromImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateBufferFromImage.__libmansuffix__ diff --git a/man/XpmCreateBufferFromPixmap.man b/man/XpmCreateBufferFromPixmap.man new file mode 100644 index 0000000..aa5b995 --- /dev/null +++ b/man/XpmCreateBufferFromPixmap.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateBufferFromPixmap.__libmansuffix__ diff --git a/man/XpmCreateBufferFromXpmImage.man b/man/XpmCreateBufferFromXpmImage.man new file mode 100644 index 0000000..a89220c --- /dev/null +++ b/man/XpmCreateBufferFromXpmImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateBufferFromXpmImage.__libmansuffix__ diff --git a/man/XpmCreateDataFromImage.man b/man/XpmCreateDataFromImage.man new file mode 100644 index 0000000..a3869ec --- /dev/null +++ b/man/XpmCreateDataFromImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateDataFromImage.__libmansuffix__ diff --git a/man/XpmCreateDataFromPixmap.man b/man/XpmCreateDataFromPixmap.man new file mode 100644 index 0000000..bd6e9d5 --- /dev/null +++ b/man/XpmCreateDataFromPixmap.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateDataFromPixmap.__libmansuffix__ diff --git a/man/XpmCreateDataFromXpmImage.man b/man/XpmCreateDataFromXpmImage.man new file mode 100644 index 0000000..6f07b22 --- /dev/null +++ b/man/XpmCreateDataFromXpmImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateDataFromXpmImage.__libmansuffix__ diff --git a/man/XpmCreateImageFromBuffer.man b/man/XpmCreateImageFromBuffer.man new file mode 100644 index 0000000..e50205d --- /dev/null +++ b/man/XpmCreateImageFromBuffer.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateImageFromBuffer.__libmansuffix__ diff --git a/man/XpmCreateImageFromData.man b/man/XpmCreateImageFromData.man new file mode 100644 index 0000000..81a25a7 --- /dev/null +++ b/man/XpmCreateImageFromData.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateImageFromData.__libmansuffix__ diff --git a/man/XpmCreateImageFromXpmImage.man b/man/XpmCreateImageFromXpmImage.man new file mode 100644 index 0000000..7923e49 --- /dev/null +++ b/man/XpmCreateImageFromXpmImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateImageFromXpmImage.__libmansuffix__ diff --git a/man/XpmCreatePixmapFromBuffer.man b/man/XpmCreatePixmapFromBuffer.man new file mode 100644 index 0000000..ab50d72 --- /dev/null +++ b/man/XpmCreatePixmapFromBuffer.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreatePixmapFromBuffer.__libmansuffix__ diff --git a/man/XpmCreatePixmapFromData.man b/man/XpmCreatePixmapFromData.man new file mode 100644 index 0000000..50a9dfc --- /dev/null +++ b/man/XpmCreatePixmapFromData.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreatePixmapFromData.__libmansuffix__ diff --git a/man/XpmCreatePixmapFromXpmImage.man b/man/XpmCreatePixmapFromXpmImage.man new file mode 100644 index 0000000..9f2d7a1 --- /dev/null +++ b/man/XpmCreatePixmapFromXpmImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreatePixmapFromXpmImage.__libmansuffix__ diff --git a/man/XpmCreateXpmImageFromBuffer.man b/man/XpmCreateXpmImageFromBuffer.man new file mode 100644 index 0000000..4963393 --- /dev/null +++ b/man/XpmCreateXpmImageFromBuffer.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateXpmImageFromBuffer.__libmansuffix__ diff --git a/man/XpmCreateXpmImageFromData.man b/man/XpmCreateXpmImageFromData.man new file mode 100644 index 0000000..5254051 --- /dev/null +++ b/man/XpmCreateXpmImageFromData.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateXpmImageFromData.__libmansuffix__ diff --git a/man/XpmCreateXpmImageFromImage.man b/man/XpmCreateXpmImageFromImage.man new file mode 100644 index 0000000..493c880 --- /dev/null +++ b/man/XpmCreateXpmImageFromImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateXpmImageFromImage.__libmansuffix__ diff --git a/man/XpmCreateXpmImageFromPixmap.man b/man/XpmCreateXpmImageFromPixmap.man new file mode 100644 index 0000000..2306994 --- /dev/null +++ b/man/XpmCreateXpmImageFromPixmap.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmCreateXpmImageFromPixmap.__libmansuffix__ diff --git a/man/XpmFree.man b/man/XpmFree.man new file mode 100644 index 0000000..762de07 --- /dev/null +++ b/man/XpmFree.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmFree.__libmansuffix__ diff --git a/man/XpmFreeAttributes.man b/man/XpmFreeAttributes.man new file mode 100644 index 0000000..bcb2d33 --- /dev/null +++ b/man/XpmFreeAttributes.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmFreeAttributes.__libmansuffix__ diff --git a/man/XpmFreeExtensions.man b/man/XpmFreeExtensions.man new file mode 100644 index 0000000..334b8aa --- /dev/null +++ b/man/XpmFreeExtensions.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmFreeExtensions.__libmansuffix__ diff --git a/man/XpmFreeXpmImage.man b/man/XpmFreeXpmImage.man new file mode 100644 index 0000000..2d93503 --- /dev/null +++ b/man/XpmFreeXpmImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmFreeXpmImage.__libmansuffix__ diff --git a/man/XpmFreeXpmInfo.man b/man/XpmFreeXpmInfo.man new file mode 100644 index 0000000..09823fd --- /dev/null +++ b/man/XpmFreeXpmInfo.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmFreeXpmInfo.__libmansuffix__ diff --git a/man/XpmGetErrorString.man b/man/XpmGetErrorString.man new file mode 100644 index 0000000..2f26336 --- /dev/null +++ b/man/XpmGetErrorString.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmGetErrorString.__libmansuffix__ diff --git a/man/XpmLibraryVersion.man b/man/XpmLibraryVersion.man new file mode 100644 index 0000000..753f38d --- /dev/null +++ b/man/XpmLibraryVersion.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmLibraryVersion.__libmansuffix__ diff --git a/man/XpmReadFileToBuffer.man b/man/XpmReadFileToBuffer.man new file mode 100644 index 0000000..1cbc427 --- /dev/null +++ b/man/XpmReadFileToBuffer.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmReadFileToBuffer.__libmansuffix__ diff --git a/man/XpmReadFileToData.man b/man/XpmReadFileToData.man new file mode 100644 index 0000000..2130bac --- /dev/null +++ b/man/XpmReadFileToData.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmReadFileToData.__libmansuffix__ diff --git a/man/XpmReadFileToImage.man b/man/XpmReadFileToImage.man new file mode 100644 index 0000000..b40e769 --- /dev/null +++ b/man/XpmReadFileToImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmReadFileToImage.__libmansuffix__ diff --git a/man/XpmReadFileToPixmap.man b/man/XpmReadFileToPixmap.man new file mode 100644 index 0000000..42604bf --- /dev/null +++ b/man/XpmReadFileToPixmap.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmReadFileToPixmap.__libmansuffix__ diff --git a/man/XpmReadFileToXpmImage.man b/man/XpmReadFileToXpmImage.man new file mode 100644 index 0000000..cbf3fc4 --- /dev/null +++ b/man/XpmReadFileToXpmImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmReadFileToXpmImage.__libmansuffix__ diff --git a/man/XpmWriteFileFromBuffer.man b/man/XpmWriteFileFromBuffer.man new file mode 100644 index 0000000..4cad67d --- /dev/null +++ b/man/XpmWriteFileFromBuffer.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmWriteFileFromBuffer.__libmansuffix__ diff --git a/man/XpmWriteFileFromData.man b/man/XpmWriteFileFromData.man new file mode 100644 index 0000000..ee76137 --- /dev/null +++ b/man/XpmWriteFileFromData.man @@ -0,0 +1 @@ +.so man__libmansuffix__/xpmwrite.man.__libmansuffix__ diff --git a/man/XpmWriteFileFromImage.man b/man/XpmWriteFileFromImage.man new file mode 100644 index 0000000..2e8d6ea --- /dev/null +++ b/man/XpmWriteFileFromImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmWriteFileFromImage.__libmansuffix__ diff --git a/man/XpmWriteFileFromPixmap.man b/man/XpmWriteFileFromPixmap.man new file mode 100644 index 0000000..3cda218 --- /dev/null +++ b/man/XpmWriteFileFromPixmap.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmWriteFileFromPixmap.__libmansuffix__ diff --git a/man/XpmWriteFileFromXpmImage.man b/man/XpmWriteFileFromXpmImage.man new file mode 100644 index 0000000..430db12 --- /dev/null +++ b/man/XpmWriteFileFromXpmImage.man @@ -0,0 +1 @@ +.so man__libmansuffix__/XpmWriteFileFromXpmImage.__libmansuffix__ diff --git a/man/xpmcreatebuffer.man b/man/xpmcreatebuffer.man new file mode 100644 index 0000000..3901870 --- /dev/null +++ b/man/xpmcreatebuffer.man @@ -0,0 +1,91 @@ +.\" Copyright (c) 2019 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software furnished to do so, subject to +.\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealing in this Software without prior written authorization +.\" from the X Consortium. +.\" + +.TH XpmCreateBuffer __libmansuffix__ __xorgversion__ "libXpm functions" +.SH NAME +XpmCreateBuffer \- create an Xpm-Buffer + +.SH SYNOPSIS +.HP +int XpmCreateBufferFromImage(display, buffer_return, image, shapeimage, attributes) + Display *display; + char **buffer_return; + XImage*image; + XImage*shapeimage; + XpmAttributes *attributes; + +.HP +int XpmCreateBufferFromPixmap(display, buffer_return, pixmap, shapemask, attributes) +Display *display; +char **buffer_return; +Pixmappixmap; +Pixmapshapemask; +XpmAttributes *attributes; + +.HP +int XpmCreateBufferFromXpmImage(buffer_return, image, info) +char **buffer_return; +XpmImage*image; +XpmInfo*info; + +.SH ARGUMENTS +.nf +display Specifies the connection to the X server. +buffer_return Returns the buffer which is created. +image Specifies the image. +shapeimage Specifies the shape mask image. +attributes Specifies the location of a structure containing information (or NULL). +info Specifies the location of a structure to get possible information (or NULL). +.fi + +.SH DESCRIPTION + +.SS XpmCreateBufferFromPixmap +XpmCreateBufferFromPixmap creates an XPM buffer from a Pixmap. +The XpmCreateBufferFromPixmap function works as XpmWriteFileFromPixmap(), it just calls +XpmCreateBufferFromImage instead of XpmWriteFileFromImage. Once again, the caller should free the buffer using +XpmFree when finished. + +As a convenience, the XpmReadFileToBuffer and XpmWriteFileFromBuffer are provided to copy a file to a buffer +and to write a file from a buffer. Thus for instance one may decide to use XpmReadFileToBuffer, +XpmCreatePixmapFromBuffer, and XpmFree instead of XpmReadFileToPixmap. On some systems this may lead to a +performance improvement, since the parsing will be performed in memory, but it uses more memory. + +.SS XpmCreateBufferFromImage +The XpmCreateBufferFromImage works as XpmWriteFileFromImage(), it just writes to a malloc’ed buffer instead of to a file. +The caller should free the buffer using XpmFree when finished. + +.SS XpmCreateBufferFromXpmImage. +To create an XPM buffer from an XpmImage, use XpmCreateBufferFromXpmImage. +The XpmCreateBufferFromXpmImage writes out the givenimage to a single block malloc’ed buffer inXPM format. +If insufficient working storage is allocated, it returns XpmNoMemory, and returns XpmSuccess on success. +If the passed XpmInfo structure pointer is not NULL, XpmCreateBufferFromXpmImage looks for the following +attributes: XpmComments, XpmExtensions, and XpmHotspot, and writes the related information out as well. +The caller should free the buffer using XpmFree when finished. + +.SH "SEE ALSO" +.BR XpmCreateBufferFromImage(__libmansuffix__) , +.BR XpmCreateBufferFromPixmap(__libmansuffix__) , +.BR XpmCreateBufferFromXpmImage(__libmansuffix__) diff --git a/man/xpmcreatedata.man b/man/xpmcreatedata.man new file mode 100644 index 0000000..a59f528 --- /dev/null +++ b/man/xpmcreatedata.man @@ -0,0 +1,90 @@ +.\" Copyright (c) 2019 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software furnished to do so, subject to +.\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealing in this Software without prior written authorization +.\" from the X Consortium. +.\" + +.TH XpmCreateData __libmansuffix__ __xorgversion__ "libXpm functions" +.SH NAME +XpmCreateData \- create an Data structure + +.SH SYNOPSIS +.HP +int XpmCreateDataFromImage(display, data_return, image, shapeimage, attributes) + Display *display; + char ***data_return; + XImage*image; + XImage*shapeimage; + XpmAttributes *attributes; + +.HP +int XpmCreateDataFromPixmap(display, data_return, pixmap, shapemask, attributes) + Display *display; + char ***data_return; + Pixmappixmap; + Pixmapshapemask; + XpmAttributes *attributes; + +.HP +int XpmCreateDataFromXpmImage(data_return, image, info) +char ***data_return; +XxpmImage*image; +XpmInfo*info; + + +.SH ARGUMENTS +.nf +display Specifies the connection to the X server. +data_return Returns the data which is created. +pixmap Specifies the pixmap. +shapemask Specifies the shape mask pixmap. +attributes Specifies the location of a structure containing information (or NULL). +info Specifies the location of a structure to get information. +image Specifies the image +.fi + +.SH DESCRIPTION +.SS XpmCreateDataFromImage +In some cases, one may want to create an XPM data from an XImage, to do so use XpmCreateDataFromImage. +The XpmCreateDataFromImage function exactly works asXpmWriteFileFromImage() does and returns the same way. +It just writes to a single block malloc’ed data instead of to a file. +It is the caller’s responsibility to free the data, using XpmFree when finished. + +.SS XpmCreateDataFromPixmap +XpmCreateDataFromPixmap creates an XPM data from a Pixmap. +The XpmCreateDataFromPixmap function uses XGetImage to get from the given pixmaps +the related X images which are passed to XpmCreateDataFromImage. +Then it destroys the created images using XDestroyImage. +XpmCreateDataFromPixmap returns the same errors as XpmCreateDataFromImage. + +.SS XpmCreateDataFromXpmImage +XpmCreateDataFromXpmImage creates an XPM data from an XmImage. +The XpmCreateDataFromXpmImage function writes out the given image to a single block malloc’ed data in XPM format. +If insufficient working storage is allocated, it returns XpmNoMemory, and returns XpmSuccess on success. +If the passed XpmInfo structure pointer is not NULL, XpmCreateDataFromXpmImage looks for the following attributes: +XpmExtensions, and XpmHotspot, and writes the related information out as well. +It is the caller’s responsibility to free the data, using XpmFree when finished. + +.SH "SEE ALSO" +.BR XpmCreateDataFromImage(__libmansuffix__) , +.BR XpmCreateDataFromPixmap(__libmansuffix__) , +.BR XpmCreateDataFromXpmImage(__libmansuffix__) diff --git a/man/xpmcreateimage.man b/man/xpmcreateimage.man new file mode 100644 index 0000000..348aa24 --- /dev/null +++ b/man/xpmcreateimage.man @@ -0,0 +1,93 @@ +.\" Copyright (c) 2019 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software furnished to do so, subject to +.\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealing in this Software without prior written authorization +.\" from the X Consortium. +.\" + +.TH XpmCreateImage __libmansuffix__ __xorgversion__ "libXpm functions" +.SH NAME +XpmCreateImage \- create an Xpm-image +.SH SYNOPSIS +.HP +int XpmCreateImageFromData(display, data, image_return, shapeimage_return, attributes) +Display *display; +char **data; +XImage**image_return; +XImage**shapeimage_return; +XpmAttributes *attributes; + +.HP +int XpmCreateImageFromBuffer(display, buffer, image_return, shapeimage_return, attributes) + Display *display; + char *buffer; + XImage**image_return; + XImage**shapeimage_return; + XpmAttributes *attributes; +.HP +int XpmCreateImageFromXpmImage(display, image, image_return, shapeimage_return, attributes) + Display *display; + XpmImage*image; + XImage*image_return; + XImage*shapeimage_return; + XpmAttributes *attributes; + +.SH ARGUMENTS +.nf +display Specifies the connection to the X server. +data Specifies the location of the data. +image_return Returns the image which is created. +shapeimage_return Returns the shape mask image which is created if the color None is used. +attributes Specifies the location of a structure to get and store information (or NULL). +shapeimage Specifies the shape mask image which is created if any. +.fi + +.SH DESCRIPTION + +.SS XpmCreateImageFromData +To create an XImage from an XPM data, use XpmCreateImageFromData. + +The XpmCreateImageFromData function allows you to include in your C program an XPM file which was +written out by functions such as XpmWriteFileFromImage or XpmWriteFileFromPixmap without reading in the file. +XpmCreateImageFromData exactly works as XpmReadFileToImage() does and returns the same way. +It just reads data instead of a file. +Here again, it is the caller’s responsibeility to free the returned images, the colors +and possibly the data returned into the XpmAttributes structure. + +.SS XpmCreateImageFromBuffer +To create an XImage from an XPM buffer, use XpmCreateImageFromBuffer. +The XpmCreateImageFromBuffer works the same way as XpmReadFileToImage(), +it just parses the buffer instead of the file. +Be aware that the feature provided on some systems by XpmReadFileToImage +to deal with compressed files is not available here. + +.SS XpmCreateImageFromXpmImage +To create an XImage from an XpmImage, use XpmCreateImageFromXpmImage. +From the givenXpmImage andXpmAttributes if notNULL, XpmCreateImageFromXpmImage allocates colors +and creates X images following the same mechanism as XpmReadFileToImage(). +When finished the caller must free the images using XDestroyImage, +the colors using XFreeColors, and possibly the +data returned into the XpmAttributes using XpmFreeAttributes(). + +.SH "SEE ALSO" +.BR XpmCreateImageFromBuffer(__libmansuffix__) , +.BR XpmCreateImageFromData(__libmansuffix__) , +.BR XpmCreateImageFromXpmImage(__libmansuffix__) diff --git a/man/xpmcreatepixmap.man b/man/xpmcreatepixmap.man new file mode 100644 index 0000000..db8acd2 --- /dev/null +++ b/man/xpmcreatepixmap.man @@ -0,0 +1,92 @@ +.\" Copyright (c) 2019 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software furnished to do so, subject to +.\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealing in this Software without prior written authorization +.\" from the X Consortium. +.\" + +.TH XpmCreatePixmap __libmansuffix__ __xorgversion__ "libXpm functions" +.SH NAME +XpmCreatePixmap \- create a pixmap +.SH SYNOPSIS +.HP +int XpmCreatePixmapFromData(display, d, data, pixmap_return, shapemask_return, attributes) + Display *display; + Drawable d; + char **data; + Pixmap*pixmap_return; + Pixmap*shapemask_return; + XpmAttributes *attributes; +.HP +int XpmCreatePixmapFromBuffer(display, d, buffer, pixmap_return, shapemask_return, attributes) + Display *display; + Drawable d; + char *buffer; + Pixmap*pixmap_return; + Pixmap*shapemask_return; + XpmAttributes *attributes; + +.HP +int XpmCreatePixmapFromXpmImage(display, d, image, pixmap_return, shapemask_return, attributes) + Display *display; + Drawable d; + XpmImage*image; + Pixmap*pixmap_return; + Pixmap*shapemask_return; + XpmAttributes *attributes; + + +.SH ARGUMENTS +.nf +display Specifies the connection to the X server. +d Specifies which screen the pixmap is created on. +buffer Specifies the location of the buffer. +pixmap_return Returns the pixmap which is created if the color None. +shapemask_return Returns the shape mask pixmap which is created if the color None is used. +attributes Specifies the location of a structure to get and store information. +image Specifies the XpmImage. +.fi +.SH DESCRIPTION +.SS XpmCreatePixmapFromData +To create a Pixmap from an XPM data, use XpmCreatePixmapFromData. +The XpmCreatePixmapFromData function creates X images usingXpmCreateImageFromData() and +thus returns the same errors. In addition on success it then creates the related pixmaps, usingXPutImage, +which are returned to pixmap_return and shapemask_return if not NULL, and finally destroys the created images using XDestroyImage. +Do not forget to free the returned pixmaps, the colors, and possibly the data returned into the XpmAttributes structure when done. + +.SS XpmCreatePixmapFromBuffer +To create a Pixmap from an XPM buffer, use XpmCreatePixmapFromBuffer. +The XpmCreatePixmapFromBuffer function works the same way asXpmReadFileToPixmap (), +it just calls XpmCreateImageFromBuffer instead of XpmReadFileToImage. + +.SS XpmCreatePixmapFromXpmImage +XpmCreatePixmapFromXpmImage creates X images calling XpmCreateImageFromXpmImage () with +the given XpmImage and XpmAttributes, then it creates the related pixmaps which are returned topixmap_return +and shapemask_return using XPutImage. +Finally it destroys the X images with XDestroyImage. +When finished the caller must free the pixmaps using XFreePixmap, the colors using XFreeColors or the appication +equivalent function when the standard Xlib functions are not used, and possibly the data returned into the +XpmAttributes using XpmFreeAttributes. + +.SH "SEE ALSO" +.BR XpmCreatePixmapFromBuffer(__libmansuffix__) , +.BR XpmCreatePixmapFromData(__libmansuffix__) , +.BR XpmCreatePixmapFromXpmImage(__libmansuffix__) diff --git a/man/xpmcreatexpmimage.man b/man/xpmcreatexpmimage.man new file mode 100644 index 0000000..2429273 --- /dev/null +++ b/man/xpmcreatexpmimage.man @@ -0,0 +1,118 @@ +.\" Copyright (c) 2019 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software furnished to do so, subject to +.\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealing in this Software without prior written authorization +.\" from the X Consortium. +.\" + +.TH XpmCreateXpmImage __libmansuffix__ __xorgversion__ "libXpm functions" +.SH NAME +XpmCreateXpmImage \- create an Xpm image +.SH SYNOPSIS +.HP +int XpmCreateXpmImageFromData(data, image, info) + char **data; + XpmImage*image; + XpmInfo*info; + +.HP +int XpmCreateXpmImageFromBuffer(buffer, image, info) +char *buffer; +XpmImage*image; +XpmInfo*info; + +.HP +int XpmCreateXpmImageFromImage(display, image, shapeimage, xpmimage, attributes) + Display *display; + XImage*image; + XImage*shapeimage; + XpmImage*xpmimage + XpmAttributes *attributes; + +.HP +int XpmCreateXpmImageFromPixmap(display, pixmap, shapemask, xpmimage, attributes) + Display *display; + Pixmap*pixmap; + Pixmap*shapemask; + XpmImage*xpmimage; + XpmAttributes *attributes; + +.SH ARGUMENTS +.nf +data Specifies the location of the data. +image Specifies the image structure location. +info Specifies the location of an XpmInfo structure to get and store information (or NULL). +display Specifies the connection to the X server. +image Specifies the image which is created. +shapeimage Specifies the shape mask image which is created if any. +xpmimage Specifies the location of an XpmImage structure. +attributes Specifies the location of a structure containing information (or NULL). +.fi +.SH DESCRIPTION +.SS XpmCreateXpmImageFromBuffer +To create an XpmImage from an XPM buffer, use XpmCreateXpmImageFromBuffer.a +The XpmCreateXpmImageFromBuffer reads the given buffer to fill in the given XpmImage structure. +If the buffer does not contain valid XPM data, it returns XpmFileInvalid. +If insufficient working storage is allocated, it returns XpmNoMemory, and returns XpmSuccess on success. +If the passed XpmInfo structure pointer is not NULL, XpmCreateXpmImageFromBuffer looks for the following attributes: +XpmReturnComments and XpmReturnExtensions, and sets possibly the XpmHotspot attribute when returning. +As specified in the table (page 28), if the data related to the attributes XpmReturnComments and +XpmReturnExtensions cannot be returned as requested because of insufficient memory storage, +XpmCreateXpmImageFromBuffer will change the valuemask to mention this and will try to continue. +So the caller should check on this before accessing requested data. + +Note: The valuemask of the passed XpmInfo structure must be set to some valid value, +at least zero, otherwise unpredictable errors can occur. + +.SS XpmCreateXpmImageFromData +To create an XpmImage from an XPM data, use XpmCreateXpmImageFromData. +XpmCreateXpmImageFromData fills in the given XpmImage structure from the given data. If the data does not +contain validXPM data, it returnsXpmFileInvalid. If insufficient working storage is allocated, it returnsXpm- +NoMemory, on success it returns XpmSuccess. +If the passed XpmInfo structure pointer is not NULL, XpmCreateXpmImageFromData looks for the following attributes: +XpmReturnExtensions, and sets possibly the XpmHotspot attribute when returning. +As specified in the table (page 28), if the data related to the attribute +XpmReturnExtensions cannot be returned as requested because of +insufficient memory storage,XpmCreateXpmImageFromData will change the valuemask to mention this and will +try to continue. +So the caller should check on this before accessing requested data. + +Note: The valuemask of the passed XpmInfo structure must be set to some valid value, at least zero, +otherwise unpredictable errors can occur. + +.SS XpmCreateXpmImageFromImage +To create an XpmImage from an XImage, use XpmCreateXpmImageFromImage. +From the given X images and XpmAttributes if not NULL, XpmCreateXpmImageFromImage creates an +XpmImage following the same mechanism as XpmWriteFileFromImage. + +.SS XpmCreateXpmImageFromPixmap +To create an XpmImage from a Pixmap, use XpmCreateXpmImageFromPixmap. +From the given pixmaps and XpmAttributes if not NULL, XpmCreateXpmImageFromPixmap gets the related Ximages +by calling XGetImage, then it gives them to XpmCreateXpmImageFromImage() to create an +XpmImage which is returned to xpmimage. +Finally it destroys the created X images using XDestroyImage. + + +.SH "SEE ALSO" +.BR XpmCreateXpmImageFromBuffer(__libmansuffix__) , +.BR XpmCreateXpmImageFromData(__libmansuffix__) , +.BR XpmCreateXpmImageFromImage(__libmansuffix__) , +.BR XpmCreateXpmImageFromPixmap(__libmansuffix__) diff --git a/man/xpmmisc.man b/man/xpmmisc.man new file mode 100644 index 0000000..7e1cbc5 --- /dev/null +++ b/man/xpmmisc.man @@ -0,0 +1,115 @@ +.\" Copyright (c) 2019 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software furnished to do so, subject to +.\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealing in this Software without prior written authorization +.\" from the X Consortium. +.\" + +.TH xpmmisc __libmansuffix__ __xorgversion__ "libXpm functions" +.SH NAME +Xpmmisc \- xpm misc functions to free used memory and handle errors +.SH SYNOPSIS + +.HP +int XpmFreeXpmImage(image) +XpmImage*image; + +.HP +int XpmFreeXpmInfo(ainfo) +XpmInfo *info; + +.HP +int XpmFreeAttributes(attributes) + XpmAttributes *attributes; + +.HP +int XpmAttributesSize() + +.HP +int XpmFreeExtensions(extensions, nextensions) + XpmExtension *extensions; + int nextensions; + +.HP +int XpmFree(ptr) +char *ptr; + +.HP +char *XpmGetErrorString(errorcode) +int errorcode; +.HP +int XpmLibraryVersion() + +.SH ARGUMENTS +.nf +image Specifies the structure to free +info Specifies the structure to free +ptr Specifies the data to free. +errorcode Specifies the XPM error. +extensions Specifies the array to free. +nextensions Specifies the number of extensions. +attributes Specifies the structure to free +.fi +.SH DESCRIPTION + +To free possible data stored into an XpmImage structure use XpmFreeXpmImage. + +TheXpmFreeXpmImagefrees the structure members which are not NULL, but not the structure itself. +To free possible data stored into an XpmInfo structure use XpmFreeXpmInfo. + +To free data possibly stored into an array of XpmExtension use XpmFreeExtensions. + +To free any data allocated by an XPM function use the XpmFree function. +The current distribution of the XPM library uses the standard memory allocation functions and thus +XpmFree is nothing else than a define to the standard free. +However since these functions may be redefined in specific environments it is wise to use XpmFree. + +To free possible data stored into an XpmAttributes structure use XpmFreeAtatributes. +The XpmFreeAttributes frees the structure members which have been malloc’ed such as the pixels list. + +To dynamically allocate an XpmAttributes structure use the XpmAttributesSize function. +The XpmAttributesSize function provides application using dynamic libraries with a safe way to allocate and then +refer to an XpmAttributesstructure, disregarding whether the XpmAttributes structure size has changed or not since +compiled. +To get data when building an error message, one can use XpmGetErrorString. +XpmGetErrorString returns a string related to the given XPM error code. + +The XpmLibraryVersion can be used when one needs to figure out which version of the library is in use. +The value returned by XpmLibraryVersion can be compared to the value of XpmIncludeVersion which is defined +in the header file "xpm.h". These numbers are computed with the following formula: +.nf + (XpmFormat * 100 + XpmVersion) * 100 + XpmRevision +.fi +Where XpmFormat is the version number of the format, XpmVersion is the library version number (which changes +only if the API changes), and XpmRevision is the library minor version number. + +This function frees all data stored in every extension and the array itself. Note that +XpmFreeAttributes call this function and thus most of the time it should not need to be explicitly called. + +.SH "SEE ALSO" +.BR XpmLibraryVersion(__libmansuffix__) , +.BR XpmGetErrorString(__libmansuffix__) , +.BR XpmFree(__libmansuffix__) , +.BR XpmFreeExtensions(__libmansuffix__) , +.BR XpmAttributesSize(__libmansuffix__) , +.BR XpmFreeAttributes(__libmansuffix__) , +.BR XpmFreeXpmImage(__libmansuffix__) , +.BR XpmFreeXpmInfo(__libmansuffix__)
\ No newline at end of file diff --git a/man/xpmread.man b/man/xpmread.man new file mode 100644 index 0000000..4259eb4 --- /dev/null +++ b/man/xpmread.man @@ -0,0 +1,176 @@ +.\" Copyright (c) 2019 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software furnished to do so, subject to +.\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealing in this Software without prior written authorization +.\" from the X Consortium. +.\" + +.TH XpmRead __libmansuffix__ __xorgversion__ "libXpm functions" +.SH NAME +XpmRead \- read an XPM file + +.SH SYNOPSIS +.HP +int XpmReadFileToImage(display, filename, image_return, shapeimage_return, attributes) + Display *display; + char *filename; + XImage**image_return; + XImage**shapeimage_return; + XpmAttributes *attributes; +.HP +int XpmReadFileToPixmap(display, d, filename, pixmap_return, shapemask_return, attributes) + Display *display; + Drawable d; + char *filename; + Pixmap*pixmap_return; + Pixmap*shapemask_return; + XpmAttributes *attributes; +.HP +To create an XpmImage from an XPM file, use XpmReadFileToXpmImage. +int XpmReadFileToXpmImage(filename, image, info) + char *filename; + XpmImage*image; + XpmInfo *info; + +.HP +int XpmReadFileToBuffer(filename, buffer_return) + char *filename; + char **buffer_return; +.HP +int XpmReadFileToData(filename, data_return) + char *filename; + char ***data_return; + +.SH ARGUMENTS +.nf + display Specifies the connection to the X server. + filename Specifies the file name to use. + image_return Returns the image which is created. + shapeimage_return Returns the shape mask image which is created if the color None is used. + attributes Specifies the location of a structure to get and store information (or NULL). + buffer_return Returns the buffer created. + data_return Returns the data array created. + image Specifies the image structure location. + info Specifies the location of a structure to store possible information (or NULL). + +.fi + +.SH DESCRIPTION +.SS XpmReadFileToImage +The XpmReadFileToImage function reads in a file in the XPM format. If the file cannot be opened it returns XpmOpenFailed. +If the file can be opened but does not contain valid XPM data, it returns XpmFileInvalid. +If insufficient working storage is allocated, it returns XpmNoMemory. +If the passedXpmAttributes structure pointer is not NULL, XpmReadFileToImage looks for the following attributes: +XpmVisual, XpmColormap, XpmDepth, XpmColorSymbols, XpmExactColors, XpmCloseness, +XpmRGBCloseness, XpmAllocCloseColors ,XpmReturnPixels, XpmReturnAllocPixels, XpmAllocColor, +XpmFreeColors, XpmColorClosure, XpmReturnExtensions, XpmReturnColorTable, XpmBitmapFormat, +sets the XpmSize, the XpmCharsPerPixel, and possibly the XpmHotspot attributes when returning. +As a backward compatibility feature, XpmReadFileToImage also looks for the XpmReturnInfos attributes. +As specified in the table (page 12), if the data related to the attributes XpmReturnExtensions, +XpmReturnColorTable, and XpmReturnInfos cannot be returned as requested because of insufficient +memory storage, XpmReadFileToImage will change the valuemask to +mention this and will try to continue. +So the caller should check on this before accessing this data. + +Note: The valuemask of the passed XpmAttributes must be set to some valid value, at least zero, otherwise +unpredictable errors can occur. +XpmReadFileToImage allocates colors, as read from the file or possibly overridden as specified in the +XpmColorSymbols attributes. +The colors are allocated using the color settings for the visual specified by the XpmColorKey +attribute, which has the value XPM_MONO, XPM_GRAY4, XPM_GRAY,or XPM_COLOR. +If the XpmColor-Key attribute is not set it is determined by examining the type of visual. +If no default value exists for the specified visual, it first looks for other defaults nearer to the monochrome visual type +and secondly nearer to the color visual type. +If the color which is found is not valid (cannot be parsed), it looks for +another default one according to the same algorithm. +If allocating a color fails, and the closeness attribute is set, it tries to find a color already in the colormap that is closest +to the desired color, and uses that. +If the alloc_close_colors attribute is set to False, the found close color is not allocated but it is used anyway. +This is especially useful for applications which use a private colormap containing read/write cells and have +complete control over the colormap. +On the other hand, since in such a case there is no garanty that the color pixel will not change any time, +this should be avoided when using the default colormap. +If no color can be found that is within closeness of the Red, Green and Blue components of the desired color, +it reverts to trying other default values as explained above. +For finer control over the closeness requirements of a particular icon, +the red_closeness, green_closeness, and blue_closeness attributes may be used instead of the more general +closeness attribute. + +The RGB components are integers within the range 0 (black) to 65535 (white). A closeness of less than 10000, +for example, will cause only quite close colors to be matched, while a closeness of more than 50000 will +allow quite dissimilar colors to match. +Specifying a closeness of more than 65535 will allow any color to match, thus forcing the icon +to be drawn in color no matter how bad the colormap is. +The value 40000 seems to be about right for many situations +requiring reasonable but not perfect matches. With this setting the color must only be within the same general area of +the RGB cube as the desired color. +If the exactColors attribute is set it then returns XpmColorError, otherwise it creates the images and returns XpmSuccess. +If no color is found, and no close color exists or is wanted, and all visuals have been exhausted, +XpmColorFailed is returned. + +XpmReadFileToImage returns the created image to image_return if not NULL and possibly the +created shapemask to shapeimage_return if not NULL and the color None is used. +If required it stores into the XpmAttributes structure the list of the used pixels. +When the image depth is one, the image format is either as specified by the bitmap_format attribute if set or ZPixmap. +When the depth is different from one the imagae format is always ZPixmap. +When finished the caller must free the images using XDestroyImage, the allocated colors using +XFreeColors or the appication equivalent function when the standard Xlib functions are not used, +and possibly the data returned into the XpmAttributes using XpmFreeAttributes (page 25). +In addition, on systems which support such features XpmReadFileToImage deals with compressed files by forking +an uncompress orgzip process and reading from the piped result. It assumes that the specified file is +compressed if the given file name ends by ’.Z’ or ’.gz’. +In case the file name does not end so, XpmReadFileToImage looks for the given file name assuming it is not a compressed file. +And if instead of a file name NULL is passed to XpmReadFile ToImage, it reads from the standard input. + +.SS XpmReadFileToPixmap +The XpmReadFileToPixmap function creates X images using XpmReadFileToImage and thus returns the same errors. +In addition on success it then creates the related pixmaps, using XPutImage, +which are returned to pixmap_return and shapemask_return if not NULL, and finally destroys the created images using XDestroyImage. +When finished the caller must free the pixmaps using XFreePixmap, the allocated colors using XFreeColors or the +application equivalent function when the standard Xlib functions are not used, and possibly the data returned into the +XpmAttributes using XpmFreeAttributes. + +.SS XpmReadFileToBuffer +XpmReadFileToBuffer allocates and fills a buffer from a file. +XpmReadFileToBuffer returns XpmOpenFailed if it cannot open the file, returns XpmNoMemory if insufficient +working storage is allocated, andXpmSuccess otherwise. The allocated buffer returned by XpmReadFileToBuffer +should be freed with XpmFree when done. + +.SS XpmReadFileToData +XpmReadFileToData returns XpmOpenFailed if it cannot open the file, +XpmNoMemory if insufficient working storage is allocated, +XpmFileInvalid if this is not a validXPM file, and XpmSuccess otherwise. +The allocated data returned by XpmReadFileToData should be freed with XpmFree when done. + +.SS XpmReadFileToXpmImage +The XpmReadFileToXpmImage function reads in a file in the XPM format. +If the file cannot be opened it returns XpmOpenFailed. +If the file can be opened but does not contain valid XPMdata, +it returns XpmFileInvalid. +If insufficient working storage is allocated, it returnsXpmNoMemory. +On success it fills in the given XpmImage structure and returns XpmSuccess. + +.SH "SEE ALSO" +.BR XpmReadFileToImage(__libmansuffix__) , +.BR XpmReadFileToPixmap(__libmansuffix__) , +.BR XpmReadFileToBuffer(__libmansuffix__) , +.BR XpmReadFileToData(__libmansuffix__) +.BR XpmReadFileToXpmImage(__libmansuffix__)
\ No newline at end of file diff --git a/man/xpmwrite.man b/man/xpmwrite.man new file mode 100644 index 0000000..2bd2994 --- /dev/null +++ b/man/xpmwrite.man @@ -0,0 +1,141 @@ +.\" Copyright (c) 2019 X Consortium +.\" +.\" Permission is hereby granted, free of charge, to any person obtaining +.\" a copy of this software and associated documentation files (the +.\" "Software"), to deal in the Software without restriction, including +.\" without limitation the rights to use, copy, modify, merge, publish, +.\" distribute, sublicense, and/or sell copies of the Software, and to +.\" permit persons to whom the Software furnished to do so, subject to +.\" the following conditions: .\" .\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of the X Consortium shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealing in this Software without prior written authorization +.\" from the X Consortium. +.\" + +.TH XpmWrite __libmansuffix__ __xorgversion__ "libXpm functions" +.SH NAME +XpmWrite \- write an XPM file + +.SH SYNOPSIS +.HP +int XpmWriteFileFromPixmap(display, filename, pixmap, shapemask, attributes) + Display *display; + char *filename; + Pixmap pixmap; + Pixmap shapemask; + XpmAttributes *attributes; + +.HP +int XpmWriteFileFromImage(display, filename, image, shapeimage, attributes) + Display *display; + char *filename; + XImage*image; + XImage*shapeimage; + XpmAttributes *attributes; + +.HP +int XpmWriteFileFromData(filename, data) + char *filename; + char **data; + +.HP +int XpmWriteFileFromXpmImage(filename, image, shapeimage, info) + char *filename; + XpmImage*image; + XImage*shapeimage; + XpmInfo *info; + +.HP +int XpmWriteFileFromBuffer(filename, data) + char *filename; + char *buffer; + +.SH ARGUMENTS +.nf +display Specifies the connection to the X server. +filename Specifies the file name to use. +pixmap Specifies the pixmap. +shapemask Specifies the shape mask pixmap. +attributes Specifies the location of a structure containing information (or NULL). +data Specifies the data array to read. +image Specifies the image. +info Specifies the location of a structure to get information from (or NULL). +buffer Specifies the buffer to read. +.fi + +.SH DESCRIPTION +.SS XpmWriteFileFromImage + +The XpmWriteFileFromImage function writes an image and its possible shapeimage out to a file in the XPM format. +If the file cannot be opened, it returnsXpmOpenFailed. +If insufficient working storage is allocated, it returns XpmNoMemory. +If no error occurs then it returns XpmSuccess. +If the passed XpmAttributes structure pointer is not NULL, +XpmWriteFileFromImage looks for the following attributes: +XpmColormap, XpmHotspot, XpmCharsPerPixel, XpmRgbFilename, and XpmExtensions. +As a backward compatibility feature, XpmWriteFileFromImage also looks for the XpmInfos attributes. +If the filename contains an extension such as “.xpm”, in order to get a valid C variable name, the dot character is +replaced by an underscore ’_’ when writing out. +As a backward compatibility feature, if the XpmInfos attributes are defined it writes out possible stored +information such as comments, color defaults and symbol. +Finally, if the XpmRgbFilenameattribute is defined, XpmWriteFileFromImage searches for color names in +this file and if found writes them out instead of the rgb values. + +In addition on systems which support such features if the given file name ends by ’.Z’ or ’.gz’ +it is assumed to be a compressed file. Then,XpmWriteFileFromImage writes to a pipedcompress or gzip process. +And if instead of a file name NULL is passed to XpmWriteFileFromImage, it writes to the standard output. + +.SS XpmWriteFileFromPixmap +To write out a Pixmap to an XPM file, use XpmWriteFileFromPixmap. + +If the passed XpmAttributes structure pointer is not NULL, +XpmWriteFileFromPixmap looks for the following atributes: XpmSize. +If they are not defined it performs an XGetGeometry operation. +Then it uses XGetImage to get from the given pixmaps the related X images which are passed to XpmWriteFileFromImage. +Finally XpmWriteFileFromPixmap destroys the created images using XDestroyImage. +The XpmWriteFileFromPixmapfunction returns the same errors as XpmWriteFileFromImage. + +.SS XpmWriteFileFromData +XpmWriteFileFromData writes an XPM data array to an XPM file. + +XpmWriteFileToData returns XpmOpenFailed if it cannot open the file, +XpmFileInvalid if this is not a valid XPM data, and XpmSuccess otherwise. + +.SS XpmWriteFileFromXpmImage +To write out an XpmImage to an XPM file, use XpmWriteFileFromXpmImage. +The XpmWriteFileFromXpmImage function writes an image out to a file in theXPM format. If the file cannot be +opened, it returns XpmOpenFailed. If insufficient working storage is allocated, it returns XpmNoMemory. +If no error occurs then it returns XpmSuccess. +If the passed XpmInfo structure pointer is not NULL, XpmWriteFileFromXpmImage looks for the following attributes: +XpmComments, XpmExtensions, and XpmHotspot, and writes the related information out as well. +In addition on systems which support such features if the given file name ends by ’.Z’ or ’.gz’ it is assumed to be a +compressed file. Then, XpmWriteFileFromXpmImage writes to a piped compress or gzip process. And if instead +of a file name NULL is passed to XpmWriteFileFromXpmImage, it writes to the standard output. + +.SS XpmWriteFileFromBuffer +XpmWriteFileFromBuffer writes a XPM-buffer to a file. +XpmWriteFileFromBuffer returns XpmOpenFailed if it cannot open the file, and XpmSuccess otherwise. + +As a convenience, the XpmReadFileToBuffer and XpmWriteFileFromBuffer are provided to copy a +file to a buffer and to write a file from a buffer. +Thus for instance one may decide to use XpmReadFileToBuffer, XpmCreatePixmapFromBuffer, and XpmFree +instead ofXpmReadFileToPixmap. On some systems this may lead to a performance improvement, +since the parsing will be performed in memory, but it uses more memory. + +.SH "SEE ALSO" +.BR XpmWriteFileFromData(__libmansuffix__) , +.BR XpmWriteFileFromPixmap(__libmansuffix__) , +.BR XpmWriteFileFromImage(__libmansuffix__) , +.BR XpmWriteFileFromXpmImage(__libmansuffix__) , +.BR XpmWriteFileFromBuffer(__libmansuffix__) |