Tools/pynche/README

   1 Pynche - The PYthonically Natural Color and Hue Editor
   2 Copyright (C) 1998 CNRI
   3 Author: Barry A. Warsaw <bwarsaw@python.org>
   4
   5 Introduction
   6
   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'.
  16
  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.
  24
  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.
  30
  31     Pynche is pronounced `Pinch-ee'.
  32
  33 Running Standalone
  34
  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:
  38
  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.
  44
  45     --initfile file
  46     -i file
  47         Alternate location of the persistent initialization file.  See
  48         the section on Persistency below.
  49
  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.
  55
  56     --help
  57     -h
  58         Print the help message.
  59
  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).
  66
  67 Running as a Modal Dialog
  68
  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
  73
  74         pyColorChooser.askcolor()
  75
  76     which will popup Pynche as a modal dialog, and return the selected
  77     color.
  78
  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.
  82
  83     When "Okay" is hit, askcolor() returns the tuple
  84
  85         ((r, g, b), "name")
  86
  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     askcolor() supports the following optional keyword arguments:
  95
  96         color
  97             the color to set as the initial selected color
  98
  99         master[*]
 100             the master window to use as the parent of the modal
 101             dialog.  Without this argument, pyColorChooser will create
 102             it's own Tkinter.Tk instance as the master.  This may not
 103             be what you want.
 104
 105         databasefile[*]
 106             similar to the --database option, the value must be a
 107             file name
 108
 109         initfile[*]
 110             similar to the --initfile option, the value must be a
 111             file name
 112
 113         ignore[*]
 114             similar to the --ignore flag, the value is a boolean
 115
 116         wantspec[*]
 117             When this is true, the "name" field in the return tuple
 118             will always be a color spec of the form "#rrggbb".  It
 119             will not return a color name even if there is a match;
 120             this is so pyColorChooser can exactly match the API of
 121             tkColorChooser.
 122
 123         [*] these arguments must be specified the first time
 124         askcolor() is used and cannot be changed on subsequent calls.
 125
 126 The Colorstrip Window
 127
 128     The top part of the main Pynche window contains the "variation
 129     strips".  Each strip contains a number of "color chips".  The
 130     strips always indicate the currently selected color by a highlight
 131     rectangle around the selected color chip, with an arrow pointing
 132     to the chip.  Each arrow has an associated number giving you the
 133     color value along the variation's axis.  Each variation strip
 134     shows you the colors that are reachable from the selected color by
 135     varying just one axis of the color solid.
 136
 137     For example, when the selected color is (in Red/Green/Blue
 138     notation) 127/127/127, the Red Variations strip shows you every
 139     color in the range 0/127/127 to 255/127/127.  Similarly for the
 140     green and blue axes.  You can select any color by clicking on its
 141     chip.  This will update the highlight rectangle and the arrow, as
 142     well as other displays in Pynche.
 143
 144     Click on "Update while dragging" if you want Pynche to update the
 145     selected color while you drag along any variation strip (this will
 146     be slower).  Click on "Hexadecimal" to display the arrow numbers
 147     in hex.
 148
 149 The Proof Window
 150
 151     In the lower left corner of the main window you see two larger
 152     color chips.  The Selected chip shows you a larger version of the
 153     color selected in the variation strips, along with its X11 color
 154     specification.  The Nearest chip shows you the closest color in
 155     the X11 database to the selected color, giving its X11 color name.
 156     Clicking on the Nearest color chip selects that color.  Color
 157     distance is calculated in the 3D space of the RGB color solid and
 158     if more than one color name is the same distance from the selected
 159     color, the first one found will be chosen.
 160
 161     Note that there may be more than one X11 color name for the same
 162     RGB value.  In that case, the first one found in the text database
 163     is designated the "primary" name, and this is shown under the
 164     Nearest chip.  The other names are "aliases" and they are visible
 165     in other Pynche windows.
 166
 167 The Type-in Window
 168
 169     At the lower right of the main window are three entry fields.
 170     Here you can type numeric values for any of the three color axes.
 171     Legal values are between 0 and 255, and these fields do not allow
 172     you to enter illegal values.  You must hit Enter or Tab to select
 173     the new color.
 174
 175     Click on "Update while typing" if you want Pynche to select the
 176     color on every keystroke (well, every one that produces a legal
 177     value!)  Click on "Hexadecimal" to display and enter color values
 178     in hex.
 179
 180 Other Views
 181
 182     There are three secondary windows which are not displayed by
 183     default.  You can bring these up via the "View" menu on the main
 184     Pynche window.
 185
 186 The Text Window
 187
 188     The "Text Window" allows you to see what effects various colors
 189     have on the standard Tk text widget elements.  In the upper part
 190     of the window is a plain Tk text widget and here you can edit the
 191     text, select a region of text, etc.  Below this is a button "Track
 192     color changes".  When this is turned on, any colors selected in
 193     the other windows will change the text widget element specified in
 194     the radio buttons below.  When this is turned off, text widget
 195     elements are not affected by color selection.
 196
 197     You can choose which element gets changed by color selection by
 198     clicking on one of the radio buttons in the bottom part of this
 199     window.  Text foreground and background affect the text in the
 200     upper part of the window.  Selection foreground and background
 201     affect the colors of the primary selection which is what you see
 202     when you click the middle button (depending on window system) and
 203     drag it through some text.
 204
 205     The Insertion is the insertion cursor in the text window, where
 206     new text will be inserted as you type.  The insertion cursor only
 207     has a background.
 208
 209 The Color List Window
 210
 211     The "Color List" window shows every color in the text database
 212     (this window may take a while to come up).  In the upper part of
 213     the window you see a scrolling list of all the color names in the
 214     database, in alphabetical order.  Click on any color to select it.
 215     In the bottom part of the window is displayed any aliases for the
 216     selected color (those color names that have the same RGB value,
 217     but were found later in the text database).  For example, find the
 218     color "Black" and you'll see that its aliases are "gray0" and
 219     "grey0".
 220
 221     If the color has no aliases you'll see "<no aliases>" here.  If you
 222     just want to see if a color has an alias, and do not want to select a
 223     color when you click on it, turn off "Update on Click".
 224
 225     Note that the color list is always updated when a color is selected
 226     from the main window.  There's no way to turn this feature off.  If
 227     the selected color has no matching color name you'll see
 228     "<no matching color>" in the Aliases window.
 229
 230 The Details Window
 231
 232     The "Details" window gives you more control over color selection
 233     than just clicking on a color chip in the main window.  The row of
 234     buttons along the top apply the specified increment and decrement
 235     amounts to the selected color.  These delta amounts are applied to
 236     the variation strips specified by the check boxes labeled "Move
 237     Sliders".  Thus if just Red and Green are selected, hitting -10
 238     will subtract 10 from the color value along the red and green
 239     variation only.  Note the message under the checkboxes; this
 240     indicates the primary color level being changed when more than one
 241     slider is tied together.  For example, if Red and Green are
 242     selected, you will be changing the Yellow level of the selected
 243     color.
 244
 245     The "At Boundary" behavior determines what happens when any color
 246     variation hits either the lower or upper boundaries (0 or 255) as
 247     a result of clicking on the top row buttons:
 248
 249     Stop
 250         When the increment or decrement would send any of the tied
 251         variations out of bounds, the entire delta is discarded.
 252
 253     Wrap Around
 254         When the increment or decrement would send any of the tied
 255         variations out of bounds, the out of bounds value is wrapped
 256         around to the other side.  Thus if red were at 238 and +25
 257         were clicked, red would have the value 7.
 258
 259     Preseve Distance
 260         When the increment or decrement would send any of the tied
 261         variations out of bounds, all tied variations are wrapped as
 262         one, so as to preserve the distance between them.  Thus if
 263         green and blue were tied, and green was at 238 while blue was
 264         at 223, and +25 were clicked, green would be at 15 and blue
 265         would be at 0.
 266
 267     Squash
 268         When the increment or decrement would send any of the tied
 269         variations out of bounds, the out of bounds variation is set
 270         to the ceiling of 255 or floor of 0, as appropriate.  In this
 271         way, all tied variations are squashed to one edge or the
 272         other.
 273
 274     The top row buttons have the following keyboard accelerators:
 275
 276     -25 == Shift Left Arrow
 277     -10 == Control Left Arrow
 278      -1 == Left Arrow
 279      +1 == Right Arrow
 280     +10 == Control Right Arrow
 281     +25 == Shift Right Arrow
 282
 283 Keyboard Accelerators
 284
 285     Alt-w in any secondary window dismisses the window.  In the main
 286     window it exits Pynche (except when running as a modal).
 287
 288     Alt-q in any window exits Pynche (except when running as a modal).
 289
 290 Persistency
 291
 292     Pynche remembers various settings of options and colors between
 293     invocations, storing these values in a `persistent initialization
 294     file'.  The actual location of this file is specified by the
 295     --initfile option (see above), and defaults to ~/.pynche.
 296
 297     When Pynche exits, it saves these values in the init file, and
 298     re-reads them when it starts up.  There is no locking on this
 299     file, so if you run multiple instances of Pynche at a time, you
 300     will override the init file.
 301
 302     The actual options stored include
 303
 304     - the currently selected color
 305
 306     - all settings of checkbox and radio button options in all windows
 307
 308     - the contents of the text window, the current text selection and
 309       insertion point, and all current text widget element color
 310       settings.
 311
 312     You can inhibit Pynche from reading the init file by supplying the
 313     --ignore option on the command line.  However, you cannot suppress
 314     the storing of the settings in the init file on Pynche exit.  If
 315     you really want to do this, use /dev/null as the init file, using
 316     --initfile.
 317
 318 To Do
 319
 320     Here's a brief list of things I want to do:
 321
 322     - Better support for resizing the top level windows
 323
 324     - Better support on 8-bit screens
 325
 326     - More output views, e.g. color solids
 327
 328     - Have the notion of a `last color selected'; this may require a
 329       new output view
 330
 331     - Support setting the font in the text view
 332
 333     I'm open to suggestions!