diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/XpmCreateBuffer.man | 87 | ||||
| -rw-r--r-- | man/XpmCreateData.man | 69 | ||||
| -rw-r--r-- | man/XpmCreateImage.man | 72 | ||||
| -rw-r--r-- | man/XpmCreatePixmap.man | 80 | ||||
| -rw-r--r-- | man/XpmCreateXpmImage.man | 112 | ||||
| -rw-r--r-- | man/XpmMisc.man | 122 | ||||
| -rw-r--r-- | man/XpmRead.man | 256 | ||||
| -rw-r--r-- | man/XpmWrite.man | 161 |
8 files changed, 690 insertions, 269 deletions
diff --git a/man/XpmCreateBuffer.man b/man/XpmCreateBuffer.man index 03d8b87..2e72a96 100644 --- a/man/XpmCreateBuffer.man +++ b/man/XpmCreateBuffer.man @@ -27,12 +27,17 @@ XpmCreateBuffer \- create an XPM Buffer .SH SYNOPSIS +.nf .HP -int XpmCreateBufferFromImage(Display *display, char **buffer_return, XImage *image, XImage *shapeimage, XpmAttributes *attributes); +.BI "int XpmCreateBufferFromImage(Display *" display " , char **" buffer_return , +.BI "XImage *" image ", XImage *" shapeimage ", XpmAttributes *" attributes ); .HP -int XpmCreateBufferFromPixmap(Display *display, char **buffer_return, Pixmap pixmap, Pixmap shapemask, XpmAttributes *attributes); +.BI "int XpmCreateBufferFromPixmap(Display *" display ", char **" buffer_return , +.BI "Pixmap " pixmap ", Pixmap " shapemask ", XpmAttributes *" attributes ); .HP -int XpmCreateBufferFromXpmImage(char **buffer_return, XpmImage *image, XpmInfo *info); +.BI "int XpmCreateBufferFromXpmImage(char **" buffer_return ", XpmImage *" image , +.BI "XpmInfo *" info ); +.fi .SH ARGUMENTS @@ -52,31 +57,71 @@ Specifies the location of a structure to get possible information (or NULL). .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 functions -are provided to copy a file to a buffer +.PP +.BR XpmCreateBufferFromPixmap () +creates an XPM buffer from a Pixmap. +The +.BR XpmCreateBufferFromPixmap () +function works as +.BR XpmWriteFileFromPixmap (__libmansuffix__), +it just calls +.BR XpmCreateBufferFromImage () +instead of +.BR XpmWriteFileFromImage (__libmansuffix__). +Once again, the caller should free the buffer using +.BR XpmFree (__libmansuffix__) +when finished. +.PP +As a convenience, the +.BR XpmReadFileToBuffer (__libmansuffix__) +and +.BR XpmWriteFileFromBuffer (__libmansuffix__) +functions 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 -XpmCreateBufferFromPixmap, XpmWriteFileFromBuffer, and XpmFree instead of -XpmWriteFileFromPixmap. On some systems this may lead to a -performance improvement, since the parsing will be performed in memory, but it uses more memory. +.BR XpmCreateBufferFromPixmap (), +.BR XpmWriteFileFromBuffer (__libmansuffix__), +and +.BR XpmFree (__libmansuffix__) +instead of +.BR XpmWriteFileFromPixmap (__libmansuffix__). +On some systems this may lead to a performance improvement, since the +processing will be performed in memory, but it uses more memory. .SS XpmCreateBufferFromImage -The XpmCreateBufferFromImage function 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. +.PP +The +.BR XpmCreateBufferFromImage () +function works as +.BR XpmWriteFileFromImage (__libmansuffix__), +it just writes to a malloc’ed buffer instead of to a file. +The caller should free the buffer using +.BR XpmFree (__libmansuffix__) +when finished. .SS XpmCreateBufferFromXpmImage. -To create an XPM buffer from an XpmImage, use XpmCreateBufferFromXpmImage. -The XpmCreateBufferFromXpmImage function writes out the given image to a single block malloc’ed buffer 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, 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. +.PP +To create an XPM buffer from an XpmImage, use +.BR XpmCreateBufferFromXpmImage (). +The +.BR XpmCreateBufferFromXpmImage () +function writes out the given image to a single block malloc’ed buffer +in XPM format. +If insufficient working storage is allocated, it returns +.BR XpmNoMemory, +and returns +.B XpmSuccess +on success. +If the passed XpmInfo structure pointer is not NULL, +.BR 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 +.BR XpmFree (__libmansuffix__) +when finished. .SH "SEE ALSO" +.ad l +.nh .BR XpmFree (__libmansuffix__), .BR XpmWriteFileFromBuffer (__libmansuffix__), .BR XpmWriteFileFromImage (__libmansuffix__), diff --git a/man/XpmCreateData.man b/man/XpmCreateData.man index d4ec6f9..97d7b14 100644 --- a/man/XpmCreateData.man +++ b/man/XpmCreateData.man @@ -27,12 +27,17 @@ XpmCreateData \- create an Data structure .SH SYNOPSIS +.nf .HP -int XpmCreateDataFromImage(Display *display, char ***data_return, XImage *image, XImage *shapeimage, XpmAttributes *attributes); +.BI "int XpmCreateDataFromImage(Display *" display ", char ***" data_return , +.BI "XImage *" image ", XImage *" shapeimage ", XpmAttributes *" attributes ); .HP -int XpmCreateDataFromPixmap(Display *display, char ***data_return, Pixmap pixmap, Pixmap shapemask, XpmAttributes *attributes); +.BI "int XpmCreateDataFromPixmap(Display *" display ", char ***" data_return , +.BI "Pixmap " pixmap ", Pixmap " shapemask ", XpmAttributes *" attributes ); .HP -int XpmCreateDataFromXpmImage(char ***data_return, XpmImage *image, XpmInfo *info); +.BI "int XpmCreateDataFromXpmImage(char ***" data_return ", XpmImage *" image , +.BI "XpmInfo *" info ); +.fi .SH ARGUMENTS @@ -53,26 +58,58 @@ Specifies the image .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 as XpmWriteFileFromImage() does and returns the same way. +.PP +In some cases, one may want to create an XPM data from an XImage, to do so use +.BR XpmCreateDataFromImage (). +The +.BR XpmCreateDataFromImage () +function exactly works as +.BR XpmWriteFileFromImage (__libmansuffix__) +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. +It is the caller’s responsibility to free the data, using +.BR XpmFree (__libmansuffix__) +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. +.PP +.BR XpmCreateDataFromPixmap () +creates an XPM data from a Pixmap. +The +.BR XpmCreateDataFromPixmap () +function uses +.BR XGetImage (__libmansuffix__) +to get from the given pixmaps +the related X images which are passed to +.BR XpmCreateDataFromImage (). +Then it destroys the created images using +.BR XDestroyImage (__libmansuffix__). +.BR XpmCreateDataFromPixmap () +returns the same errors as +.BR XpmCreateDataFromImage (). .SS XpmCreateDataFromXpmImage -XpmCreateDataFromXpmImage creates an XPM data from an XpmImage. -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: +.PP +.BR XpmCreateDataFromXpmImage () +creates an XPM data from an XpmImage. +The +.BR 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 +.BR XpmNoMemory , +and returns +.B XpmSuccess +on success. +If the passed XpmInfo structure pointer is not NULL, +.BR 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. +It is the caller’s responsibility to free the data, using +.BR XpmFree (__libmansuffix__) +when finished. .SH "SEE ALSO" +.ad l +.nh .BR XpmFree (__libmansuffix__), .BR XpmWriteFileFromImage (__libmansuffix__) diff --git a/man/XpmCreateImage.man b/man/XpmCreateImage.man index 73521f5..c876447 100644 --- a/man/XpmCreateImage.man +++ b/man/XpmCreateImage.man @@ -26,12 +26,20 @@ .SH NAME XpmCreateImage \- create an XImage from an XPM .SH SYNOPSIS +.nf .HP -int XpmCreateImageFromData(Display *display, char **data, XImage **image_return, XImage **shapeimage_return, XpmAttributes *attributes); +.BI "int XpmCreateImageFromData(Display *" display ", char **" data , +.BI "XImage **" image_return ", XImage **" shapeimage_return , +.BI "XpmAttributes *" attributes ); .HP -int XpmCreateImageFromBuffer(Display *display, char *buffer, XImage **image_return, XImage **shapeimage_return, XpmAttributes *attributes); +.BI "int XpmCreateImageFromBuffer(Display *" display ", char *" buffer , +.BI "XImage **" image_return ", XImage **" shapeimage_return , +.BI "XpmAttributes *" attributes ); .HP -int XpmCreateImageFromXpmImage(Display *display, XpmImage *image, XImage *image_return, XImage *shapeimage_return, XpmAttributes *attributes); +.BI "int XpmCreateImageFromXpmImage(Display *" display ", XpmImage *" image , +.BI "XImage *" image_return ", XImage *" shapeimage_return , +.BI "XpmAttributes *" attributes ); +.fi .SH ARGUMENTS @@ -51,30 +59,56 @@ Specifies the shape mask image which is created if any. .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. +.PP +To create an XImage from an XPM data, use +.BR XpmCreateImageFromData (). +.PP +The +.BR XpmCreateImageFromData () +function allows you to include in your C program an XPM file which was +written out by functions such as +.BR XpmWriteFileFromImage (__libmansuffix__) +or +.BR XpmWriteFileFromPixmap (__libmansuffix__) +without reading in the file. +.BR XpmCreateImageFromData () +exactly works as +.BR XpmReadFileToImage (__libmansuffix__) +does and returns the same way. It just reads data instead of a file. -Here again, it is the caller’s responsibility to free the returned images, the colors -and possibly the data returned into the XpmAttributes structure. +Here again, it is the caller’s responsibility 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 function works the same way as XpmReadFileToImage(), +.PP +To create an XImage from an XPM buffer, use +.BR XpmCreateImageFromBuffer (). +The +.BR XpmCreateImageFromBuffer() +function works the same way as +.BR XpmReadFileToImage (__libmansuffix__), it just parses the buffer instead of the file. -Be aware that the feature provided on some systems by XpmReadFileToImage +Be aware that the feature provided on some systems by +.BR XpmReadFileToImage (__libmansuffix__) to deal with compressed files is not available here. .SS XpmCreateImageFromXpmImage -To create an XImage from an XpmImage, use XpmCreateImageFromXpmImage. -From the given XpmImage and XpmAttributes if not NULL, 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(). +.PP +To create an XImage from an XpmImage, use +.BR XpmCreateImageFromXpmImage (). +From the given XpmImage and XpmAttributes if not NULL, +.BR XpmCreateImageFromXpmImage () +allocates colors and creates X images following the same mechanism as +.BR XpmReadFileToImage (__libmansuffix__). +When finished the caller must free the images using +.BR XDestroyImage (__libmansuffix__), +the colors using +.BR XFreeColors (__libmansuffix__), +and possibly the data returned into the XpmAttributes using +.BR XpmFreeAttributes (__libmansuffix__). .SH "SEE ALSO" +.ad l +.nh .BR XpmFreeAttributes (__libmansuffix__), .BR XpmReadFileToImage (__libmansuffix__) diff --git a/man/XpmCreatePixmap.man b/man/XpmCreatePixmap.man index 79f54ae..19fe4cb 100644 --- a/man/XpmCreatePixmap.man +++ b/man/XpmCreatePixmap.man @@ -26,12 +26,20 @@ .SH NAME XpmCreatePixmap \- create a pixmap .SH SYNOPSIS +.nf .HP -int XpmCreatePixmapFromData(Display *display, Drawable d, char **data, Pixmap *pixmap_return, Pixmap *shapemask_return, XpmAttributes *attributes); +.BI "int XpmCreatePixmapFromData(Display *" display ", Drawable " d , +.BI "char **" data ", Pixmap *" pixmap_return ", Pixmap *" shapemask_return , +.BI "XpmAttributes *" attributes ); .HP -int XpmCreatePixmapFromBuffer(Display *display, Drawable d, char *buffer, Pixmap *pixmap_return, Pixmap *shapemask_return, XpmAttributes *attributes); +.BI "int XpmCreatePixmapFromBuffer(Display *" display ", Drawable " d , +.BI "char *" buffer ", Pixmap *" pixmap_return ", Pixmap *" shapemask_return , +.BI "XpmAttributes *" attributes ); .HP -int XpmCreatePixmapFromXpmImage(Display *display, Drawable d, XpmImage *image, Pixmap *pixmap_return, Pixmap *shapemask_return, XpmAttributes *attributes); +.BI "int XpmCreatePixmapFromXpmImage(Display *" display ", Drawable " d , +.BI "XpmImage *" image ", Pixmap *" pixmap_return ", Pixmap *" shapemask_return , +.BI "XpmAttributes *" attributes ); +.fi .SH ARGUMENTS @@ -52,27 +60,63 @@ Specifies the XpmImage. .SH DESCRIPTION .SS XpmCreatePixmapFromData -To create a Pixmap from an XPM data, use XpmCreatePixmapFromData. -The XpmCreatePixmapFromData function creates X images using XpmCreateImageFromData() 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. -Do not forget to free the returned pixmaps, the colors, and possibly the data returned into the XpmAttributes structure when done. +.PP +To create a Pixmap from an XPM data, use +.BR XpmCreatePixmapFromData (). +The +.BR XpmCreatePixmapFromData () +function creates X images using +.BR XpmCreateImageFromData (__libmansuffix__) +and thus returns the same errors. +In addition on success it then creates the related pixmaps, using +.BR XPutImage (__libmansuffix__), +which are returned to +.I pixmap_return +and +.I shapemask_return +if not NULL, and finally destroys the created images using +.BR XDestroyImage (__libmansuffix__). +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 as XpmReadFileToPixmap (), -it just calls XpmCreateImageFromBuffer instead of XpmReadFileToImage. +.PP +To create a Pixmap from an XPM buffer, use +.BR XpmCreatePixmapFromBuffer (). +The +.BR XpmCreatePixmapFromBuffer () +function works the same way as +.BR XpmReadFileToPixmap (__libmansuffix__), +it just calls +.BR XpmCreateImageFromBuffer (__libmansuffix__) +instead of +.BR XpmReadFileToImage (__libmansuffix__). .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 application -equivalent function when the standard Xlib functions are not used, and possibly the data returned into the -XpmAttributes using XpmFreeAttributes. +.PP +.BR XpmCreatePixmapFromXpmImage () +creates X images calling +.BR XpmCreateImageFromXpmImage (__libmansuffix__) +with the given XpmImage and XpmAttributes, then it creates the related pixmaps +which are returned to +.I pixmap_return +and +.I shapemask_return +using +.BR XPutImage (__libmansuffix__). +Finally it destroys the X images with +.BR XDestroyImage (__libmansuffix__). +When finished the caller must free the pixmaps using +.BR XFreePixmap (__libmansuffix__), +the colors using +.BR XFreeColors (__libmansuffix__) +or the application equivalent function when the standard Xlib functions are not +used, and possibly the data returned into the XpmAttributes using +.BR XpmFreeAttributes (__libmansuffix__). .SH "SEE ALSO" +.ad l +.nh .BR XpmCreateImageFromData (__libmansuffix__), .BR XpmCreateImageFromXpmImage (__libmansuffix__), .BR XpmFreeAttributes (__libmansuffix__), diff --git a/man/XpmCreateXpmImage.man b/man/XpmCreateXpmImage.man index 64353ba..93147f5 100644 --- a/man/XpmCreateXpmImage.man +++ b/man/XpmCreateXpmImage.man @@ -26,15 +26,22 @@ .SH NAME XpmCreateXpmImage \- create an Xpm image .SH SYNOPSIS - +.nf .HP -int XpmCreateXpmImageFromData(char **data, XpmImage *image, XpmInfo *info); +.BI "int XpmCreateXpmImageFromData(char **" data ", XpmImage *" image , +.BI "XpmInfo *" info ); .HP -int XpmCreateXpmImageFromBuffer(char *buffer, XpmImage *image, XpmInfo *info); +.BI "int XpmCreateXpmImageFromBuffer(char *" buffer ", XpmImage *" image , +.BI "XpmInfo *" info ); .HP -int XpmCreateXpmImageFromImage(Display *display, XImage *image, XImage *shapeimage, XpmImage *xpmimage, XpmAttributes *attributes); +.BI "int XpmCreateXpmImageFromImage(Display *" display , +.BI "XImage *" image ", XImage *" shapeimage , +.BI "XpmImage *" xpmimage ", XpmAttributes *" attributes ); .HP -int XpmCreateXpmImageFromPixmap(Display *display, Pixmap *pixmap, Pixmap *shapemask, XpmImage *xpmimage, XpmAttributes *attributes); +.BI "int XpmCreateXpmImageFromPixmap(Display *" display , +.BI "Pixmap *" pixmap ", Pixmap *" shapemask , +.BI "XpmImage *" xpmimage ", XpmAttributes *" attributes ); +.fi .SH ARGUMENTS @@ -47,60 +54,93 @@ Specifies the location of an XpmInfo structure to get and store information (or .IP \fIdisplay\fP li Specifies the connection to the X server. .IP \fIimage\fP li -Specifies the image which is created. +Specifies the X image used as the source. .IP \fIshapeimage\fP li -Specifies the shape mask image which is created if any. +Specifies the shape mask image, if any. .IP \fIxpmimage\fP li -Specifies the location of an XpmImage structure. +Specifies the XPM image which is created. .IP \fIattributes\fP li Specifies the location of a structure containing information (or NULL). .SH DESCRIPTION .SS XpmCreateXpmImageFromBuffer -To create an XpmImage from an XPM buffer, use XpmCreateXpmImageFromBuffer. -The XpmCreateXpmImageFromBuffer function 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. +.PP +To create an XpmImage from an XPM buffer, use +.BR XpmCreateXpmImageFromBuffer (). +The +.BR XpmCreateXpmImageFromBuffer () +function reads the given buffer to fill in the given XpmImage structure. +If the buffer does not contain valid XPM data, it returns +.BR XpmFileInvalid . +If insufficient working storage is allocated, it returns +.BR XpmNoMemory . +On success it returns +.BR XpmSuccess . +If the passed XpmInfo structure pointer is not NULL, +.BR 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. +.BR 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. +.PP +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 returns XpmFileInvalid. If insufficient working storage is allocated, it returns -XpmNoMemory, on success it returns XpmSuccess. -If the passed XpmInfo structure pointer is not NULL, XpmCreateXpmImageFromData looks for the following attributes: +.PP +To create an XpmImage from an XPM data, use +.BR XpmCreateXpmImageFromData (). +.BR XpmCreateXpmImageFromData () +fills in the given XpmImage structure from the given data. If the data does not +contain valid XPM data, it returns +.BR XpmFileInvalid . +If insufficient working storage is allocated, it returns +.BR XpmNoMemory . +On success it returns +.BR XpmSuccess. +If the passed XpmInfo structure pointer is not NULL, +.BR 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. +insufficient memory storage, +.BR 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. +.PP +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. +.PP +To create an XpmImage from an XImage, use +.BR XpmCreateXpmImageFromImage (). +From the given X images and XpmAttributes if not NULL, +.BR XpmCreateXpmImageFromImage () +creates an XpmImage following the same mechanism as +.BR XpmWriteFileFromImage (__libmansuffix__). .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. +.PP +To create an XpmImage from a Pixmap, use +.BR XpmCreateXpmImageFromPixmap (). +From the given pixmaps and XpmAttributes if not NULL, +.BR XpmCreateXpmImageFromPixmap () +gets the related XImages by calling XGetImage, then it gives them to +.BR XpmCreateXpmImageFromImage () +to create an XpmImage which is returned to +.IR xpmimage . +Finally it destroys the created X images using +.BR XDestroyImage (__libmansuffix__). .SH "SEE ALSO" +.ad l +.nh .BR XpmFreeXpmImage (__libmansuffix__), .BR XpmReadFileToBuffer (__libmansuffix__), .BR XpmReadFileToData (__libmansuffix__), diff --git a/man/XpmMisc.man b/man/XpmMisc.man index 7e3d696..769a9b8 100644 --- a/man/XpmMisc.man +++ b/man/XpmMisc.man @@ -26,24 +26,24 @@ .SH NAME XpmMisc \- xpm misc functions to free used memory and handle errors .SH SYNOPSIS - +.nf .HP -int XpmFreeXpmImage(XpmImage *image); +.BI "int XpmFreeXpmImage(XpmImage *" image ); .HP -int XpmFreeXpmInfo(XpmInfo *info); +.BI "int XpmFreeXpmInfo(XpmInfo *" info ); .HP -int XpmFreeAttributes(XpmAttributes *attributes); +.BI "int XpmFreeAttributes(XpmAttributes *" attributes ); .HP -int XpmAttributesSize(); +.B "int XpmAttributesSize(void);" .HP -int XpmFreeExtensions(XpmExtension *extensions, int nextensions); +.BI "int XpmFreeExtensions(XpmExtension *" extensions ", int " nextensions ); .HP -int XpmFree(char *ptr); +.BI "int XpmFree(char *" ptr ); .HP -char *XpmGetErrorString(int errorcode); +.BI "char *XpmGetErrorString(int " errorcode ); .HP -int XpmLibraryVersion(); - +.B "int XpmLibraryVersion(void);" +.fi .SH ARGUMENTS .IP \fIimage\fP li @@ -62,41 +62,87 @@ Specifies the number of extensions Specifies the structure to free .SH DESCRIPTION +.PP +To free possible data stored into an XpmImage structure use +.BR XpmFreeXpmImage (). +The +.BR XpmFreeXpmImage () +function frees the structure members which are not NULL, +but not the structure itself. +.PP +To free possible data stored into an XpmInfo structure use +.BR XpmFreeXpmInfo(). +.PP +To free data possibly stored into an array of XpmExtension use +.BR XpmFreeExtensions (). +.PP +To free any data allocated by an XPM function use the +.BR XpmFree () +function. +The current distribution of the XPM library uses the standard memory allocation +functions and thus +.BR XpmFree () +is nothing else than a define to the standard +.BR free (__libmansuffix__). +However since these functions may be redefined in specific environments +it is wise to use +.BR XpmFree () +.PP +To free possible data stored into an XpmAttributes structure use +.BR XpmFreeAttributes (). +The +.BR XpmFreeAttributes () +function frees the structure members which have been malloc’ed +such as the pixels list. +.PP +To dynamically allocate an XpmAttributes structure use the +.BR XpmAttributesSize () +function. +The +.BR XpmAttributesSize () +function provides applications using dynamic libraries with a safe way to +allocate and then refer to an XpmAttributes structure, disregarding whether +the XpmAttributes structure size has changed or not since compiled. +.PP +To get data when building an error message, one can use +.BR XpmGetErrorString (). +.BR XpmGetErrorString () +returns a string related to the given XPM error code. +.PP +The +.BR XpmLibraryVersion () +function can be used when one needs to figure out which version of the library +is in use. +The value returned by +.BR XpmLibraryVersion () +can be compared to the value of +.B XpmIncludeVersion +which is defined in the header file "xpm.h". +These numbers are computed with the following formula: -To free possible data stored into an XpmImage structure use XpmFreeXpmImage. -The XpmFreeXpmImage function frees 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 XpmFreeAttributes. -The XpmFreeAttributes function 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 XpmAttributes structure, 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 function 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. -The XpmFreeExtensions 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. +where +.B XpmFormat +is the version number of the format, +.B XpmVersion +is the library version number (which changes only if the API changes), and +.B XpmRevision +is the library minor version number. +.PP +The +.BR XpmFreeExtensions () +function frees all data stored in every extension and the array itself. +Note that +.BR XpmFreeAttributes () +calls this function and thus most of the time it should not need to be +explicitly called. .SH "SEE ALSO" +.ad l +.nh .BR XpmCreateBuffer (__libmansuffix__), .BR XpmCreateData (__libmansuffix__), .BR XpmCreateImage (__libmansuffix__), diff --git a/man/XpmRead.man b/man/XpmRead.man index b98f3d3..5843bd7 100644 --- a/man/XpmRead.man +++ b/man/XpmRead.man @@ -27,16 +27,23 @@ XpmRead \- read an XPM file .SH SYNOPSIS +.nf .HP -int XpmReadFileToImage(Display *display, char *filename, XImage **image_return, XImage **shapeimage_return, XpmAttributes *attributes); +.BI "int XpmReadFileToImage(Display *" display ", char *" filename , +.BI "XImage **" image_return ", XImage **" shapeimage_return , +.BI "XpmAttributes *" attributes ); .HP -int XpmReadFileToPixmap(Display *display, Drawable d, char *filename, Pixmap *pixmap_return, Pixmap *shapemask_return, XpmAttributes *attributes); +.BI "int XpmReadFileToPixmap(Display *" display ", Drawable " d ", char *" filename , +.BI "Pixmap *" pixmap_return ", Pixmap *" shapemask_return , +.BI "XpmAttributes *" attributes ); .HP -int XpmReadFileToXpmImage(char *filename, XpmImage *image, XpmInfo *info); +.BI "int XpmReadFileToXpmImage(char *" filename ", XpmImage *" image , +.BI "XpmInfo *" info ); .HP -int XpmReadFileToBuffer(char *filename, char **buffer_return); +.BI "int XpmReadFileToBuffer(char *" filename ", char **" buffer_return ); .HP -int XpmReadFileToData(char *filename, char ***data_return); +.BI "int XpmReadFileToData(char *" filename ", char ***" data_return ); +.fi .SH ARGUMENTS .IP \fIdisplay\fP li @@ -60,108 +67,205 @@ Specifies the location of a structure to store possible information (or NULL). .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 passed XpmAttributes structure pointer is not NULL, XpmReadFileToImage looks for the following attributes: +.PP +The +.BR XpmReadFileToImage () +function reads in a file in the XPM format. +If the file cannot be opened it returns +.BR XpmOpenFailed . +If the file can be opened but does not contain valid XPM data, it returns +.BR XpmFileInvalid . +If insufficient working storage is allocated, it returns +.BR XpmNoMemory . +If the passed XpmAttributes structure pointer is not NULL, +.BR 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. +As a backward compatibility feature, +.BR 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, +.BR 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 +.PP +Note: The valuemask of the passed XpmAttributes must be set to some valid value, +at least zero, otherwise unpredictable errors can occur. +.PP +.BR 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 XpmColorKey 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 +If the XpmColorKey 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 +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 guarantee that the color pixel will not change any time, +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 guarantee 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, +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 +the red_closeness, green_closeness, and blue_closeness attributes may be +used instead of the more general closeness attribute. +.PP +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. +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 +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. +If the exactColors attribute is set it then returns +.BR XpmColorError , +otherwise it creates the images and returns +.BR XpmSuccess . +If no color is found, and no close color exists or is wanted, +and all visuals have been exhausted, +.B XpmColorFailed +is returned. +.PP +.BR XpmReadFileToImage () +returns the created image to +.I image_return +if not NULL and possibly the created shapemask to +.I 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 image format is always ZPixmap. -When finished the caller must free the images using XDestroyImage, 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 (page 25). -In addition, on systems which support such features XpmReadFileToImage deals with compressed files by forking -an uncompress or gzip process and reading from the piped result. It assumes that the specified file is +When finished the caller must free the images using +.BR XDestroyImage (__libmansuffix__), +the allocated colors using +.BR XFreeColors (__libmansuffix__) +or the application equivalent function +when the standard Xlib functions are not used, +and possibly the data returned into the XpmAttributes using +.BR XpmFreeAttributes (__libmansuffix__). +In addition, on systems which support such features +.BR XpmReadFileToImage () +deals with compressed files by forking an uncompress or gzip 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 XpmReadFileToImage, it reads from the standard input. +In case the file name does not end so, +.BR 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 +.BR XpmReadFileToImage (), +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. +The +.BR XpmReadFileToPixmap () +function creates X images using +.BR XpmReadFileToImage () +and thus returns the same errors. +In addition on success it then creates the related pixmaps, using +.BR XPutImage (__libmansuffix__), +which are returned to +.I pixmap_return +and +.I shapemask_return +if not NULL, and finally destroys the created images using +.BR XDestroyImage (__libmansuffix__). +When finished the caller must free the pixmaps using +.BR XFreePixmap (__libmansuffix__), +the allocated colors using +.BR XFreeColors (__libmansuffix__) +or the application equivalent function when the standard Xlib functions +are not used, and possibly the data returned into the XpmAttributes using +.BR XpmFreeAttributes (__libmansuffix__). .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, and XpmSuccess otherwise. The allocated buffer returned by XpmReadFileToBuffer -should be freed with XpmFree when done. - -As a convenience, the XpmReadFileToBuffer and XpmWriteFileFromBuffer functions +.PP +.BR XpmReadFileToBuffer () +allocates and fills a buffer from a file. +.BR XpmReadFileToBuffer () +returns +.B XpmOpenFailed +if it cannot open the file, returns +.B XpmNoMemory +if insufficient working storage is allocated, and +.B XpmSuccess +otherwise. The allocated buffer returned by +.BR XpmReadFileToBuffer () +should be freed with +.BR XpmFree (__libmansuffix__) +when done. +.PP +As a convenience, the +.BR XpmReadFileToBuffer () +and +.BR XpmWriteFileFromBuffer (__libmansuffix__) 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. +Thus for instance one may decide to use +.BR XpmReadFileToBuffer (), +.BR XpmCreatePixmapFromBuffer (__libmansuffix__), +and +.BR XpmFree (__libmansuffix__) +instead of +.BR 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 XpmReadFileToData -XpmReadFileToData returns XpmOpenFailed if it cannot open the file, -XpmNoMemory if insufficient working storage is allocated, -XpmFileInvalid if this is not a valid XPM file, and XpmSuccess otherwise. -The allocated data returned by XpmReadFileToData should be freed with XpmFree when done. +.PP +.BR XpmReadFileToData () +returns +.B XpmOpenFailed +if it cannot open the file, +.B XpmNoMemory +if insufficient working storage is allocated, +.B XpmFileInvalid +if this is not a valid XPM file, and +.B XpmSuccess +otherwise. +The allocated data returned by +.BR XpmReadFileToData () +should be freed with +.BR XpmFree (__libmansuffix__) +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 XPM data, -it returns XpmFileInvalid. -If insufficient working storage is allocated, it returns XpmNoMemory. -On success it fills in the given XpmImage structure and returns XpmSuccess. +.PP +The +.BR XpmReadFileToXpmImage () +function reads in a file in the XPM format. +If the file cannot be opened it returns +.BR XpmOpenFailed . +If the file can be opened but does not contain valid XPM data, it returns +.BR XpmFileInvalid . +If insufficient working storage is allocated, it returns +.BR XpmNoMemory . +On success it fills in the given XpmImage structure and returns +.BR XpmSuccess . .SH "SEE ALSO" +.ad l +.nh .BR XpmCreateBuffer (__libmansuffix__), .BR XpmCreateData (__libmansuffix__), .BR XpmCreateImage (__libmansuffix__), diff --git a/man/XpmWrite.man b/man/XpmWrite.man index 8e04fd0..9d2ff95 100644 --- a/man/XpmWrite.man +++ b/man/XpmWrite.man @@ -27,19 +27,23 @@ XpmWrite \- write an XPM file .SH SYNOPSIS +.nf .HP -int XpmWriteFileFromPixmap(Display *display, char *filename, Pixmap pixmap, Pixmap shapemask, XpmAttributes *attributes); +.BI "int XpmWriteFileFromPixmap(Display *" display ", char *" filename , +.BI "Pixmap " pixmap ", Pixmap " shapemask ", XpmAttributes *" attributes ); .HP -int XpmWriteFileFromImage(Display *display, char *filename, XImage *image, XImage *shapeimage, XpmAttributes *attributes); +.BI "int XpmWriteFileFromImage(Display *" display " , char *" filename , +.BI "XImage *"image ", XImage *" shapeimage ", XpmAttributes *" attributes ); .HP -int XpmWriteFileFromData(char *filename, char **data); +.BI "int XpmWriteFileFromData(char *" filename ", char **" data ); .HP -int XpmWriteFileFromXpmImage(char *filename, XpmImage *image, XImage *shapeimage, XpmInfo *info); +.BI "int XpmWriteFileFromXpmImage(char *" filename ", XpmImage *" image , +.BI "XImage *" shapeimage ", XpmInfo *" info ); .HP -int XpmWriteFileFromBuffer(char *filename, char *buffer); +.BI "int XpmWriteFileFromBuffer(char *" filename ", char *" buffer ); +.fi .SH ARGUMENTS - .IP \fIdisplay\fP li Specifies the connection to the X server. .IP \fIfilename\fP li @@ -61,65 +65,132 @@ Specifies the buffer to read. .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 returns XpmOpenFailed. -If insufficient working storage is allocated, it returns XpmNoMemory. -If no error occurs then it returns XpmSuccess. +.PP +The +.BR XpmWriteFileFromImage () +function writes an +.I image and its possible +.I shapeimage +out to a file in the XPM format. +If the file cannot be opened, it returns +.BR XpmOpenFailed . +If insufficient working storage is allocated, it returns +.BR XpmNoMemory . +If no error occurs then it returns +.BR XpmSuccess . If the passed XpmAttributes structure pointer is not NULL, -XpmWriteFileFromImage looks for the following attributes: +.BR 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 +As a backward compatibility feature, +.BR 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 +Finally, if the XpmRgbFilenameattribute is defined, +.BR 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 piped compress or gzip process. -And if instead of a file name NULL is passed to XpmWriteFileFromImage, it writes to the standard output. +.PP +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, +.BR XpmWriteFileFromImage () +writes to a piped compress or gzip process. +And if instead of a file name, NULL is passed to +.BR XpmWriteFileFromImage (), +it writes to the standard output. .SS XpmWriteFileFromPixmap -To write out a Pixmap to an XPM file, use XpmWriteFileFromPixmap. - +.PP +To write out a Pixmap to an XPM file, use +.BR XpmWriteFileFromPixmap (). +.PP If the passed XpmAttributes structure pointer is not NULL, -XpmWriteFileFromPixmap looks for the following attributes: XpmSize. +.BR XpmWriteFileFromPixmap () +looks for the following attributes: 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 XpmWriteFileFromPixmap function returns the same errors as XpmWriteFileFromImage. +Then it uses XGetImage to get from the given pixmaps the related X images which are passed to +.BR XpmWriteFileFromImage (). +Finally +.BR XpmWriteFileFromPixmap () +destroys the created images using XDestroyImage. +The +.BR XpmWriteFileFromPixmap () +function returns the same errors as +.BR 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. +.PP +.BR XpmWriteFileFromData () +writes an XPM data array to an XPM file. +.PP +.BR XpmWriteFileToData () +returns +.B XpmOpenFailed +if it cannot open the file, +.B XpmFileInvalid +if this is not a valid XPM data, and +.B 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 the XPM 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. +.PP +To write out an XpmImage to an XPM file, use +.BR XpmWriteFileFromXpmImage (). +The +.BR XpmWriteFileFromXpmImage () +function writes an image out to a file in the XPM format. +If the file cannot be opened, it returns +.BR XpmOpenFailed . +If insufficient working storage is allocated, it returns +.BR XpmNoMemory . +If no error occurs then it returns +.BR XpmSuccess . +If the passed XpmInfo structure pointer is not NULL, +.BR 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, +.BR XpmWriteFileFromXpmImage () +writes to a piped compress or gzip process. +And if instead of a file name, NULL is passed to +.BR 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 functions +.PP +.BR XpmWriteFileFromBuffer () +writes a XPM buffer to a file. +.BR XpmWriteFileFromBuffer () +returns +.B XpmOpenFailed +if it cannot open the file, and +.B XpmSuccess +otherwise. +.PP +As a convenience, the +.BR XpmReadFileToBuffer () +and +.BR XpmWriteFileFromBuffer () +functions 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 XpmCreateBufferFromPixmap, -XpmWriteFileFromBuffer, and XpmFree instead of XpmWriteFileFromPixmap. +Thus for instance one may decide to use +.BR XpmCreateBufferFromPixmap (), +.BR XpmWriteFileFromBuffer (), +and +.BR XpmFree () +instead of +.BR XpmWriteFileFromPixmap (). 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" +.ad l +.nh .BR XpmRead (__libmansuffix__) |