Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 1 | Pynche - The PYthonically Natural Color and Hue Editor |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 2 | |
| 3 | Author: Barry A. Warsaw |
| 4 | Email: bwarsaw@python.org |
| 5 | Version: 0.1 |
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 | Introduction |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 8 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 9 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 18 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 19 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 26 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 27 | 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 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 | Pynche is pronounced `Pinch-ee'. |
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 | Running Standalone |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 36 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 37 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 40 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 41 | --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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 46 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 47 | --initfile file |
| 48 | -i file |
| 49 | Alternate location of the persistent initialization file. See |
| 50 | the section on Persistency below. |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 51 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 52 | --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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 57 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 58 | --help |
| 59 | -h |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 60 | Print the help message. |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 61 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 62 | initialcolor |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 63 | 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 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 | Running as a Modal Dialog |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 70 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 71 | 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 75 | |
Barry Warsaw | cf1daad | 1998-10-22 19:00:38 +0000 | [diff] [blame] | 76 | pyColorChooser.askcolor() |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 77 | |
Barry Warsaw | cf1daad | 1998-10-22 19:00:38 +0000 | [diff] [blame] | 78 | which will popup Pynche as a modal dialog, and return the selected |
| 79 | color. |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 80 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 81 | 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 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 | When "Okay" is hit, askcolor() returns the tuple |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 86 | |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 87 | ((r, g, b), "name") |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 88 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 89 | 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 Warsaw | cf1daad | 1998-10-22 19:00:38 +0000 | [diff] [blame] | 96 | askcolor() supports the following optional keyword arguments: |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 97 | |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 98 | color |
| 99 | the color to set as the initial selected color |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 100 | |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 101 | 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 Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 106 | |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 107 | databasefile[*] |
| 108 | similar to the --database option, the value must be a |
| 109 | file name |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 110 | |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 111 | initfile[*] |
| 112 | similar to the --initfile option, the value must be a |
| 113 | file name |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 114 | |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 115 | ignore[*] |
| 116 | similar to the --ignore flag, the value is a boolean |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 117 | |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 118 | 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 Warsaw | cf1daad | 1998-10-22 19:00:38 +0000 | [diff] [blame] | 124 | |
Barry Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 125 | [*] these arguments must be specified the first time |
| 126 | askcolor() is used and cannot be changed on subsequent calls. |
Barry Warsaw | cf1daad | 1998-10-22 19:00:38 +0000 | [diff] [blame] | 127 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 128 | The 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 | |
| 151 | The 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 | |
| 169 | The 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 | |
| 182 | Other 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 | |
| 188 | The 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 | |
| 211 | The 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 | |
| 232 | The 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 Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 250 | |
| 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 Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 276 | The top row buttons have the following keyboard accelerators: |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 277 | |
| 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 Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 285 | Keyboard Accelerators |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 286 | |
| 287 | Alt-w in any secondary window dismisses the window. In the main |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 288 | window it exits Pynche (except when running as a modal). |
Barry Warsaw | e55055d | 1998-10-06 23:03:22 +0000 | [diff] [blame] | 289 | |
Barry Warsaw | 3dd1c39 | 1998-10-22 04:14:24 +0000 | [diff] [blame] | 290 | Alt-q in any window exits Pynche (except when running as a modal). |
| 291 | |
| 292 | Persistency |
| 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 Warsaw | cf1daad | 1998-10-22 19:00:38 +0000 | [diff] [blame] | 319 | |
| 320 | To 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 Warsaw | eb6b9b7e | 1998-12-03 19:49:45 +0000 | [diff] [blame^] | 336 | |
| 337 | |
| 338 | |
| 339 | Local Variables: |
| 340 | indent-tabs-mode: nil |
| 341 | End: |