1XpmRead(3) libXpm functions XpmRead(3)
2
6 XpmRead - read an XPM file
7
10 int XpmReadFileToImage(Display *display, char *filename,
11 XImage **image_return, XImage **shapeimage_return,
12 XpmAttributes *attributes);
13 int XpmReadFileToPixmap(Display *display, Drawable d, char *filename,
15 Pixmap *pixmap_return, Pixmap *shapemask_return,
16 XpmAttributes *attributes);
17 int XpmReadFileToXpmImage(char *filename, XpmImage *image,
19 XpmInfo *info);
20 int XpmReadFileToBuffer(char *filename, char **buffer_return);
22 int XpmReadFileToData(char *filename, char ***data_return);
24
27 display
28 Specifies the connection to the X server.
29 filename
31 Specifies the file name to use.
32 image_return
34 Returns the image which is created.
35 shapeimage_return
37 Returns the shape mask image which is created if the color None
38 is used.
39 attributes
41 Specifies the location of a structure to get and store informa‐
42 tion (or NULL).
43 buffer_return
45 Returns the buffer created.
46 data_return
48 Returns the data array created.
49 image Specifies the image structure location.
51 info Specifies the location of a structure to store possible informa‐
53 tion (or NULL).
54
57 XpmReadFileToImage
58 The XpmReadFileToImage() function reads in a file in the XPM format.
59 If the file cannot be opened it returns XpmOpenFailed. If the file can
60 be opened but does not contain valid XPM data, it returns XpmFileIn‐
61 valid. If insufficient working storage is allocated, it returns Xpm‐
62 NoMemory. If the passed XpmAttributes structure pointer is not NULL,
63 XpmReadFileToImage() looks for the following attributes: XpmVisual,
64 XpmColormap, XpmDepth, XpmColorSymbols, XpmExactColors, XpmCloseness,
65 XpmRGBCloseness, XpmAllocCloseColors, XpmReturnPixels, XpmReturnAl‐
66 locPixels, XpmAllocColor, XpmFreeColors, XpmColorClosure, XpmReturnEx‐
67 tensions, XpmReturnColorTable, XpmBitmapFormat, sets the XpmSize, the
68 XpmCharsPerPixel, and possibly the XpmHotspot attributes when return‐
69 ing. As a backward compatibility feature, XpmReadFileToImage() also
70 looks for the XpmReturnInfos attributes. As specified in the table
71 (page 12), if the data related to the attributes XpmReturnExtensions,
72 XpmReturnColorTable, and XpmReturnInfos cannot be returned as requested
73 because of insufficient memory storage, XpmReadFileToImage() will
74 change the valuemask to mention this and will try to continue. So the
75 caller should check on this before accessing this data.
76 Note: The valuemask of the passed XpmAttributes must be set to some
78 valid value, at least zero, otherwise unpredictable errors can occur.
79 XpmReadFileToImage() allocates colors, as read from the file or possi‐
81 bly overridden as specified in the XpmColorSymbols attributes. The
82 colors are allocated using the color settings for the visual specified
83 by the XpmColorKey attribute, which has the value XPM_MONO, XPM_GRAY4,
84 XPM_GRAY, or XPM_COLOR. If the XpmColorKey attribute is not set it is
85 determined by examining the type of visual. If no default value exists
86 for the specified visual, it first looks for other defaults nearer to
87 the monochrome visual type and secondly nearer to the color visual
88 type. If the color which is found is not valid (cannot be parsed), it
89 looks for another default one according to the same algorithm. If al‐
90 locating a color fails, and the closeness attribute is set, it tries to
91 find a color already in the colormap that is closest to the desired
92 color, and uses that. If the alloc_close_colors attribute is set to
93 False, the found close color is not allocated but it is used anyway.
94 This is especially useful for applications which use a private colormap
95 containing read/write cells and have complete control over the col‐
96 ormap. On the other hand, since in such a case there is no guarantee
97 that the color pixel will not change any time, this should be avoided
98 when using the default colormap. If no color can be found that is
99 within closeness of the Red, Green, and Blue components of the desired
100 color, it reverts to trying other default values as explained above.
101 For finer control over the closeness requirements of a particular icon,
102 the red_closeness, green_closeness, and blue_closeness attributes may
103 be used instead of the more general closeness attribute.
104 The RGB components are integers within the range 0 (black) to 65535
106 (white). A closeness of less than 10000, for example, will cause only
107 quite close colors to be matched, while a closeness of more than 50000
108 will allow quite dissimilar colors to match. Specifying a closeness of
109 more than 65535 will allow any color to match, thus forcing the icon to
110 be drawn in color no matter how bad the colormap is. The value 40000
111 seems to be about right for many situations requiring reasonable but
112 not perfect matches. With this setting the color must only be within
113 the same general area of the RGB cube as the desired color. If the ex‐
114 actColors attribute is set it then returns XpmColorError, otherwise it
115 creates the images and returns XpmSuccess. If no color is found, and
116 no close color exists or is wanted, and all visuals have been ex‐
117 hausted, XpmColorFailed is returned.
118 XpmReadFileToImage() returns the created image to image_return if not
120 NULL and possibly the created shapemask to shapeimage_return if not
121 NULL and the color None is used. If required it stores into the XpmAt‐
122 tributes structure the list of the used pixels. When the image depth
123 is one, the image format is either as specified by the bitmap_format
124 attribute if set or ZPixmap. When the depth is different from one the
125 image format is always ZPixmap. When finished the caller must free the
126 images using XDestroyImage(3), the allocated colors using XFreeCol‐
127 ors(3) or the application equivalent function when the standard Xlib
128 functions are not used, and possibly the data returned into the XpmAt‐
129 tributes using XpmFreeAttributes(3). In addition, on systems which
130 support such features XpmReadFileToImage() deals with compressed files
131 by forking an uncompress or gzip process and reading from the piped re‐
132 sult. It assumes that the specified file is compressed if the given
133 file name ends by ’.Z’ or ’.gz’. In case the file name does not end
134 so, XpmReadFileToImage() looks for the given file name assuming it is
135 not a compressed file. And if instead of a file name NULL is passed to
136 XpmReadFileToImage(), it reads from the standard input.
137 XpmReadFileToPixmap
140 The XpmReadFileToPixmap() function creates X images using XpmReadFile‐
141 ToImage() and thus returns the same errors. In addition on success it
142 then creates the related pixmaps, using XPutImage(3), which are re‐
143 turned to pixmap_return and shapemask_return if not NULL, and finally
144 destroys the created images using XDestroyImage(3). When finished the
145 caller must free the pixmaps using XFreePixmap(3), the allocated colors
146 using XFreeColors(3) or the application equivalent function when the
147 standard Xlib functions are not used, and possibly the data returned
148 into the XpmAttributes using XpmFreeAttributes(3).
149 XpmReadFileToBuffer
152 XpmReadFileToBuffer() allocates and fills a buffer from a file. Xpm‐
153 ReadFileToBuffer() returns XpmOpenFailed if it cannot open the file,
154 returns XpmNoMemory if insufficient working storage is allocated, and
155 XpmSuccess otherwise. The allocated buffer returned by XpmReadFileTo‐
156 Buffer() should be freed with XpmFree(3) when done.
157 As a convenience, the XpmReadFileToBuffer() and XpmWriteFileFrom‐
159 Buffer(3) are provided to copy a file to a buffer and to write a file
160 from a buffer. Thus for instance one may decide to use XpmReadFileTo‐
161 Buffer(), XpmCreatePixmapFromBuffer(3), and XpmFree(3) instead of Xpm‐
162 ReadFileToPixmap(). On some systems this may lead to a performance im‐
163 provement, since the parsing will be performed in memory, but it uses
164 more memory.
165 XpmReadFileToData
168 XpmReadFileToData() returns XpmOpenFailed if it cannot open the file,
169 XpmNoMemory if insufficient working storage is allocated, XpmFileIn‐
170 valid if this is not a valid XPM file, and XpmSuccess otherwise. The
171 allocated data returned by XpmReadFileToData() should be freed with
172 XpmFree(3) when done.
173 XpmReadFileToXpmImage
176 The XpmReadFileToXpmImage() function reads in a file in the XPM format.
177 If the file cannot be opened it returns XpmOpenFailed. If the file can
178 be opened but does not contain valid XPM data, it returns XpmFileIn‐
179 valid. If insufficient working storage is allocated, it returns Xpm‐
180 NoMemory. On success it fills in the given XpmImage structure and re‐
181 turns XpmSuccess.
182
185 XpmCreateBuffer(3), XpmCreateData(3), XpmCreateImage(3),
186 XpmCreatePixmap(3), XpmCreateXpmImage(3), XpmFreeAttributes(3),
187 XpmWrite(3)
188X Version 11 libXpm 3.5.17 XpmRead(3)