blob: 48e896a4b3e6f5d55808d41072e950c22e7d9428 [file] [log] [blame]
Barry Warsawe55055d1998-10-06 23:03:22 +00001Pynche - The PYthonically Natural Color and Hue Editor
2Copyright (C) 1998 CNRI
3Author: Barry A. Warsaw <bwarsaw@python.org>
4
Barry Warsaw3dd1c391998-10-22 04:14:24 +00005Introduction
Barry Warsawe55055d1998-10-06 23:03:22 +00006
Barry Warsaw3dd1c391998-10-22 04:14:24 +00007 Pynche is a color editor based largely on a similar program that I
8 originally wrote back in 1987 for the Sunview window system. That
9 editor was called ICE, the Interactive Color Editor. I'd always
10 wanted to port this program to X but didn't feel like hacking X
11 and C code to do it. Fast forward many years, to where Python +
12 Tkinter provides such a nice programming environment, with enough
13 power, that I finally buckled down and re-implemented it. I
14 changed the name because these days, too many other systems have
15 the acronym `ICE'.
Barry Warsawe55055d1998-10-06 23:03:22 +000016
Barry Warsaw3dd1c391998-10-22 04:14:24 +000017 Pynche has been tested with Python 1.5.1 using Tk 8.0. It
18 probably works with Python 1.5. I've tested it on both Solaris
19 2.6 and Windows NT. There are some funky things that happen on
20 Windows but I think they are primarily Tk problems. You'll want
21 to be sure to have Tk 8.0.3 for Windows. Also, Pynche is very
22 colormap intensive, so it doesn't work very well on 8-bit graphics
23 cards. I'll probably fix that in the future.
Barry Warsawe55055d1998-10-06 23:03:22 +000024
Barry Warsaw3dd1c391998-10-22 04:14:24 +000025 Pynche must find a text database of colors, in the X11 format.
26 Pynche is distributed with an rgb.txt file from the X11R6.4
27 distribution for this reason, but you can use a different file
28 with the -d option. The file xlicense.txt contains the license
29 only for rgb.txt and both files are in the X/ subdirectory.
Barry Warsawe55055d1998-10-06 23:03:22 +000030
Barry Warsaw3dd1c391998-10-22 04:14:24 +000031 Pynche is pronounced `Pinch-ee'.
Barry Warsawe55055d1998-10-06 23:03:22 +000032
Barry Warsaw3dd1c391998-10-22 04:14:24 +000033Running Standalone
Barry Warsawe55055d1998-10-06 23:03:22 +000034
Barry Warsaw3dd1c391998-10-22 04:14:24 +000035 On Unix, start it by running the `pynche' script. On Windows, run
36 pynche.pyw to inhibit the console window. When run from the
37 command line, the following options are recognized:
Barry Warsawe55055d1998-10-06 23:03:22 +000038
Barry Warsaw3dd1c391998-10-22 04:14:24 +000039 --database file
40 -d file
41 Alternate location of the color database file. Without this
42 option, the first of /usr/openwin/lib/rgb.txt or X/rgb.txt
43 will be used.
Barry Warsawe55055d1998-10-06 23:03:22 +000044
Barry Warsaw3dd1c391998-10-22 04:14:24 +000045 --initfile file
46 -i file
47 Alternate location of the persistent initialization file. See
48 the section on Persistency below.
Barry Warsawe55055d1998-10-06 23:03:22 +000049
Barry Warsaw3dd1c391998-10-22 04:14:24 +000050 --ignore
51 -X
52 Ignore the persistent initialization file when starting up.
53 Pynche will still write the current option settings to the
54 persistent init file when it quits.
Barry Warsawe55055d1998-10-06 23:03:22 +000055
Barry Warsaw3dd1c391998-10-22 04:14:24 +000056 --help
57 -h
58 Print the help message.
Barry Warsawe55055d1998-10-06 23:03:22 +000059
Barry Warsaw3dd1c391998-10-22 04:14:24 +000060 initialcolor
61 a Tk color name or #rrggbb color spec to be used as the
62 initially selected color. This overrides any color saved in
63 the persistent init file. Since `#' needs to be escaped in
64 many shells, it is optional in the spec (e.g. #45dd1f is the
65 same as 45dd1f).
Barry Warsawe55055d1998-10-06 23:03:22 +000066
Barry Warsaw3dd1c391998-10-22 04:14:24 +000067Running as a Modal Dialog
Barry Warsawe55055d1998-10-06 23:03:22 +000068
Barry Warsaw3dd1c391998-10-22 04:14:24 +000069 Pynche can be run as a modal dialog, inside another application.
70 It supports the API implemented by the Tkinter standard
71 tkColorChooser module, with a few changes. By importing
72 pyColorChooser from the Pynche package, you can run
Barry Warsawe55055d1998-10-06 23:03:22 +000073
Barry Warsaw3dd1c391998-10-22 04:14:24 +000074 pyColorChooser.askcolor(master=window)
Barry Warsawe55055d1998-10-06 23:03:22 +000075
Barry Warsaw3dd1c391998-10-22 04:14:24 +000076 where `window' is an Tkinter parent window object. Without the
77 `master' keyword argument, Pynche runs standalone.
Barry Warsawe55055d1998-10-06 23:03:22 +000078
Barry Warsaw3dd1c391998-10-22 04:14:24 +000079 There are some UI differences when running as a modal
80 vs. standalone. When running as a modal, there is no "File" menu,
81 but instead there are "Okay" and "Cancel" buttons.
Barry Warsawe55055d1998-10-06 23:03:22 +000082
Barry Warsaw3dd1c391998-10-22 04:14:24 +000083 When "Okay" is hit, askcolor() returns the tuple
Barry Warsawe55055d1998-10-06 23:03:22 +000084
Barry Warsaw3dd1c391998-10-22 04:14:24 +000085 ((r, g, b), "name")
Barry Warsawe55055d1998-10-06 23:03:22 +000086
Barry Warsaw3dd1c391998-10-22 04:14:24 +000087 where r, g, and b are red, green, and blue color values
88 respectively (in the range 0 to 255). "name" will be a color name
89 from the color database if there is an exact match, otherwise it
90 will be an X11 color spec of the form "#rrggbb". Note that this
91 is different than tkColorChooser, which doesn't know anything
92 about color names.
93
94 When the optional keyword `wantspec' is true, a #rrggbb color spec
95 will always be returned instead of a color name.
96
97 askcolor() also supports the following optional keyword arguments
98 which parallel the command line options described above:
99
100 initialcolor
101
102 databasefile
103 similar to the --database option, the value must be a
104 file name
105
106 initfile
107 similar to the --initfile option, the value must be a
108 file name
109
110 ignore
111 similar to the --ignore flag, the value is a boolean
112
113The Colorstrip Window
114
115 The top part of the main Pynche window contains the "variation
116 strips". Each strip contains a number of "color chips". The
117 strips always indicate the currently selected color by a highlight
118 rectangle around the selected color chip, with an arrow pointing
119 to the chip. Each arrow has an associated number giving you the
120 color value along the variation's axis. Each variation strip
121 shows you the colors that are reachable from the selected color by
122 varying just one axis of the color solid.
123
124 For example, when the selected color is (in Red/Green/Blue
125 notation) 127/127/127, the Red Variations strip shows you every
126 color in the range 0/127/127 to 255/127/127. Similarly for the
127 green and blue axes. You can select any color by clicking on its
128 chip. This will update the highlight rectangle and the arrow, as
129 well as other displays in Pynche.
130
131 Click on "Update while dragging" if you want Pynche to update the
132 selected color while you drag along any variation strip (this will
133 be slower). Click on "Hexadecimal" to display the arrow numbers
134 in hex.
135
136The Proof Window
137
138 In the lower left corner of the main window you see two larger
139 color chips. The Selected chip shows you a larger version of the
140 color selected in the variation strips, along with its X11 color
141 specification. The Nearest chip shows you the closest color in
142 the X11 database to the selected color, giving its X11 color name.
143 Clicking on the Nearest color chip selects that color. Color
144 distance is calculated in the 3D space of the RGB color solid and
145 if more than one color name is the same distance from the selected
146 color, the first one found will be chosen.
147
148 Note that there may be more than one X11 color name for the same
149 RGB value. In that case, the first one found in the text database
150 is designated the "primary" name, and this is shown under the
151 Nearest chip. The other names are "aliases" and they are visible
152 in other Pynche windows.
153
154The Type-in Window
155
156 At the lower right of the main window are three entry fields.
157 Here you can type numeric values for any of the three color axes.
158 Legal values are between 0 and 255, and these fields do not allow
159 you to enter illegal values. You must hit Enter or Tab to select
160 the new color.
161
162 Click on "Update while typing" if you want Pynche to select the
163 color on every keystroke (well, every one that produces a legal
164 value!) Click on "Hexadecimal" to display and enter color values
165 in hex.
166
167Other Views
168
169 There are three secondary windows which are not displayed by
170 default. You can bring these up via the "View" menu on the main
171 Pynche window.
172
173The Text Window
174
175 The "Text Window" allows you to see what effects various colors
176 have on the standard Tk text widget elements. In the upper part
177 of the window is a plain Tk text widget and here you can edit the
178 text, select a region of text, etc. Below this is a button "Track
179 color changes". When this is turned on, any colors selected in
180 the other windows will change the text widget element specified in
181 the radio buttons below. When this is turned off, text widget
182 elements are not affected by color selection.
183
184 You can choose which element gets changed by color selection by
185 clicking on one of the radio buttons in the bottom part of this
186 window. Text foreground and background affect the text in the
187 upper part of the window. Selection foreground and background
188 affect the colors of the primary selection which is what you see
189 when you click the middle button (depending on window system) and
190 drag it through some text.
191
192 The Insertion is the insertion cursor in the text window, where
193 new text will be inserted as you type. The insertion cursor only
194 has a background.
195
196The Color List Window
197
198 The "Color List" window shows every color in the text database
199 (this window may take a while to come up). In the upper part of
200 the window you see a scrolling list of all the color names in the
201 database, in alphabetical order. Click on any color to select it.
202 In the bottom part of the window is displayed any aliases for the
203 selected color (those color names that have the same RGB value,
204 but were found later in the text database). For example, find the
205 color "Black" and you'll see that its aliases are "gray0" and
206 "grey0".
207
208 If the color has no aliases you'll see "<no aliases>" here. If you
209 just want to see if a color has an alias, and do not want to select a
210 color when you click on it, turn off "Update on Click".
211
212 Note that the color list is always updated when a color is selected
213 from the main window. There's no way to turn this feature off. If
214 the selected color has no matching color name you'll see
215 "<no matching color>" in the Aliases window.
216
217The Details Window
218
219 The "Details" window gives you more control over color selection
220 than just clicking on a color chip in the main window. The row of
221 buttons along the top apply the specified increment and decrement
222 amounts to the selected color. These delta amounts are applied to
223 the variation strips specified by the check boxes labeled "Move
224 Sliders". Thus if just Red and Green are selected, hitting -10
225 will subtract 10 from the color value along the red and green
226 variation only. Note the message under the checkboxes; this
227 indicates the primary color level being changed when more than one
228 slider is tied together. For example, if Red and Green are
229 selected, you will be changing the Yellow level of the selected
230 color.
231
232 The "At Boundary" behavior determines what happens when any color
233 variation hits either the lower or upper boundaries (0 or 255) as
234 a result of clicking on the top row buttons:
Barry Warsawe55055d1998-10-06 23:03:22 +0000235
236 Stop
237 When the increment or decrement would send any of the tied
238 variations out of bounds, the entire delta is discarded.
239
240 Wrap Around
241 When the increment or decrement would send any of the tied
242 variations out of bounds, the out of bounds value is wrapped
243 around to the other side. Thus if red were at 238 and +25
244 were clicked, red would have the value 7.
245
246 Preseve Distance
247 When the increment or decrement would send any of the tied
248 variations out of bounds, all tied variations are wrapped as
249 one, so as to preserve the distance between them. Thus if
250 green and blue were tied, and green was at 238 while blue was
251 at 223, and +25 were clicked, green would be at 15 and blue
252 would be at 0.
253
254 Squash
255 When the increment or decrement would send any of the tied
256 variations out of bounds, the out of bounds variation is set
257 to the ceiling of 255 or floor of 0, as appropriate. In this
258 way, all tied variations are squashed to one edge or the
259 other.
260
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000261 The top row buttons have the following keyboard accelerators:
Barry Warsawe55055d1998-10-06 23:03:22 +0000262
263 -25 == Shift Left Arrow
264 -10 == Control Left Arrow
265 -1 == Left Arrow
266 +1 == Right Arrow
267 +10 == Control Right Arrow
268 +25 == Shift Right Arrow
269
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000270Keyboard Accelerators
Barry Warsawe55055d1998-10-06 23:03:22 +0000271
272 Alt-w in any secondary window dismisses the window. In the main
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000273 window it exits Pynche (except when running as a modal).
Barry Warsawe55055d1998-10-06 23:03:22 +0000274
Barry Warsaw3dd1c391998-10-22 04:14:24 +0000275 Alt-q in any window exits Pynche (except when running as a modal).
276
277Persistency
278
279 Pynche remembers various settings of options and colors between
280 invocations, storing these values in a `persistent initialization
281 file'. The actual location of this file is specified by the
282 --initfile option (see above), and defaults to ~/.pynche.
283
284 When Pynche exits, it saves these values in the init file, and
285 re-reads them when it starts up. There is no locking on this
286 file, so if you run multiple instances of Pynche at a time, you
287 will override the init file.
288
289 The actual options stored include
290
291 - the currently selected color
292
293 - all settings of checkbox and radio button options in all windows
294
295 - the contents of the text window, the current text selection and
296 insertion point, and all current text widget element color
297 settings.
298
299 You can inhibit Pynche from reading the init file by supplying the
300 --ignore option on the command line. However, you cannot suppress
301 the storing of the settings in the init file on Pynche exit. If
302 you really want to do this, use /dev/null as the init file, using
303 --initfile.