path: root/README.org

#+OPTIONS: _:nil
#+title: colorful-mode
#+subtitle: Preview any color in your buffer in real time.
#+author: Elias G. Perez

[[https://raw.githubusercontent.com/DevelopmentCool2449/colorful-mode/main/assets/colorful-mode-logo.svg]]

 #+BEGIN_QUOTE
 Preview any color in your buffer in real time.
 #+END_QUOTE

#+html: <a href="https://elpa.gnu.org/packages/colorful-mode.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/colorful-mode.svg"/></a>
#+html: <a href="https://jcs-emacs.github.io/jcs-elpa/"><img alt="JCS ELPA" src="https://raw.githubusercontent.com/jcs-emacs/badges/master/elpa/v/colorful-mode.svg"></a>
#+html: <a href="https://github.com/DevelopmentCool2449/colorful-mode/actions/workflows/test.yml"><img alt="CI" src="https://github.com/DevelopmentCool2449/colorful-mode/actions/workflows/test.yml/badge.svg"></a>

#+html: <img src="https://raw.githubusercontent.com/DevelopmentCool2449/emacs-svg-badges/main/elisp_logo_warning.svg" align="right" width="10%">

🎨 =colorful-mode= is a minor mode that allow you highlight/preview any color
format such as *color hex* and *color names*, in your current buffer
in real time and in a user friendly way based/inspired on 🌈[[https://elpa.gnu.org/packages/rainbow-mode.html][rainbow-mode.el]].

* Features ✨
- Real time color highlight.
- Supports:
  - Hexadecimal (#RRGGBB, #RGB, #RRGGBBAA, #RGBA).
  - Color names (Emacs, HTML, CSS).
  - CSS
    - rgb/rgba
    - hsl/hsla
    - oklab/oklch
    - user-defined colors variables:
      - gtk @define-color
      - var()
  - LaTeX colors (gray, rbg, RGB, HTML)
- Convert current color at point or in region to other formats
  such as hexadecimal or color names *(only available for some colors)*
  with mouse click support.
- Prefix/suffix string instead highlight /(Optional)/.
- Highlight only in strings /(Optional)/.
- Blacklist color keywords from being highlighted.

* Screenshots and animated GIFs 📷

[[https://raw.githubusercontent.com/DevelopmentCool2449/colorful-mode/main/assets/screenshot1.png]]
Supports for both GUI/TUI.

[[https://raw.githubusercontent.com/DevelopmentCool2449/colorful-mode/main/assets/screenshot2.png]]
Support for custom color string indicator.

[[https://raw.githubusercontent.com/DevelopmentCool2449/colorful-mode/main/assets/gif1.gif]]

[[https://raw.githubusercontent.com/DevelopmentCool2449/colorful-mode/main/assets/gif2.gif]]
Change color support in real time.

[[https://raw.githubusercontent.com/DevelopmentCool2449/colorful-mode/main/assets/gif3.gif]]
Support for color changing at region.

* User Options 🔧
** Customizable User options
- =colorful-allow-mouse-clicks (default: t)= If non-nil, allow using mouse buttons
  for change color.
- =colorful-use-prefix (default: nil)= If non-nil, use prefix for preview color
  instead highlight them.

#+begin_quote
[!WARNING]

css-derived modes colorize rgb and hex colors out the box,
this may interfere with colorful prefix, you can disable this setting
'css-fontify-colors' to nil
#+end_quote

- =colorful-prefix-string (default: "●")= String to be used in highlights.
  Only relevant if `colorful-use-prefix' is non-nil.
- =colorful-prefix-alignment (default: 'left)= The position to put prefix string.
  The value can be left or right.
  Only relevant if `colorful-use-prefix' is non-nil.
- =colorful-extra-color-keyword-functions=
  default:
  '(colorful-add-hex-colors
    (emacs-lisp-mode . colorful-add-color-names)
    ((html-mode css-mode) .
     (colorful-add-css-variables-colors
      colorful-add-rgb-colors
      colorful-add-hsl-colors
      colorful-add-oklab-oklch-colors
      colorful-add-color-names))
    (latex-mode . colorful-add-latex-colors))
  List of functions to add extra color keywords to colorful-color-keywords.

  It can be a cons cell specifying the mode (or a list of modes)
  e.g:

  (((css-mode css-ts-mode) . colorful-add-rgb-colors)
    (emacs-lisp-mode . (colorful-add-color-names
                        colorful-add-rgb-colors))
    ((text-mode html-mode) . (colorful-add-color-names
                              colorful-add-rgb-colors))
    ...)

  Or a simple list of functions for executing wherever colorful is active:
  (colorful-add-color-names
    colorful-add-rgb-colors)

  Available functions are:
  + colorful-add-hex-colors.
  + colorful-add-color-names.
  + colorful-add-css-variables-colors.
  + colorful-add-rgb-colors.
  + colorful-add-hsl-colors.
  + colorful-add-latex-colors

- =colorful-exclude-colors (default: '("#define"))= List of keywords not to highlight.
- =colorful-short-hex-conversions (default: t)= If non-nil, colorful
  will converted long hex colors to \"#RRGGBB\" format.  Setting this
  to non-nil can make converted hex inaccurate.
- =colorful-only-strings (default: nil)= If non-nil, colorful will only highlight colors inside strings.
  If set to `only-prog', the colors in `prog-mode' will be highlighted
  only if they are inside a string, this doesn't include `css-mode' and
  derived.
- =colorful-highlight-in-comments= If non-nil, colorful will highlight colors inside comments.
  NOTE: If this is set, this will highlight any keyword within the
  comments, including color names, which can be annoying.
- =colorful-html-colors-alist= Alist of HTML colors. Each entry should have the form (COLOR-NAME . HEXADECIMAL-COLOR).
- =global-colorful-modes (default: '(prog-mode help-mode html-mode css-mode latex-mode))= Which major modes global-colorful-mode is switched on in (globally).

** Faces
- =colorful-base= Face used as base for highlight color names.
  Changing background or foreground color will have no effect.

** Interactive User Functions.
- =colorful-change-or-copy-color= Change or copy color at point to
  another format.
- =colorful-convert-and-change-color= Convert color at point or colors
  in region to another format.
- =colorfu-convert-and-copy-color= Convert color at point to another
  format and copy it to the kill ring.
- =colorful-mode= Buffer-local minor mode.
- =global-colorful-mode= Global minor mode.

** Key bindings
These key bindings are defined by: =colorful-mode-map=
- =C-x c x= → =colorful-change-or-copy-color=.
- =C-x c c= → =colorful-convert-and-copy-color=.
- =C-x c r= → =colorful-convert-and-change-color=.

* Setups and Guides 📖

** Enabling colors to specifics major-modes
If you want to use css rgb colors outside css-derived modes, you
can add them to `colorful-extra-color-keyword-functions' in your config.

#+begin_src elisp
  (add-to-list 'colorful-extra-color-keyword-functions '(insert-your-major-mode . colorful-add-rgb-colors))
#+end_src

If you want also use hsl and rgb together you can use this
#+begin_src elisp
  (add-to-list 'colorful-extra-color-keyword-functions '(insert-your-major-mode . (colorful-add-rgb-colors colorful-add-hsl-colors)))
#+end_src

colorful provides extra functions out-the-box that enable additional
highlighting:

- =colorful-add-hex-colors=: Add Hexadecimal colors highlighting.
- =colorful-add-color-names=: Add color names highlighting.
- =colorful-add-css-variables-colors=: Add CSS user-defined color variables highlighting.
- =colorful-add-rgb-colors=: Add CSS RGB colors highlighting.
- =colorful-add-oklab-oklch-colors=: Add CSS OkLab and OkLch colors highlighting.
- =colorful-add-hsl-colors=: Add CSS HSL colors highlighting.
- =colorful-add-latex-colors=: Add LaTeX rgb/RGB/HTML/Grey colors highlighting.

See: =colorful-extra-color-keyword-functions= for more details.

* Usage and Installation 📦
It's recommended that you must use emacs-28.x or higher.

For install colorful run:
- =M-x package-install colorful-mode=

Once you have it installed you can activate colorful locally in your
buffer with =M-x colorful-mode=, if want enable it globally without
using hooks then you can do =M-x global-colorful-mode=

* Configuration ⚙️

Example /(Personal)/ configuration for your =init.el=:

#+begin_src emacs-lisp
(use-package colorful-mode
  ;; :diminish
  ;; :ensure t ; Optional
  :custom
  (colorful-use-prefix t)
  (colorful-only-strings 'only-prog)
  (css-fontify-colors nil)
  :config
  (global-colorful-mode t)
  (add-to-list 'global-colorful-modes 'helpful-mode))
#+end_src

** Disable colorful in regions

If you want to disable colorful at region this hack may be useful
for you:

#+begin_src emacs-lisp
(add-hook 'post-command-hook
          (lambda ()
            "delete colorful overlay on active mark"
            (when-let* (colorful-mode
                        (beg (use-region-beginning))
                        (end (use-region-end)))
              ;; Remove full colorful overlay instead only the part where
              ;; the region is.
                  (dolist (ov (overlays-in beg end))
                    (when (overlay-get ov 'colorful--overlay)
                      (delete-overlay ov))))))

(add-hook 'deactivate-mark-hook
          (lambda ()
            "refontify deleted mark"
            (when-let* (colorful-mode
                        (beg (region-beginning))
                        (end (region-end)))
              (font-lock-flush beg end))))
#+end_src

* How does it compare to =rainbow-mode= or built-in =css fontify colors=?
=colorful-mode= improves =rainbow-mode= and =css fontify-colors= in adding more features:

| Comparison                                            | colorful-mode.el | rainbow-mode.el | built-in css-mode |
|-------------------------------------------------------+------------------+-----------------+-------------------|
| Compatible with hl-line and other overlays?           | ✓               | ❌             | ❌               |
| Convert color to other formats?                       | ✓               | ❌             | ✓                |
| Optionally use string prefix/suffix instead highlight | ✓               | ❌             | ❌               |
| Blacklist colors?                                     | ✓               | ❌^{1}            | ❌               |
| Allow highlight specifics colors in specific modes    | ✓               | ✓^{2}             | ❌               |
| Optionally highlight only in strings                  | ✓               | ❌             | ❌               |
| No performance issues?^{3}                               | ❌              | ✓              | ✓                |

#+begin_src text
[1] rainbow-mode (like colorful) uses regex for highlight some
    keywords, however it cannot exclude specifics colors (such as
    "#def" that overrides C "#define" keyword).
[2] Only for some colors.
[3] I didn't a benchmark however due colorful-mode uses overlays
    instead text properties it can be a bit slow.
#+end_src

The intention is to provide a featured alternative to
=rainbow-mode.el= and =css-fontify-colors= with a user-friendly approach.

If you prefer only highlights without color conversion, prefix/suffix
string indicator and/or anything else you can use =rainbow-mode.el=.

or something built-in and just for css then use built-in
css-fontify-colors which is activated by default

On the other hand, if you want convert colors, overlays, optional
prefix strings and more features you can use =colorful-mode.el=.
* [[https://raw.githubusercontent.com/DevelopmentCool2449/colorful-mode/main/CONTRIBUITING.org][How to Contribute]]
colorful-mode is part of GNU ELPA, if you want send patches you will
need assign copyright to the Free Software Foundation.
Please see the [[https://raw.githubusercontent.com/DevelopmentCool2449/colorful-mode/main/CONTRIBUITING.org][CONTRIBUTING.org]] file for getting more information.

#+html: <img src="https://raw.githubusercontent.com/DevelopmentCool2449/emacs-svg-badges/main/powered_by_emacs.svg" align="left" width="10%" alt="Powered by GNU Emacs">
#+html: <img src="https://raw.githubusercontent.com/DevelopmentCool2449/emacs-svg-badges/main/powered_by_org_mode.svg" align="right" width="10%" alt="Powered by Org Mode">