blob: d9e304f6d5066c31ef7af237e81f4609d6aa69c3 [file] [log] [blame]
Barry Warsawe55055d1998-10-06 23:03:22 +00001Pynche - The PYthonically Natural Color and Hue Editor
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +00002
3Author: Barry A. Warsaw
4Email: bwarsaw@python.org
5Version: 0.1
Barry Warsawe55055d1998-10-06 23:03:22 +00006
Barry Warsaw3dd1c391998-10-22 04:14:24 +00007Introduction
Barry Warsawe55055d1998-10-06 23:03:22 +00008
Barry Warsaw3dd1c391998-10-22 04:14:24 +00009 Pynche is a color editor based largely on a similar program that I
10 originally wrote back in 1987 for the Sunview window system. That
11 editor was called ICE, the Interactive Color Editor. I'd always
12 wanted to port this program to X but didn't feel like hacking X
13 and C code to do it. Fast forward many years, to where Python +
14 Tkinter provides such a nice programming environment, with enough
15 power, that I finally buckled down and re-implemented it. I
16 changed the name because these days, too many other systems have
17 the acronym `ICE'.
Barry Warsawe55055d1998-10-06 23:03:22 +000018
Barry Warsaw3dd1c391998-10-22 04:14:24 +000019 Pynche has been tested with Python 1.5.1 using Tk 8.0. It
20 probably works with Python 1.5. I've tested it on both Solaris
21 2.6 and Windows NT. There are some funky things that happen on
22 Windows but I think they are primarily Tk problems. You'll want
23 to be sure to have Tk 8.0.3 for Windows. Also, Pynche is very
24 colormap intensive, so it doesn't work very well on 8-bit graphics
25 cards. I'll probably fix that in the future.
Barry Warsawe55055d1998-10-06 23:03:22 +000026
Barry Warsaw3dd1c391998-10-22 04:14:24 +000027 Pynche must find a text database of colors, in the X11 format.
28 Pynche is distributed with an rgb.txt file from the X11R6.4
29 distribution for this reason, but you can use a different file
30 with the -d option. The file xlicense.txt contains the license
31 only for rgb.txt and both files are in the X/ subdirectory.
Barry Warsawe55055d1998-10-06 23:03:22 +000032
Barry Warsaw3dd1c391998-10-22 04:14:24 +000033 Pynche is pronounced `Pinch-ee'.
Barry Warsawe55055d1998-10-06 23:03:22 +000034
Barry Warsaw3dd1c391998-10-22 04:14:24 +000035Running Standalone
Barry Warsawe55055d1998-10-06 23:03:22 +000036
Barry Warsaw3dd1c391998-10-22 04:14:24 +000037 On Unix, start it by running the `pynche' script. On Windows, run
38 pynche.pyw to inhibit the console window. When run from the
39 command line, the following options are recognized:
Barry Warsawe55055d1998-10-06 23:03:22 +000040
Barry Warsaw3dd1c391998-10-22 04:14:24 +000041 --database file
42 -d file
43 Alternate location of the color database file. Without this
44 option, the first of /usr/openwin/lib/rgb.txt or X/rgb.txt
45 will be used.
Barry Warsawe55055d1998-10-06 23:03:22 +000046
Barry Warsaw3dd1c391998-10-22 04:14:24 +000047 --initfile file
48 -i file
49 Alternate location of the persistent initialization file. See
50 the section on Persistency below.
Barry Warsawe55055d1998-10-06 23:03:22 +000051
Barry Warsaw3dd1c391998-10-22 04:14:24 +000052 --ignore
53 -X
54 Ignore the persistent initialization file when starting up.
55 Pynche will still write the current option settings to the
56 persistent init file when it quits.
Barry Warsawe55055d1998-10-06 23:03:22 +000057
Barry Warsaw3dd1c391998-10-22 04:14:24 +000058 --help
59 -h
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +000060 Print the help message.
Barry Warsawe55055d1998-10-06 23:03:22 +000061
Barry Warsaw3dd1c391998-10-22 04:14:24 +000062 initialcolor
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +000063 a Tk color name or #rrggbb color spec to be used as the
64 initially selected color. This overrides any color saved in
65 the persistent init file. Since `#' needs to be escaped in
66 many shells, it is optional in the spec (e.g. #45dd1f is the
67 same as 45dd1f).
Barry Warsawe55055d1998-10-06 23:03:22 +000068
Barry Warsaw3dd1c391998-10-22 04:14:24 +000069Running as a Modal Dialog
Barry Warsawe55055d1998-10-06 23:03:22 +000070
Barry Warsaw3dd1c391998-10-22 04:14:24 +000071 Pynche can be run as a modal dialog, inside another application.
72 It supports the API implemented by the Tkinter standard
73 tkColorChooser module, with a few changes. By importing
74 pyColorChooser from the Pynche package, you can run
Barry Warsawe55055d1998-10-06 23:03:22 +000075
Barry Warsawcf1daad1998-10-22 19:00:38 +000076 pyColorChooser.askcolor()
Barry Warsawe55055d1998-10-06 23:03:22 +000077
Barry Warsawcf1daad1998-10-22 19:00:38 +000078 which will popup Pynche as a modal dialog, and return the selected
79 color.
Barry Warsawe55055d1998-10-06 23:03:22 +000080
Barry Warsaw3dd1c391998-10-22 04:14:24 +000081 There are some UI differences when running as a modal
82 vs. standalone. When running as a modal, there is no "File" menu,
83 but instead there are "Okay" and "Cancel" buttons.
Barry Warsawe55055d1998-10-06 23:03:22 +000084
Barry Warsaw3dd1c391998-10-22 04:14:24 +000085 When "Okay" is hit, askcolor() returns the tuple
Barry Warsawe55055d1998-10-06 23:03:22 +000086
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +000087 ((r, g, b), "name")
Barry Warsawe55055d1998-10-06 23:03:22 +000088
Barry Warsaw3dd1c391998-10-22 04:14:24 +000089 where r, g, and b are red, green, and blue color values
90 respectively (in the range 0 to 255). "name" will be a color name
91 from the color database if there is an exact match, otherwise it
92 will be an X11 color spec of the form "#rrggbb". Note that this
93 is different than tkColorChooser, which doesn't know anything
94 about color names.
95
Barry Warsawcf1daad1998-10-22 19:00:38 +000096 askcolor() supports the following optional keyword arguments:
Barry Warsaw3dd1c391998-10-22 04:14:24 +000097
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +000098 color
99 the color to set as the initial selected color
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000100
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +0000101 master[*]
102 the master window to use as the parent of the modal
103 dialog. Without this argument, pyColorChooser will create
104 it's own Tkinter.Tk instance as the master. This may not
105 be what you want.
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000106
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +0000107 databasefile[*]
108 similar to the --database option, the value must be a
109 file name
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000110
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +0000111 initfile[*]
112 similar to the --initfile option, the value must be a
113 file name
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000114
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +0000115 ignore[*]
116 similar to the --ignore flag, the value is a boolean
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000117
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +0000118 wantspec[*]
119 When this is true, the "name" field in the return tuple
120 will always be a color spec of the form "#rrggbb". It
121 will not return a color name even if there is a match;
122 this is so pyColorChooser can exactly match the API of
123 tkColorChooser.
Barry Warsawcf1daad1998-10-22 19:00:38 +0000124
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +0000125 [*] these arguments must be specified the first time
126 askcolor() is used and cannot be changed on subsequent calls.
Barry Warsawcf1daad1998-10-22 19:00:38 +0000127
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000128The Colorstrip Window
129
130 The top part of the main Pynche window contains the "variation
131 strips". Each strip contains a number of "color chips". The
132 strips always indicate the currently selected color by a highlight
133 rectangle around the selected color chip, with an arrow pointing
134 to the chip. Each arrow has an associated number giving you the
135 color value along the variation's axis. Each variation strip
136 shows you the colors that are reachable from the selected color by
137 varying just one axis of the color solid.
138
139 For example, when the selected color is (in Red/Green/Blue
140 notation) 127/127/127, the Red Variations strip shows you every
141 color in the range 0/127/127 to 255/127/127. Similarly for the
142 green and blue axes. You can select any color by clicking on its
143 chip. This will update the highlight rectangle and the arrow, as
144 well as other displays in Pynche.
145
146 Click on "Update while dragging" if you want Pynche to update the
147 selected color while you drag along any variation strip (this will
148 be slower). Click on "Hexadecimal" to display the arrow numbers
149 in hex.
150
151The Proof Window
152
153 In the lower left corner of the main window you see two larger
154 color chips. The Selected chip shows you a larger version of the
155 color selected in the variation strips, along with its X11 color
156 specification. The Nearest chip shows you the closest color in
157 the X11 database to the selected color, giving its X11 color name.
158 Clicking on the Nearest color chip selects that color. Color
159 distance is calculated in the 3D space of the RGB color solid and
160 if more than one color name is the same distance from the selected
161 color, the first one found will be chosen.
162
163 Note that there may be more than one X11 color name for the same
164 RGB value. In that case, the first one found in the text database
165 is designated the "primary" name, and this is shown under the
166 Nearest chip. The other names are "aliases" and they are visible
167 in other Pynche windows.
168
169The Type-in Window
170
171 At the lower right of the main window are three entry fields.
172 Here you can type numeric values for any of the three color axes.
173 Legal values are between 0 and 255, and these fields do not allow
174 you to enter illegal values. You must hit Enter or Tab to select
175 the new color.
176
177 Click on "Update while typing" if you want Pynche to select the
178 color on every keystroke (well, every one that produces a legal
179 value!) Click on "Hexadecimal" to display and enter color values
180 in hex.
181
182Other Views
183
184 There are three secondary windows which are not displayed by
185 default. You can bring these up via the "View" menu on the main
186 Pynche window.
187
188The Text Window
189
190 The "Text Window" allows you to see what effects various colors
191 have on the standard Tk text widget elements. In the upper part
192 of the window is a plain Tk text widget and here you can edit the
193 text, select a region of text, etc. Below this is a button "Track
194 color changes". When this is turned on, any colors selected in
195 the other windows will change the text widget element specified in
196 the radio buttons below. When this is turned off, text widget
197 elements are not affected by color selection.
198
199 You can choose which element gets changed by color selection by
200 clicking on one of the radio buttons in the bottom part of this
201 window. Text foreground and background affect the text in the
202 upper part of the window. Selection foreground and background
203 affect the colors of the primary selection which is what you see
204 when you click the middle button (depending on window system) and
205 drag it through some text.
206
207 The Insertion is the insertion cursor in the text window, where
208 new text will be inserted as you type. The insertion cursor only
209 has a background.
210
211The Color List Window
212
213 The "Color List" window shows every color in the text database
214 (this window may take a while to come up). In the upper part of
215 the window you see a scrolling list of all the color names in the
216 database, in alphabetical order. Click on any color to select it.
217 In the bottom part of the window is displayed any aliases for the
218 selected color (those color names that have the same RGB value,
219 but were found later in the text database). For example, find the
220 color "Black" and you'll see that its aliases are "gray0" and
221 "grey0".
222
223 If the color has no aliases you'll see "<no aliases>" here. If you
224 just want to see if a color has an alias, and do not want to select a
225 color when you click on it, turn off "Update on Click".
226
227 Note that the color list is always updated when a color is selected
228 from the main window. There's no way to turn this feature off. If
229 the selected color has no matching color name you'll see
230 "<no matching color>" in the Aliases window.
231
232The Details Window
233
234 The "Details" window gives you more control over color selection
235 than just clicking on a color chip in the main window. The row of
236 buttons along the top apply the specified increment and decrement
237 amounts to the selected color. These delta amounts are applied to
238 the variation strips specified by the check boxes labeled "Move
239 Sliders". Thus if just Red and Green are selected, hitting -10
240 will subtract 10 from the color value along the red and green
241 variation only. Note the message under the checkboxes; this
242 indicates the primary color level being changed when more than one
243 slider is tied together. For example, if Red and Green are
244 selected, you will be changing the Yellow level of the selected
245 color.
246
247 The "At Boundary" behavior determines what happens when any color
248 variation hits either the lower or upper boundaries (0 or 255) as
249 a result of clicking on the top row buttons:
Barry Warsawe55055d1998-10-06 23:03:22 +0000250
251 Stop
252 When the increment or decrement would send any of the tied
253 variations out of bounds, the entire delta is discarded.
254
255 Wrap Around
256 When the increment or decrement would send any of the tied
257 variations out of bounds, the out of bounds value is wrapped
258 around to the other side. Thus if red were at 238 and +25
259 were clicked, red would have the value 7.
260
261 Preseve Distance
262 When the increment or decrement would send any of the tied
263 variations out of bounds, all tied variations are wrapped as
264 one, so as to preserve the distance between them. Thus if
265 green and blue were tied, and green was at 238 while blue was
266 at 223, and +25 were clicked, green would be at 15 and blue
267 would be at 0.
268
269 Squash
270 When the increment or decrement would send any of the tied
271 variations out of bounds, the out of bounds variation is set
272 to the ceiling of 255 or floor of 0, as appropriate. In this
273 way, all tied variations are squashed to one edge or the
274 other.
275
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000276 The top row buttons have the following keyboard accelerators:
Barry Warsawe55055d1998-10-06 23:03:22 +0000277
278 -25 == Shift Left Arrow
279 -10 == Control Left Arrow
280 -1 == Left Arrow
281 +1 == Right Arrow
282 +10 == Control Right Arrow
283 +25 == Shift Right Arrow
284
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000285Keyboard Accelerators
Barry Warsawe55055d1998-10-06 23:03:22 +0000286
287 Alt-w in any secondary window dismisses the window. In the main
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000288 window it exits Pynche (except when running as a modal).
Barry Warsawe55055d1998-10-06 23:03:22 +0000289
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000290 Alt-q in any window exits Pynche (except when running as a modal).
291
292Persistency
293
294 Pynche remembers various settings of options and colors between
295 invocations, storing these values in a `persistent initialization
296 file'. The actual location of this file is specified by the
297 --initfile option (see above), and defaults to ~/.pynche.
298
299 When Pynche exits, it saves these values in the init file, and
300 re-reads them when it starts up. There is no locking on this
301 file, so if you run multiple instances of Pynche at a time, you
302 will override the init file.
303
304 The actual options stored include
305
306 - the currently selected color
307
308 - all settings of checkbox and radio button options in all windows
309
310 - the contents of the text window, the current text selection and
311 insertion point, and all current text widget element color
312 settings.
313
314 You can inhibit Pynche from reading the init file by supplying the
315 --ignore option on the command line. However, you cannot suppress
316 the storing of the settings in the init file on Pynche exit. If
317 you really want to do this, use /dev/null as the init file, using
318 --initfile.
Barry Warsawcf1daad1998-10-22 19:00:38 +0000319
320To Do
321
322 Here's a brief list of things I want to do:
323
324 - Better support for resizing the top level windows
325
326 - Better support on 8-bit screens
327
328 - More output views, e.g. color solids
329
330 - Have the notion of a `last color selected'; this may require a
331 new output view
332
333 - Support setting the font in the text view
334
335 I'm open to suggestions!
Barry Warsaweb6b9b7e1998-12-03 19:49:45 +0000336
337
338
339Local Variables:
340indent-tabs-mode: nil
341End: