Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 1 | Pynche - The PYthonically Natural Color and Hue Editor |
| 2 | Copyright (C) 1998 CNRI |
| 3 | Author: Barry A. Warsaw <bwarsaw@python.org> |
| 4 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 5 | Introduction |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 6 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 7 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 16 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 17 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 24 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 25 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 30 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 31 | Pynche is pronounced `Pinch-ee'. |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 32 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 33 | Running Standalone |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 34 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 35 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 38 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 39 | --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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 44 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 45 | --initfile file |
| 46 | -i file |
| 47 | Alternate location of the persistent initialization file. See |
| 48 | the section on Persistency below. |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 49 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 50 | --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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 55 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 56 | --help |
| 57 | -h |
| 58 | Print the help message. |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 59 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 60 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 66 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 67 | Running as a Modal Dialog |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 68 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 69 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 73 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 74 | pyColorChooser.askcolor(master=window) |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 75 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 76 | where `window' is an Tkinter parent window object. Without the |
| 77 | `master' keyword argument, Pynche runs standalone. |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 78 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 79 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 82 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 83 | When "Okay" is hit, askcolor() returns the tuple |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 84 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 85 | ((r, g, b), "name") |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 86 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 87 | 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 | |
| 113 | The 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 | |
| 136 | The 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 | |
| 154 | The 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 | |
| 167 | Other 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 | |
| 173 | The 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 | |
| 196 | The 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 | |
| 217 | The 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 235 | |
| 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 Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 261 | The top row buttons have the following keyboard accelerators: |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 262 | |
| 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 Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 270 | Keyboard Accelerators |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 271 | |
| 272 | Alt-w in any secondary window dismisses the window. In the main |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 273 | window it exits Pynche (except when running as a modal). |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 274 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame^] | 275 | Alt-q in any window exits Pynche (except when running as a modal). |
| 276 | |
| 277 | Persistency |
| 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. |