/Tools/pynche/README

http://unladen-swallow.googlecode.com/ · #! · 398 lines · 295 code · 103 blank · 0 comment · 0 complexity · 1dbbe04e9b5e5f506645f3e668932c73 MD5 · raw file

  1. Pynche - The PYthonically Natural Color and Hue Editor
  2. Contact: Barry A. Warsaw
  3. Email: bwarsaw@python.org
  4. Version: 1.3
  5. Introduction
  6. Pynche is a color editor based largely on a similar program that I
  7. originally wrote back in 1987 for the Sunview window system. That
  8. editor was called ICE, the Interactive Color Editor. I'd always
  9. wanted to port this program to X but didn't feel like hacking X
  10. and C code to do it. Fast forward many years, to where Python +
  11. Tkinter provides such a nice programming environment, with enough
  12. power, that I finally buckled down and re-implemented it. I
  13. changed the name because these days, too many other systems have
  14. the acronym `ICE'.
  15. Pynche should work with any variant of Python after 1.5.2
  16. (e.g. 2.0.1 and 2.1.1), using Tk 8.0.x. It's been tested on
  17. Solaris 2.6, Windows NT 4, and various Linux distros. You'll want
  18. to be sure to have at least Tk 8.0.3 for Windows. Also, Pynche is
  19. very colormap intensive, so it doesn't work very well on 8-bit
  20. graphics cards; 24bit+ graphics cards are so cheap these days,
  21. I'll probably never "fix" that.
  22. Pynche must find a text database of colors names in order to
  23. provide `nearest' color matching. Pynche is distributed with an
  24. rgb.txt file from the X11R6.4 distribution for this reason, along
  25. with other "Web related" database (see below). You can use a
  26. different file with the -d option. The file xlicense.txt contains
  27. the license only for rgb.txt and both files are in the X/
  28. subdirectory.
  29. Pynche is pronounced: Pin'-chee
  30. Running Standalone
  31. On Unix, start it by running the `pynche' script. On Windows, run
  32. pynche.pyw to inhibit the console window. When run from the
  33. command line, the following options are recognized:
  34. --database file
  35. -d file
  36. Alternate location of the color database file. Without this
  37. option, the first valid file found will be used (see below).
  38. --initfile file
  39. -i file
  40. Alternate location of the persistent initialization file. See
  41. the section on Persistency below.
  42. --ignore
  43. -X
  44. Ignore the persistent initialization file when starting up.
  45. Pynche will still write the current option settings to the
  46. persistent init file when it quits.
  47. --help
  48. -h
  49. Print the help message.
  50. initialcolor
  51. a Tk color name or #rrggbb color spec to be used as the
  52. initially selected color. This overrides any color saved in
  53. the persistent init file. Since `#' needs to be escaped in
  54. many shells, it is optional in the spec (e.g. #45dd1f is the
  55. same as 45dd1f).
  56. Running as a Modal Dialog
  57. Pynche can be run as a modal dialog, inside another application,
  58. say as a general color chooser. In fact, Grail 0.6 uses Pynche
  59. and a future version of IDLE may as well. Pynche supports the API
  60. implemented by the Tkinter standard tkColorChooser module, with a
  61. few changes as described below. By importing pyColorChooser from
  62. the Pynche package, you can run
  63. pyColorChooser.askcolor()
  64. which will popup Pynche as a modal dialog, and return the selected
  65. color.
  66. There are some UI differences when running as a modal
  67. vs. standalone. When running as a modal, there is no "Quit" menu
  68. item under the "File" menu. Instead there are "Okay" and "Cancel"
  69. buttons.
  70. When "Okay" is hit, askcolor() returns the tuple
  71. ((r, g, b), "name")
  72. where r, g, and b are red, green, and blue color values
  73. respectively (in the range 0 to 255). "name" will be a color name
  74. from the color database if there is an exact match, otherwise it
  75. will be an X11 color spec of the form "#rrggbb". Note that this
  76. is different than tkColorChooser, which doesn't know anything
  77. about color names.
  78. askcolor() supports the following optional keyword arguments:
  79. color
  80. the color to set as the initial selected color
  81. master[*]
  82. the master window to use as the parent of the modal
  83. dialog. Without this argument, pyColorChooser will create
  84. its own Tkinter.Tk instance as the master. This may not
  85. be what you want.
  86. databasefile
  87. similar to the --database option, the value must be a
  88. file name
  89. initfile[*]
  90. similar to the --initfile option, the value must be a
  91. file name
  92. ignore[*]
  93. similar to the --ignore flag, the value is a boolean
  94. wantspec
  95. When this is true, the "name" field in the return tuple
  96. will always be a color spec of the form "#rrggbb". It
  97. will not return a color name even if there is a match;
  98. this is so pyColorChooser can exactly match the API of
  99. tkColorChooser.
  100. [*] these arguments must be specified the first time
  101. askcolor() is used and cannot be changed on subsequent calls.
  102. The Colorstrip Window
  103. The top part of the main Pynche window contains the "variation
  104. strips". Each strip contains a number of "color chips". The
  105. strips always indicate the currently selected color by a highlight
  106. rectangle around the selected color chip, with an arrow pointing
  107. to the chip. Each arrow has an associated number giving you the
  108. color value along the variation's axis. Each variation strip
  109. shows you the colors that are reachable from the selected color by
  110. varying just one axis of the color solid.
  111. For example, when the selected color is (in Red/Green/Blue
  112. notation) 127/127/127, the Red Variations strip shows you every
  113. color in the range 0/127/127 to 255/127/127. Similarly for the
  114. green and blue axes. You can select any color by clicking on its
  115. chip. This will update the highlight rectangle and the arrow, as
  116. well as other displays in Pynche.
  117. Click on "Update while dragging" if you want Pynche to update the
  118. selected color while you drag along any variation strip (this will
  119. be a bit slower). Click on "Hexadecimal" to display the arrow
  120. numbers in hex.
  121. There are also two shortcut buttons in this window, which
  122. auto-select Black (0/0/0) and White (255/255/255).
  123. The Proof Window
  124. In the lower left corner of the main window you see two larger
  125. color chips. The Selected chip shows you a larger version of the
  126. color selected in the variation strips, along with its X11 color
  127. specification. The Nearest chip shows you the closest color in
  128. the X11 database to the selected color, giving its X11 color
  129. specification, and below that, its X11 color name. When the
  130. Selected chip color exactly matches the Nearest chip color, you
  131. will see the color name appear below the color specification for
  132. the Selected chip.
  133. Clicking on the Nearest color chip selects that color. Color
  134. distance is calculated in the 3D space of the RGB color solid and
  135. if more than one color name is the same distance from the selected
  136. color, the first one found will be chosen.
  137. Note that there may be more than one X11 color name for the same
  138. RGB value. In that case, the first one found in the text database
  139. is designated the "primary" name, and this is shown under the
  140. Nearest chip. The other names are "aliases" and they are visible
  141. in the Color List Window (see below).
  142. Both the color specifications and color names are selectable for
  143. copying and pasting into another window.
  144. The Type-in Window
  145. At the lower right of the main window are three entry fields.
  146. Here you can type numeric values for any of the three color axes.
  147. Legal values are between 0 and 255, and these fields do not allow
  148. you to enter illegal values. You must hit Enter or Tab to select
  149. the new color.
  150. Click on "Update while typing" if you want Pynche to select the
  151. color on every keystroke (well, every one that produces a legal
  152. value!) Click on "Hexadecimal" to display and enter color values
  153. in hex.
  154. Other Views
  155. There are three secondary windows which are not displayed by
  156. default. You can bring these up via the "View" menu on the main
  157. Pynche window.
  158. The Text Window
  159. The "Text Window" allows you to see what effects various colors
  160. have on the standard Tk text widget elements. In the upper part
  161. of the window is a plain Tk text widget and here you can edit the
  162. text, select a region of text, etc. Below this is a button "Track
  163. color changes". When this is turned on, any colors selected in
  164. the other windows will change the text widget element specified in
  165. the radio buttons below. When this is turned off, text widget
  166. elements are not affected by color selection.
  167. You can choose which element gets changed by color selection by
  168. clicking on one of the radio buttons in the bottom part of this
  169. window. Text foreground and background affect the text in the
  170. upper part of the window. Selection foreground and background
  171. affect the colors of the primary selection which is what you see
  172. when you click the middle button (depending on window system) and
  173. drag it through some text.
  174. The Insertion is the insertion cursor in the text window, where
  175. new text will be inserted as you type. The insertion cursor only
  176. has a background.
  177. The Color List Window
  178. The "Color List" window shows every named color in the color name
  179. database (this window may take a while to come up). In the upper
  180. part of the window you see a scrolling list of all the color names
  181. in the database, in alphabetical order. Click on any color to
  182. select it. In the bottom part of the window is displayed any
  183. aliases for the selected color (those color names that have the
  184. same RGB value, but were found later in the text database). For
  185. example, find the color "Black" and you'll see that its aliases
  186. are "gray0" and "grey0".
  187. If the color has no aliases you'll see "<no aliases>" here. If you
  188. just want to see if a color has an alias, and do not want to select a
  189. color when you click on it, turn off "Update on Click".
  190. Note that the color list is always updated when a color is selected
  191. from the main window. There's no way to turn this feature off. If
  192. the selected color has no matching color name you'll see
  193. "<no matching color>" in the Aliases window.
  194. The Details Window
  195. The "Details" window gives you more control over color selection
  196. than just clicking on a color chip in the main window. The row of
  197. buttons along the top apply the specified increment and decrement
  198. amounts to the selected color. These delta amounts are applied to
  199. the variation strips specified by the check boxes labeled "Move
  200. Sliders". Thus if just Red and Green are selected, hitting -10
  201. will subtract 10 from the color value along the red and green
  202. variation only. Note the message under the checkboxes; this
  203. indicates the primary color level being changed when more than one
  204. slider is tied together. For example, if Red and Green are
  205. selected, you will be changing the Yellow level of the selected
  206. color.
  207. The "At Boundary" behavior determines what happens when any color
  208. variation hits either the lower or upper boundaries (0 or 255) as
  209. a result of clicking on the top row buttons:
  210. Stop
  211. When the increment or decrement would send any of the tied
  212. variations out of bounds, the entire delta is discarded.
  213. Wrap Around
  214. When the increment or decrement would send any of the tied
  215. variations out of bounds, the out of bounds value is wrapped
  216. around to the other side. Thus if red were at 238 and +25
  217. were clicked, red would have the value 7.
  218. Preserve Distance
  219. When the increment or decrement would send any of the tied
  220. variations out of bounds, all tied variations are wrapped as
  221. one, so as to preserve the distance between them. Thus if
  222. green and blue were tied, and green was at 238 while blue was
  223. at 223, and +25 were clicked, green would be at 15 and blue
  224. would be at 0.
  225. Squash
  226. When the increment or decrement would send any of the tied
  227. variations out of bounds, the out of bounds variation is set
  228. to the ceiling of 255 or floor of 0, as appropriate. In this
  229. way, all tied variations are squashed to one edge or the
  230. other.
  231. The top row buttons have the following keyboard accelerators:
  232. -25 == Shift Left Arrow
  233. -10 == Control Left Arrow
  234. -1 == Left Arrow
  235. +1 == Right Arrow
  236. +10 == Control Right Arrow
  237. +25 == Shift Right Arrow
  238. Keyboard Accelerators
  239. Alt-w in any secondary window dismisses the window. In the main
  240. window it exits Pynche (except when running as a modal).
  241. Alt-q in any window exits Pynche (except when running as a modal).
  242. Persistency
  243. Pynche remembers various settings of options and colors between
  244. invocations, storing these values in a `persistent initialization
  245. file'. The actual location of this file is specified by the
  246. --initfile option (see above), and defaults to ~/.pynche.
  247. When Pynche exits, it saves these values in the init file, and
  248. re-reads them when it starts up. There is no locking on this
  249. file, so if you run multiple instances of Pynche at a time, you
  250. may clobber the init file.
  251. The actual options stored include
  252. - the currently selected color
  253. - all settings of checkbox and radio button options in all windows
  254. - the contents of the text window, the current text selection and
  255. insertion point, and all current text widget element color
  256. settings.
  257. - the name of the color database file (but not its contents)
  258. You can inhibit Pynche from reading the init file by supplying the
  259. --ignore option on the command line. However, you cannot suppress
  260. the storing of the settings in the init file on Pynche exit. If
  261. you really want to do this, use /dev/null as the init file, using
  262. --initfile.
  263. Color Name Database Files
  264. Pynche uses a color name database file to calculate the nearest
  265. color to the selected color, and to display in the Color List
  266. view. Several files are distributed with Pynche, described
  267. below. By default, the X11 color name database file is selected.
  268. Other files:
  269. html40colors.txt -- the HTML 4.0 guaranteed color names
  270. websafe.txt -- the 216 "Web-safe" colors that Netscape and MSIE
  271. guarantee will not be dithered. These are specified in #rrggbb
  272. format for both values and names
  273. webcolors.txt -- The 140 color names that Tim Peters and his
  274. sister say NS and MSIE both understand (with some controversy over
  275. AliceBlue).
  276. namedcolors.txt -- an alternative set of Netscape colors.
  277. You can switch between files by choosing "Load palette..." from
  278. the "File" menu. This brings up a standard Tk file dialog.
  279. Choose the file you want and then click "Ok". If Pynche
  280. understands the format in this file, it will load the database and
  281. update the appropriate windows. If not, it will bring up an error
  282. dialog.
  283. To Do
  284. Here's a brief list of things I want to do (some mythical day):
  285. - Better support for resizing the top level windows
  286. - More output views, e.g. color solids
  287. - Have the notion of a `last color selected'; this may require a
  288. new output view
  289. - Support setting the font in the text view
  290. - Support distutils setup.py for installation
  291. I'm open to suggestions!
  292. Local Variables:
  293. indent-tabs-mode: nil
  294. End: