1XpmRead(3)                     libXpm functions                     XpmRead(3)
2
3
4

NAME

6       XpmRead - read an XPM file
7
8

SYNOPSIS

10       int XpmReadFileToImage(Display *display, char *filename,
11              XImage **image_return, XImage **shapeimage_return,
12              XpmAttributes *attributes);
13
14       int XpmReadFileToPixmap(Display *display, Drawable d, char *filename,
15              Pixmap *pixmap_return, Pixmap *shapemask_return,
16              XpmAttributes *attributes);
17
18       int XpmReadFileToXpmImage(char *filename, XpmImage *image,
19              XpmInfo *info);
20
21       int XpmReadFileToBuffer(char *filename, char **buffer_return);
22
23       int XpmReadFileToData(char *filename, char ***data_return);
24
25

ARGUMENTS

27       display
28              Specifies the connection to the X server.
29
30       filename
31              Specifies the file name to use.
32
33       image_return
34              Returns the image which is created.
35
36       shapeimage_return
37              Returns  the shape mask image which is created if the color None
38              is used.
39
40       attributes
41              Specifies the location of a structure to get and store  informa‐
42              tion (or NULL).
43
44       buffer_return
45              Returns the buffer created.
46
47       data_return
48              Returns the data array created.
49
50       image  Specifies the image structure location.
51
52       info   Specifies the location of a structure to store possible informa‐
53              tion (or NULL).
54
55

DESCRIPTION

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
77       Note:  The  valuemask  of  the passed XpmAttributes must be set to some
78       valid value, at least zero, otherwise unpredictable errors can occur.
79
80       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
105       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
119       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
138
139   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
150
151   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
158       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
166
167   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
174
175   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
183

SEE ALSO

185       XpmCreateBuffer(3), XpmCreateData(3), XpmCreateImage(3),
186       XpmCreatePixmap(3), XpmCreateXpmImage(3), XpmFreeAttributes(3),
187       XpmWrite(3)
188
189
190
191X Version 11                     libXpm 3.5.15                      XpmRead(3)
Impressum