]> git.saurik.com Git - wxWidgets.git/blob - src/xpm/readme
wxGetUserName() returns the user name (wxGetUserId()) if all else fails
[wxWidgets.git] / src / xpm / readme
1 /*
2 * Copyright (C) 1989-94 GROUPE BULL
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a copy
5 * of this software and associated documentation files (the "Software"), to
6 * deal in the Software without restriction, including without limitation the
7 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8 * sell copies of the Software, and to permit persons to whom the Software is
9 * furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
17 * GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
18 * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
19 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
20 *
21 * Except as contained in this notice, the name of GROUPE BULL shall not be
22 * used in advertising or otherwise to promote the sale, use or other dealings
23 * in this Software without prior written authorization from GROUPE BULL.
24 */
25
26
27 XPM Version 3
28
29 WHAT IS XPM?
30 ============
31
32 XPM (X PixMap) is a format for storing/retrieving X pixmaps to/from files.
33
34 Here is provided a library containing a set of four functions, similar to the
35 X bitmap functions as defined in the Xlib: XpmCreatePixmapFromData,
36 XpmCreateDataFromPixmap, XpmReadFileToPixmap and XpmWriteFileFromPixmap for
37 respectively including, storing, reading and writing this format, plus four
38 other: XpmCreateImageFromData, XpmCreateDataFromImage, XpmReadFileToImage and
39 XpmWriteFileFromImage for working with images instead of pixmaps.
40
41 This new version provides a C includable format, defaults for different types
42 of display: monochrome/color/grayscale, hotspot coordinates and symbol names
43 for colors for overriding default colors when creating the pixmap. It provides
44 a mechanism for storing information while reading a file which is re-used
45 while writing. This way comments, default colors and symbol names aren't lost.
46 It also handles "transparent pixels" by returning a shape mask in addition to
47 the created pixmap.
48
49 See the XPM Manual for more details.
50
51 HOW TO GET XPM?
52 ===============
53
54 New xpm updates are announced on the comp.windows.x newsgroup, and on the
55 "xpm-talk" list. All new "official" xpm releases can be found by ftp on:
56
57 ftp.x.org (18.112.44.100) contrib (Boston, USA)
58 avahi.inria.fr (192.5.60.47) pub (Sophia Antipolis, France)
59
60
61 DOCUMENTATION:
62 =============
63
64 Old users might read the CHANGES file for a history of changes interesting
65 the user.
66
67 Read the doc. The documentation is in PostScript format (file doc/xpm.ps) and
68 has been produced with FrameMaker. The source files are available on request.
69
70
71 INSTALLATION:
72 ============
73
74 To obtain the XPM library, first uncompress and untar the compressed tar file
75 in an approriate directory.
76
77 Then you can either compile xpm via "imake" or in a stand-alone way.
78
79 WITH IMAKE:
80
81 Imakefiles are provided to build both shared and unshared libraries.
82 First have a look at the beginning of the lib/Imakefile and see if you
83 need to do some modification to fit with your system.
84 You should know how to use imake to build the XPM Makefiles
85 by executing "xmkmf", then do:
86
87 make Makefiles
88 make depend (if you want to)
89 make
90
91 which will build the XPM library and the sxpm application.
92 Then do:
93
94 make install
95 make install.man
96
97 which will install the library and the sxpm pregram and man page.
98
99 If it fails, you may edit the Imakefiles to add compilation flags to
100 suit your machine.
101
102 WITHOUT IMAKE:
103
104 To compile xpm, in the xpm directory you just created, do:
105
106 make -f Makefile.noXtree
107
108 Then to install it, do:
109
110 make -f Makefile.noXtree install
111
112 SXPM:
113 ====
114
115 In addition to the library the sxpm tool is provided to show XPM file and
116 convert them from XPM1 or XPM2 to XPM version 3. If you have previously done
117 'make' or 'make all' you should have it yet, otherwise just do:
118
119 cd sxpm; make
120
121 This application shows you most of the features of XPM and its source can be
122 used to quickly see how to use the provided functions.
123
124 By executing 'sxpm -help' you will get the usage.
125
126 Executing 'sxpm -plaid' will show a demo of the XpmCreatePixmapFromData
127 function. The pixmap is created from the static variable plaid defined in the
128 sxpm.c file. sxpm will end when you press the key 'q' in the created window.
129
130 Executing 'sxpm -plaid -sc lines_in_mix blue' will show the feature of
131 overriding color symbols giving a colorname, executing 'sxpm -sp lines_in_mix
132 1' will show overriding giving a pixel value, and executing 'sxpm -plaid -cp
133 red 0' will show overriding giving a color value.
134
135 Then you should try 'sxpm -plaid -o output' to get an output file using the
136 XpmWriteFileFromPixmap function.
137
138 You can now try 'sxpm -plaid -o - -nod -rgb /usr/lib/X11/rgb.txt' to directly
139 get the pixmap printed out on the standard output with colornames instead of
140 rgb values.
141
142 Then you should try 'sxpm plaid.xpm' to use the XpmReadFileToPixmap function,
143 and 'cat plaid_mask.xpm|sxpm' to see how "transparent pixels" are handled.
144
145 The XpmCreatePixmapFromData function is on purpose called without any XpmInfos
146 flag to show the utility of this one. Indeed, compare the color section of the
147 two files foo and bar obtained from 'sxpm -nod -plaid -o foo' and 'sxpm -nod
148 plaid.xpm -o bar'. All the default colors and also the comments have been
149 restored.
150
151 To end look at plaid_ext.xpm and try "sxpm -nod plaid_ext.xpm -v" to see how
152 extensions are handled.
153
154 Of course, other combinations are allowed and should be tried. Thus, 'sxpm
155 plaid.xpm -o output -nod' will show you how to convert a file from XPM1 or XPM2
156 to a XPM version 3 using sxpm.
157
158 See the manual page for more detail.
159
160 OTHER TOOLS:
161 ===========
162
163 Several converters dealing with XPM and a pixmap editor can be found in the
164 xpm-contrib distribution. Also I recommend the use of netpbm to do any kind of
165 general image operations such as scaling, resizing, dithering, and to convert
166 from and to any other image format.
167
168 DISCUSSION:
169 ==========
170
171 There is a mailing list to discuss about XPM which is xpm-talk@sophia.inria.fr.
172 Any request to subscribe should be sent to xpm-talk-request@sophia.inria.fr.
173
174 COPYRIGHT:
175 ==========
176
177 Copyright 1989-94 GROUPE BULL --
178 See license conditions in the COPYRIGHT file of the XPM distribution
179
180 Please mail any bug reports or modifications done, comments, suggestions,
181 requests for updates or patches to port on another machine to:
182
183 lehors@sophia.inria.fr (INTERNET)
184
185 33 (FRANCE) 93.65.77.71 (VOICE PHONE)
186
187 Arnaud Le Hors (SURFACE MAIL)
188 Bull c/o Inria BP. 109
189 2004, Route des lucioles
190 Sophia Antipolis
191 06561 Valbonne Cedex
192 FRANCE