Issue #7042: Use a better mechanism for testing timers in test_signal.

[python.git] / Tools / pynche / README

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!


\f
Local Variables:
indent-tabs-mode: nil
End: