diff options
| -rw-r--r-- | Tools/pynche/README | 395 |
1 files changed, 262 insertions, 133 deletions
diff --git a/Tools/pynche/README b/Tools/pynche/README index 586e75f..48e896a 100644 --- a/Tools/pynche/README +++ b/Tools/pynche/README @@ -2,135 +2,236 @@ Pynche - The PYthonically Natural Color and Hue Editor Copyright (C) 1998 CNRI Author: Barry A. Warsaw <bwarsaw@python.org> -Pynche is a color editor based largely on a similar program that I -originally back in 1987 for the Sunview window system. That editor -was called ICE, the Interactive Color Editor. I'd always wanted to -port this program to X but didn't feel like hacking X and C code to do -it. Fast forward many years, to where Python + Tkinter provides such -a nice programming environment, with enough power, that I finally -buckled down and implemented it. I changed the name because these -days, too many other systems have the acronym `ICE'. - -Pynche has been tested with Python 1.5.1 using Tk 8.0. It probably -works with Python 1.5. I've tested it on both Solaris 2.6 and Windows -NT. There are some funky things that happen on Windows but I think -they are primarily Tk problems. You'll want to be sure to have Tk -8.0.3 for Windows. Also, Pynche is very colormap intensive, so it -doesn't work very well on 8-bit graphics cards. I'll probably fix -that in the future. - -Pynche must find a text database of colors, in the X11 format. Pynche -is distributed with an rgb.txt file from the X11R6.4 distribution for -this reason, but you can use a different file with the -d option. The -file xlicense.txt contains the license only for rgb.txt. - -Pynche is pronounced `Pinch-ee'. Start it by running the `pynche' -script. On Windows, run pynche.pyw to inhibit the console window. - -The top part of the main Pynche window contains the "variation -strips". Each strip contains a number of "color chips". The strips -always indicate the currently selected color by a highlight rectangle -around the selected color chip, with an arrow pointing to the chip. -Each arrow has an associated number giving you the color value along -the variation's axis. Each variation strip shows you the colors that -are reachable from the selected color by varying just one axis of the -color solid. - -For example, when the selected color is (in Red/Green/Blue notation) -127/127/127, the Red Variations strip shows you every color in the -range 0/127/127 to 255/127/127. Similarly for the green and blue -axes. You can select any color by clicking on its chip. This will -update the highlight rectangle and the arrow, as well as other -displays in Pynche. - -Click on "Update while dragging" if you want Pynche to update the -selected color while you drag along any variation strip (this will be -slower). Click on "Hexadecimal" to display the arrow numbers in hex. - -In the lower left corner of the main window you see two larger color -chips. The Selected chip shows you a larger version of the color -selected in the variation strips, along with its X11 color -specification. The Nearest chip shows you the closest color in the -X11 database to the selected color, giving its X11 color name. -Clicking on the Nearest color chip selects that color. Color distance -is calculated in the 3D space of the RGB color solid and if more than -one color name is the same distance from the selected color, the first -one found will be chosen. - -Note that there may be more than one X11 color name for the same RGB -value. In that case, the first one found in the text database is -designated the "primary" name, and this is shown under the Nearest -chip. The other names are "aliases" and they are visible in other -Pynche windows. - -At the lower right of the main window are three entry fields. Here -you can type numeric values for any of the three color axes. Legal -values are between 0 and 255, and these fields do not allow you to -enter illegal values. You must hit Enter or Tab to select the new -color. - -Click on "Update while typing" if you want Pynche to select the color -on every keystroke (well, every one that produces a legal value!). -Click on "Hexadecimal" to display and enter color values in hex. - -There are three secondary windows which are not displayed by default. -You can bring these up via the "View" menu on the main Pynche window. - -The "Text Window" allows you to see what effects various colors have -on the standard Tk text widget elements. In the upper part of the -window is a plain Tk text widget and here you can edit the text, -select a region of text, etc. Below this is a button "Track color -changes". When this is turned on, any colors selected in the other -windows will change the text widget element specified in the radio -buttons below. When this is turned off, text widget elements are not -affected by color selection. - -You can choose which element gets changed by color selection by -clicking on one of the radio buttons in the bottom part of this -window. Text foreground and background affect the text in the upper -part of the window. Selection foreground and background affect the -colors of the primary selection which is what you see when you click -the middle button (depending on window system) and drag it through -some text. - -The Insertion is the insertion cursor in the text window, where new -text will be inserted as you type. The insertion cursor only has a -background. - -The "Color List" window shows every color in the text database. This -is the primary reason why Pynche doesn't work so well on 8-bit -screens. In the upper part of the window you see a scrolling list of -all the color names in the database, in alphabetical order. Click on -any color to select it. In the bottom part of the window is displayed -any aliases for the selected color (those color names that have the -same RGB value, but were found later in the text database). For -example, find the color "Black" and you'll see that its aliases are -"gray0" and "grey0". - -If the color has no aliases you'll see "<no aliases>" here. If you -just want to see if a color has an alias, and do not want to select a -color when you click on it, turn off "Update on Click". - -Note that the color list is always updated when a color is selected -from the main window. There's no way to turn this feature off. If -the selected color has no matching color name you'll see -"<no matching color>" in the Aliases window. - -The "Details" window gives you more control over color selection than -just clicking on a color chip in the main window. The row of buttons -along the top apply the specified increment and decrement amounts to -the selected color. These delta amounts are applied to the variation -strips specified by the check boxes labeled "Move Sliders". Thus if -just Red and Green are selected, hitting -10 will subtract 10 from the -color value along the red and green variation only. Note the message -under the checkboxes; this indicates the primary color level being -changed when more than one slider is tied together. For example, if -Red and Green are selected, you will be changing the Yellow level of -the selected color. - -The "At Boundary" behavior determines what happens when any color -variation hits either the lower or upper boundaries (0 or 255) as a -result of clicking on the top row buttons: +Introduction + + Pynche is a color editor based largely on a similar program that I + originally wrote back in 1987 for the Sunview window system. That + editor was called ICE, the Interactive Color Editor. I'd always + wanted to port this program to X but didn't feel like hacking X + and C code to do it. Fast forward many years, to where Python + + Tkinter provides such a nice programming environment, with enough + power, that I finally buckled down and re-implemented it. I + changed the name because these days, too many other systems have + the acronym `ICE'. + + Pynche has been tested with Python 1.5.1 using Tk 8.0. It + probably works with Python 1.5. I've tested it on both Solaris + 2.6 and Windows NT. There are some funky things that happen on + Windows but I think they are primarily Tk problems. You'll want + to be sure to have Tk 8.0.3 for Windows. Also, Pynche is very + colormap intensive, so it doesn't work very well on 8-bit graphics + cards. I'll probably fix that in the future. + + Pynche must find a text database of colors, in the X11 format. + Pynche is distributed with an rgb.txt file from the X11R6.4 + distribution for this reason, but you can use a different file + with the -d option. The file xlicense.txt contains the license + only for rgb.txt and both files are in the X/ subdirectory. + + Pynche is pronounced `Pinch-ee'. + +Running Standalone + + On Unix, start it by running the `pynche' script. On Windows, run + pynche.pyw to inhibit the console window. When run from the + command line, the following options are recognized: + + --database file + -d file + Alternate location of the color database file. Without this + option, the first of /usr/openwin/lib/rgb.txt or X/rgb.txt + will be used. + + --initfile file + -i file + Alternate location of the persistent initialization file. See + the section on Persistency below. + + --ignore + -X + Ignore the persistent initialization file when starting up. + Pynche will still write the current option settings to the + persistent init file when it quits. + + --help + -h + Print the help message. + + initialcolor + a Tk color name or #rrggbb color spec to be used as the + initially selected color. This overrides any color saved in + the persistent init file. Since `#' needs to be escaped in + many shells, it is optional in the spec (e.g. #45dd1f is the + same as 45dd1f). + +Running as a Modal Dialog + + Pynche can be run as a modal dialog, inside another application. + It supports the API implemented by the Tkinter standard + tkColorChooser module, with a few changes. By importing + pyColorChooser from the Pynche package, you can run + + pyColorChooser.askcolor(master=window) + + where `window' is an Tkinter parent window object. Without the + `master' keyword argument, Pynche runs standalone. + + There are some UI differences when running as a modal + vs. standalone. When running as a modal, there is no "File" menu, + but instead there are "Okay" and "Cancel" buttons. + + When "Okay" is hit, askcolor() returns the tuple + + ((r, g, b), "name") + + where r, g, and b are red, green, and blue color values + respectively (in the range 0 to 255). "name" will be a color name + from the color database if there is an exact match, otherwise it + will be an X11 color spec of the form "#rrggbb". Note that this + is different than tkColorChooser, which doesn't know anything + about color names. + + When the optional keyword `wantspec' is true, a #rrggbb color spec + will always be returned instead of a color name. + + askcolor() also supports the following optional keyword arguments + which parallel the command line options described above: + + initialcolor + + databasefile + similar to the --database option, the value must be a + file name + + initfile + similar to the --initfile option, the value must be a + file name + + ignore + similar to the --ignore flag, the value is a boolean + +The Colorstrip Window + + The top part of the main Pynche window contains the "variation + strips". Each strip contains a number of "color chips". The + strips always indicate the currently selected color by a highlight + rectangle around the selected color chip, with an arrow pointing + to the chip. Each arrow has an associated number giving you the + color value along the variation's axis. Each variation strip + shows you the colors that are reachable from the selected color by + varying just one axis of the color solid. + + For example, when the selected color is (in Red/Green/Blue + notation) 127/127/127, the Red Variations strip shows you every + color in the range 0/127/127 to 255/127/127. Similarly for the + green and blue axes. You can select any color by clicking on its + chip. This will update the highlight rectangle and the arrow, as + well as other displays in Pynche. + + Click on "Update while dragging" if you want Pynche to update the + selected color while you drag along any variation strip (this will + be slower). Click on "Hexadecimal" to display the arrow numbers + in hex. + +The Proof Window + + In the lower left corner of the main window you see two larger + color chips. The Selected chip shows you a larger version of the + color selected in the variation strips, along with its X11 color + specification. The Nearest chip shows you the closest color in + the X11 database to the selected color, giving its X11 color name. + Clicking on the Nearest color chip selects that color. Color + distance is calculated in the 3D space of the RGB color solid and + if more than one color name is the same distance from the selected + color, the first one found will be chosen. + + Note that there may be more than one X11 color name for the same + RGB value. In that case, the first one found in the text database + is designated the "primary" name, and this is shown under the + Nearest chip. The other names are "aliases" and they are visible + in other Pynche windows. + +The Type-in Window + + At the lower right of the main window are three entry fields. + Here you can type numeric values for any of the three color axes. + Legal values are between 0 and 255, and these fields do not allow + you to enter illegal values. You must hit Enter or Tab to select + the new color. + + Click on "Update while typing" if you want Pynche to select the + color on every keystroke (well, every one that produces a legal + value!) Click on "Hexadecimal" to display and enter color values + in hex. + +Other Views + + There are three secondary windows which are not displayed by + default. You can bring these up via the "View" menu on the main + Pynche window. + +The Text Window + + The "Text Window" allows you to see what effects various colors + have on the standard Tk text widget elements. In the upper part + of the window is a plain Tk text widget and here you can edit the + text, select a region of text, etc. Below this is a button "Track + color changes". When this is turned on, any colors selected in + the other windows will change the text widget element specified in + the radio buttons below. When this is turned off, text widget + elements are not affected by color selection. + + You can choose which element gets changed by color selection by + clicking on one of the radio buttons in the bottom part of this + window. Text foreground and background affect the text in the + upper part of the window. Selection foreground and background + affect the colors of the primary selection which is what you see + when you click the middle button (depending on window system) and + drag it through some text. + + The Insertion is the insertion cursor in the text window, where + new text will be inserted as you type. The insertion cursor only + has a background. + +The Color List Window + + The "Color List" window shows every color in the text database + (this window may take a while to come up). In the upper part of + the window you see a scrolling list of all the color names in the + database, in alphabetical order. Click on any color to select it. + In the bottom part of the window is displayed any aliases for the + selected color (those color names that have the same RGB value, + but were found later in the text database). For example, find the + color "Black" and you'll see that its aliases are "gray0" and + "grey0". + + If the color has no aliases you'll see "<no aliases>" here. If you + just want to see if a color has an alias, and do not want to select a + color when you click on it, turn off "Update on Click". + + Note that the color list is always updated when a color is selected + from the main window. There's no way to turn this feature off. If + the selected color has no matching color name you'll see + "<no matching color>" in the Aliases window. + +The Details Window + + The "Details" window gives you more control over color selection + than just clicking on a color chip in the main window. The row of + buttons along the top apply the specified increment and decrement + amounts to the selected color. These delta amounts are applied to + the variation strips specified by the check boxes labeled "Move + Sliders". Thus if just Red and Green are selected, hitting -10 + will subtract 10 from the color value along the red and green + variation only. Note the message under the checkboxes; this + indicates the primary color level being changed when more than one + slider is tied together. For example, if Red and Green are + selected, you will be changing the Yellow level of the selected + color. + + The "At Boundary" behavior determines what happens when any color + variation hits either the lower or upper boundaries (0 or 255) as + a result of clicking on the top row buttons: Stop When the increment or decrement would send any of the tied @@ -157,7 +258,7 @@ result of clicking on the top row buttons: way, all tied variations are squashed to one edge or the other. -The top row buttons have the following keyboard accelerators: + The top row buttons have the following keyboard accelerators: -25 == Shift Left Arrow -10 == Control Left Arrow @@ -166,9 +267,37 @@ The top row buttons have the following keyboard accelerators: +10 == Control Right Arrow +25 == Shift Right Arrow -Other keyboard accelerators: +Keyboard Accelerators Alt-w in any secondary window dismisses the window. In the main - window it exits Pynche. + window it exits Pynche (except when running as a modal). + + Alt-q in any window exits Pynche (except when running as a modal). + +Persistency + + Pynche remembers various settings of options and colors between + invocations, storing these values in a `persistent initialization + file'. The actual location of this file is specified by the + --initfile option (see above), and defaults to ~/.pynche. + + When Pynche exits, it saves these values in the init file, and + re-reads them when it starts up. There is no locking on this + file, so if you run multiple instances of Pynche at a time, you + will override the init file. + + The actual options stored include + + - the currently selected color + + - all settings of checkbox and radio button options in all windows + + - the contents of the text window, the current text selection and + insertion point, and all current text widget element color + settings. - Alt-q in any window exits Pynche. + You can inhibit Pynche from reading the init file by supplying the + --ignore option on the command line. However, you cannot suppress + the storing of the settings in the init file on Pynche exit. If + you really want to do this, use /dev/null as the init file, using + --initfile. |