RE: read-color

["Drew Adams" <drew.adams@oracle.com>]

> This function does not support the "RGB:xx/xx/xx" color notation.  I
> think it should, if it wants to be _the_ ultimate means for reading
> color specifications.
> 
> Btw, why was this function added? there are no users of it in Emacs
> sources, and we already had facemenu-read-color, which is still used.
> Any pointers to relevant discussions are appreciated.

Richard will correct me if I'm wrong, but I believe he added it based on a
discussion we had off list about the code in my library `hexrgb.el'. Emacs
`read-color' is essentially `hexrgb-read-color' (see below). `hexrgb.el' is
here:
http://www.emacswiki.org/emacs/hexrgb.el.

FWIW, I use `hexrgb-read-color':

* In my version of `facemenu-read-color'.

* In various hexrgb commands that return color components (e.g. `hexrgb-hue' to
read a color and return its hue).

* In `icicle-read-color' with a prefix arg (`icicle-read-color' is more general)

* In `palette.el', to read a color name and: give its RGB or HSV components; to
pick a color by name; to move to the palette location of a color (name); and to
open the palette, a brightness scale, or a color swatch with the given color
current.

(defun hexrgb-read-color (&optional convert-to-RGB-p allow-empty-name-p prompt)
  "Read a color name or RGB hex value: #RRRRGGGGBBBB.
Completion is available for color names, but not for RGB hex strings.
If you input an RGB hex string, it must have the form #XXXXXXXXXXXX or
XXXXXXXXXXXX, where each X is a hex digit.  The number of Xs must be a
multiple of 3, with the same number of Xs for each of red, green, and
blue.  The order is red, green, blue.

In addition to standard color names and RGB hex values, the following
are available as color candidates.  In each case, the corresponding
color is used.

* `*copied foreground*'  - last copied foreground, if available
* `*copied background*'  - last copied background, if available
* `*mouse-2 foreground*' - foreground where you click `mouse-2'
* `*mouse-2 background*' - background where you click `mouse-2'
* `*point foreground*'   - foreground under the cursor
* `*point background*'   - background under the cursor

\(You can copy a color using eyedropper commands such as
`eyedrop-pick-foreground-at-mouse'.)

Checks input to be sure it represents a valid color.  If not, raises
an error (but see exception for empty input with non-nil
ALLOW-EMPTY-NAME-P).

Interactively, or with optional arg CONVERT-TO-RGB-P non-nil, converts
an input color name to an RGB hex string.  Returns the RGB hex string.

Optional arg ALLOW-EMPTY-NAME-P controls what happens if you enter an
empty color name (that is, you just hit `RET').  If non-nil, then
`hexrgb-read-color' returns an empty color name, \"\".  If nil, then
it raises an error.  Programs must test for \"\" if ALLOW-EMPTY-NAME-P
is non-nil.  They can then perform an appropriate action in case of
empty input.

Optional arg PROMPT is the prompt.  Nil means use a default prompt."
  (interactive "p")                     ; Always convert to RGB interactively.
  (let* ((completion-ignore-case t)
         (colors (if (fboundp 'eyedrop-foreground-at-point)
                     (append (and eyedrop-picked-foreground '(("*copied
foreground*")))
                             (and eyedrop-picked-background '(("*copied
background*")))
                             '(("*mouse-2 foreground*") ("*mouse-2 background*")
                               ("*point foreground*") ("*point background*"))
                             hexrgb-defined-colors-alist)
                   hexrgb-defined-colors-alist))
         (color (completing-read (or prompt "Color (name or #R+G+B+): ")
colors))
         hex-string)
    (when (fboundp 'eyedrop-foreground-at-point)
      (cond ((string= "*copied foreground*" color) (setq color
eyedrop-picked-foreground))
            ((string= "*copied background*" color) (setq color
eyedrop-picked-background))
            ((string= "*point foreground*" color)  (setq color
(eyedrop-foreground-at-point)))
            ((string= "*point background*" color)  (setq color
(eyedrop-background-at-point)))
            ((string= "*mouse-2 foreground*" color)
             (setq color (prog1 (eyedrop-foreground-at-mouse
                                 (read-event "Click `mouse-2' to choose
foreground color - "))
                           (read-event)))) ; Discard mouse up event.
            ((string= "*mouse-2 background*" color)
             (setq color (prog1 (eyedrop-background-at-mouse
                                 (read-event "Click `mouse-2' to choose
background color - "))
                           (read-event)))))) ; Discard mouse up event.
    (setq hex-string (or (string-match
"^#\\([a-fA-F0-9][a-fA-F0-9][a-fA-F0-9]\\)+$" color)
                         (and (string-match
"^\\([a-fA-F0-9][a-fA-F0-9][a-fA-F0-9]\\)+$" color)
                              t)))
    (if (and allow-empty-name-p (string= "" color))
        ""
      (when (and hex-string (not (eq 0 hex-string)))
        (setq color (concat "#" color))) ; No #; add it.
      (unless hex-string
        (when (or (string= "" color)
                  (not (if (fboundp 'test-completion) ; Not defined in Emacs 20.
                           (test-completion color colors)
                         (try-completion color colors))))
          (error "No such color: %S" color))
        (when convert-to-RGB-p (setq color (hexrgb-color-name-to-hex color))))
      (when (interactive-p) (message "Color: `%s'" color))
      color)))