/Tools/pynche/README
http://unladen-swallow.googlecode.com/ · #! · 398 lines · 295 code · 103 blank · 0 comment · 0 complexity · 1dbbe04e9b5e5f506645f3e668932c73 MD5 · raw file
- Pynche - The PYthonically Natural Color and Hue Editor
- Contact: Barry A. Warsaw
- Email: bwarsaw@python.org
- Version: 1.3
- 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 should work with any variant of Python after 1.5.2
- (e.g. 2.0.1 and 2.1.1), using Tk 8.0.x. It's been tested on
- Solaris 2.6, Windows NT 4, and various Linux distros. You'll want
- to be sure to have at least Tk 8.0.3 for Windows. Also, Pynche is
- very colormap intensive, so it doesn't work very well on 8-bit
- graphics cards; 24bit+ graphics cards are so cheap these days,
- I'll probably never "fix" that.
- Pynche must find a text database of colors names in order to
- provide `nearest' color matching. Pynche is distributed with an
- rgb.txt file from the X11R6.4 distribution for this reason, along
- with other "Web related" database (see below). 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: Pin'-chee
- 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 valid file found will be used (see below).
- --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,
- say as a general color chooser. In fact, Grail 0.6 uses Pynche
- and a future version of IDLE may as well. Pynche supports the API
- implemented by the Tkinter standard tkColorChooser module, with a
- few changes as described below. By importing pyColorChooser from
- the Pynche package, you can run
- pyColorChooser.askcolor()
- which will popup Pynche as a modal dialog, and return the selected
- color.
- There are some UI differences when running as a modal
- vs. standalone. When running as a modal, there is no "Quit" menu
- item under the "File" menu. 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.
- askcolor() supports the following optional keyword arguments:
- color
- the color to set as the initial selected color
- master[*]
- the master window to use as the parent of the modal
- dialog. Without this argument, pyColorChooser will create
- its own Tkinter.Tk instance as the master. This may not
- be what you want.
- 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
- wantspec
- When this is true, the "name" field in the return tuple
- will always be a color spec of the form "#rrggbb". It
- will not return a color name even if there is a match;
- this is so pyColorChooser can exactly match the API of
- tkColorChooser.
- [*] these arguments must be specified the first time
- askcolor() is used and cannot be changed on subsequent calls.
- 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 a bit slower). Click on "Hexadecimal" to display the arrow
- numbers in hex.
- There are also two shortcut buttons in this window, which
- auto-select Black (0/0/0) and White (255/255/255).
- 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
- specification, and below that, its X11 color name. When the
- Selected chip color exactly matches the Nearest chip color, you
- will see the color name appear below the color specification for
- the Selected chip.
-
- 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 the Color List Window (see below).
- Both the color specifications and color names are selectable for
- copying and pasting into another window.
- 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 named color in the color name
- 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
- variations out of bounds, the entire delta is discarded.
- Wrap Around
- When the increment or decrement would send any of the tied
- variations out of bounds, the out of bounds value is wrapped
- around to the other side. Thus if red were at 238 and +25
- were clicked, red would have the value 7.
- Preserve Distance
- When the increment or decrement would send any of the tied
- variations out of bounds, all tied variations are wrapped as
- one, so as to preserve the distance between them. Thus if
- green and blue were tied, and green was at 238 while blue was
- at 223, and +25 were clicked, green would be at 15 and blue
- would be at 0.
- Squash
- When the increment or decrement would send any of the tied
- variations out of bounds, the out of bounds variation is set
- to the ceiling of 255 or floor of 0, as appropriate. In this
- way, all tied variations are squashed to one edge or the
- other.
- The top row buttons have the following keyboard accelerators:
- -25 == Shift Left Arrow
- -10 == Control Left Arrow
- -1 == Left Arrow
- +1 == Right Arrow
- +10 == Control Right Arrow
- +25 == Shift Right Arrow
- Keyboard Accelerators
- Alt-w in any secondary window dismisses the window. In the main
- 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
- may clobber 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.
- - the name of the color database file (but not its contents)
- 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.
- Color Name Database Files
- Pynche uses a color name database file to calculate the nearest
- color to the selected color, and to display in the Color List
- view. Several files are distributed with Pynche, described
- below. By default, the X11 color name database file is selected.
- Other files:
- html40colors.txt -- the HTML 4.0 guaranteed color names
- websafe.txt -- the 216 "Web-safe" colors that Netscape and MSIE
- guarantee will not be dithered. These are specified in #rrggbb
- format for both values and names
- webcolors.txt -- The 140 color names that Tim Peters and his
- sister say NS and MSIE both understand (with some controversy over
- AliceBlue).
- namedcolors.txt -- an alternative set of Netscape colors.
- You can switch between files by choosing "Load palette..." from
- the "File" menu. This brings up a standard Tk file dialog.
- Choose the file you want and then click "Ok". If Pynche
- understands the format in this file, it will load the database and
- update the appropriate windows. If not, it will bring up an error
- dialog.
- To Do
- Here's a brief list of things I want to do (some mythical day):
- - Better support for resizing the top level windows
- - More output views, e.g. color solids
- - Have the notion of a `last color selected'; this may require a
- new output view
- - Support setting the font in the text view
- - Support distutils setup.py for installation
- I'm open to suggestions!
- Local Variables:
- indent-tabs-mode: nil
- End: