patch 8.2.3562: cannot add color names
Problem: Cannot add color names.
Solution: Add the v:colornames dictionary. (Drew Vogel, closes #8761)
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 8d31483..418aee9 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1840,6 +1840,43 @@
command.
See |multi-lang|.
+ *v:colornames*
+v:colornames A dictionary that maps color names to hex color strings. These
+ color names can be used with the |highlight-guifg|,
+ |highlight-guibg|, and |highlight-guisp| parameters. Updating
+ an entry in v:colornames has no immediate effect on the syntax
+ highlighting. The highlight commands (probably in a
+ colorscheme script) need to be re-evaluated in order to use
+ the updated color values. For example: >
+
+ :let v:colornames['fuscia'] = '#cf3ab4'
+ :let v:colornames['mauve'] = '#915f6d'
+ :highlight Normal guifg=fuscia guibg=mauve
+<
+ This cannot be used to override the |cterm-colors| but it can
+ be used to override other colors. For example, the X11 colors
+ defined in the `colors/lists/default.vim` (previously defined
+ in |rgb.txt|). When defining new color names in a plugin, the
+ recommended practice is to set a color entry only when it does
+ not already exist. For example: >
+
+ :call extend(v:colornames, {
+ \ 'fuscia': '#cf3ab4',
+ \ 'mauve': '#915f6d,
+ \ }, 'keep')
+<
+ Using |extend| with the 'keep' option updates each color only
+ if it did not exist in |v:colornames|. Doing so allows the
+ user to choose the precise color value for a common name
+ by setting it in their |.vimrc|.
+
+ It is possible to remove entries from this dictionary but
+ doing so is *NOT* recommended. Doing so is disruptive to
+ other scripts. It is also unlikely to achieve the desired
+ result because the |colorscheme| and |highlight| commands will
+ both automatically load all `colors/lists/default.vim` color
+ scripts.
+
*v:completed_item* *completed_item-variable*
v:completed_item
|Dictionary| containing the |complete-items| for the most
diff --git a/runtime/doc/gui_w32.txt b/runtime/doc/gui_w32.txt
index b83df1b..227d0a2 100644
--- a/runtime/doc/gui_w32.txt
+++ b/runtime/doc/gui_w32.txt
@@ -323,20 +323,10 @@
Gray, Grey, LightYellow, SeaGreen, Orange, Purple, SlateBlue, Violet,
*rgb.txt*
-Additionally, colors defined by a "rgb.txt" file can be used. This file is
-well known from X11. A few lines from it: >
-
- 255 218 185 peach puff
- 205 133 63 peru
- 255 181 197 pink
-
-This shows the layout of the file: First the R, G and B value as a decimal
-number, followed by the name of the color. The four fields are separated by
-spaces.
-
-You can get an rgb.txt file from any X11 distribution. It is located in a
-directory like "/usr/X11R6/lib/X11/". For Vim it must be located in the
-$VIMRUNTIME directory. Thus the file can be found with "$VIMRUNTIME/rgb.txt".
+Additionally, colors defined by a default color list can be used. For more
+info see |:colorscheme|. These colors used to be defined in
+$VIMRUNTIME/rgb.txt, now they are in |v:colornames| which is initialized from
+$VIMRUNTIME/colors/lists/default.vim.
==============================================================================
*gui-w32-dialogs* *dialog*
diff --git a/runtime/doc/message.txt b/runtime/doc/message.txt
index 2dc7535..5334ac0 100644
--- a/runtime/doc/message.txt
+++ b/runtime/doc/message.txt
@@ -141,6 +141,11 @@
The color name {name} is unknown. See |gui-colors| for a list of colors that
are available on most systems.
+ *E1244* >
+ Bad color string: {str}
+
+The provided color did not conform to the pattern #rrggbb
+
*E458* >
Cannot allocate colormap entry, some colors may be incorrect
diff --git a/runtime/doc/os_haiku.txt b/runtime/doc/os_haiku.txt
index 5c520b0..a22b99b 100644
--- a/runtime/doc/os_haiku.txt
+++ b/runtime/doc/os_haiku.txt
@@ -194,9 +194,8 @@
11. Color names *haiku-colors*
-Vim has a number of color names built-in. Additional names are read from the
-file $VIMRUNTIME/rgb.txt, if present. This file is basically the color
-database from X. Names used from this file are cached for efficiency.
+Vim has a number of color names built-in. Additional names can be defined in
+|v:colornames|. See |:colorscheme| for details.
12. GUI Toolbar Images *haiku-toolbar-images*
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 1ade9e9..1c20659 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -5143,8 +5143,35 @@
"gg" is the Green value
"bb" is the Blue value
All values are hexadecimal, range from "00" to "ff". Examples: >
- :highlight Comment guifg=#11f0c3 guibg=#ff00ff
+ :highlight Comment guifg=#11f0c3 guibg=#ff00ff
<
+ If you are authoring a color scheme and use the same hexademical value
+ repeatedly, you can define a name for it in |v:colornames|. For
+ example: >
+
+ # provide a default value for this color but allow the user to
+ # override it.
+ :call extend(v:colornames, {'alt_turquoise': '#11f0c3'}, 'keep')
+ :highlight Comment guifg=alt_turquoise guibg=magenta
+<
+ If you are using a color scheme that relies on named colors and you
+ would like to adjust the precise appearance of those colors, you can
+ do so by overriding the values in |v:colornames| prior to loading the
+ scheme: >
+
+ let v:colornames['alt_turquoise'] = '#22f0d3'
+ colorscheme alt
+<
+ If you want to develop a color list that can be relied on by others,
+ it is best to prefix your color names. By convention these color lists
+ are placed in the colors/lists directory. You can see an example in
+ '$VIMRUNTIME/colors/lists/csscolors.vim'. This list would be sourced
+ by a color scheme using: >
+
+ :runtime colors/lists/csscolors.vim
+ :highlight Comment guifg=css_turquoise
+<
+
*highlight-groups* *highlight-default*
These are the default highlighting groups. These groups are used by the
'highlight' option default. Note that the highlighting depends on the value
diff --git a/runtime/doc/usr_06.txt b/runtime/doc/usr_06.txt
index 65d69de..2cf672e 100644
--- a/runtime/doc/usr_06.txt
+++ b/runtime/doc/usr_06.txt
@@ -184,7 +184,30 @@
:runtime syntax/colortest.vim
You will see text in various color combinations. You can check which ones are
-readable and look nice.
+readable and look nice. These aren't the only colors available to you though.
+You can specify #rrggbb hex colors and you can define new names for hex
+colors in |v:colornames| like so: >
+
+ let v:colornames['mine_red'] = '#aa0000'
+<
+If you are authoring a color scheme for others to use, it is important
+to define these colors only when they do not exist: >
+
+ call extend(v:colornames, {'mine_red': '#aa0000'}, 'keep')
+
+This allows users of the color scheme to override the precise definition of
+that color prior to loading your color scheme. For example, in a |.vimrc|
+file:
+
+ runtime colors/lists/css_colors.vim
+ let v:colornames['your_red'] = v:colornames['css_red']
+ colorscheme yourscheme
+
+As a color scheme author, you should be able to rely on some color names for
+GUI colors. These are defined in `colors/lists/default.vim`. All such files
+found on the |runtimepath| are loaded each time the colorscheme command is
+run. A canonical list is provided by the vim distribution, which should
+include all X11 colors (previously defined in rgb.txt).
==============================================================================
*06.4* With colors or without colors