--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/symbian-qemu-0.9.1-12/python-2.6.1/Tools/pynche/README Fri Jul 31 15:01:17 2009 +0100
@@ -0,0 +1,398 @@
+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: