Function: read-color

read-color is an interactive and byte-compiled function defined in faces.el.gz.

Signature

(read-color &optional PROMPT CONVERT-TO-RGB ALLOW-EMPTY-NAME MSG FOREGROUND FACE)

Documentation

Read a color name or RGB triplet, return a string, the color name or RGB.

Completion is available for color names, but not for RGB triplets.

RGB triplets have the form "#RRGGBB". Each of the R, G, and B components can have one to four digits, but all three components must have the same number of digits. Each digit is a hex value between 0 and F; either upper case or lower case for A through F are acceptable.

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.

 * foreground at point - foreground under the cursor
 * background at point - background under the cursor

Optional arg PROMPT is the prompt; if nil, use a default prompt.

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

If optional arg ALLOW-EMPTY-NAME is non-nil, the user is allowed to enter an empty color name (the empty string).

Interactively, or with optional arg MSG non-nil, print the resulting color name in the echo area.

Interactively, provides completion for selecting the color. If the optional argument FOREGROUND is non-nil, shows the completion candidates with their foregound color changed to be the color of the candidate, otherwise changes the background color of the candidates. The optional argument FACE determines the other face attributes of the candidates on display.

View in manual

Probably introduced at or before Emacs version 23.1.

Key Bindings

Aliases

facemenu-read-color

Source Code

;; Defined in /usr/src/emacs/lisp/faces.el.gz
(defun read-color (&optional prompt convert-to-RGB allow-empty-name msg
			     foreground face)
  "Read a color name or RGB triplet, return a string, the color name or RGB.
Completion is available for color names, but not for RGB triplets.

RGB triplets have the form \"#RRGGBB\".  Each of the R, G, and B
components can have one to four digits, but all three components
must have the same number of digits.  Each digit is a hex value
between 0 and F; either upper case or lower case for A through F
are acceptable.

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.

 * `foreground at point'   - foreground under the cursor
 * `background at point'   - background under the cursor

Optional arg PROMPT is the prompt; if nil, use a default prompt.

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

If optional arg ALLOW-EMPTY-NAME is non-nil, the user is allowed
to enter an empty color name (the empty string).

Interactively, or with optional arg MSG non-nil, print the
resulting color name in the echo area.

Interactively, provides completion for selecting the color.  If
the optional argument FOREGROUND is non-nil, shows the completion
candidates with their foregound color changed to be the color of
the candidate, otherwise changes the background color of the
candidates.  The optional argument FACE determines the other
face attributes of the candidates on display."
  (interactive "i\np\ni\np")    ; Always convert to RGB interactively.
  (let* ((completion-ignore-case t)
	 (color-alist
          `(("foreground at point" . ,(foreground-color-at-point))
            ("background at point" . ,(background-color-at-point))
            ,@(if allow-empty-name '(("" . unspecified)))
            ,@(mapcar (lambda (c) (cons c c)) (defined-colors))))
         (colors (mapcar (lambda (pair)
                           (let* ((name (car pair))
                                  (color (cdr pair)))
                             (faces--string-with-color name color
                                                       foreground face)))
                         color-alist))
	 (color (completing-read
		 (or prompt "Color (name or #RGB triplet): ")
		 ;; Completing function for reading colors, accepting
		 ;; both color names and RGB triplets.
		 (lambda (string pred flag)
		   (cond
		    ((null flag)        ; Try completion.
		     (or (try-completion string colors pred)
			 (if (color-defined-p string)
			     string)))
		    ((eq flag t)        ; List all completions.
		     (or (all-completions string colors pred)
			 (if (color-defined-p string)
			     (list string))))
		    ((eq flag 'lambda)  ; Test completion.
		     (or (member string colors)
			 (color-defined-p string)))))
		 nil t)))

    ;; Process named colors.
    (when (member color colors)
      (cond ((string-equal color "foreground at point")
	     (setq color (foreground-color-at-point)))
	    ((string-equal color "background at point")
	     (setq color (background-color-at-point))))
      (when (and convert-to-RGB
		 (not (string-equal color "")))
        (let ((components (color-values color)))
	  (unless (string-match-p "^#\\(?:[[:xdigit:]][[:xdigit:]][[:xdigit:]]\\)+$" color)
	    (setq color (format "#%04X%04X%04X"
				(logand 65535 (nth 0 components))
				(logand 65535 (nth 1 components))
				(logand 65535 (nth 2 components))))))))
    (when msg (message "Color: `%s'" color))
    color))