diff options
| -rw-r--r-- | runtime/doc/api.txt | 45 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 39 |
2 files changed, 67 insertions, 17 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index b5ec9114de..812208ca31 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1570,18 +1570,46 @@ nvim_set_current_win({window}) *nvim_set_current_win()* nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* Sets a highlight group. - Note: Unlike the `:highlight` command which can update a - highlight group, this function completely replaces the - definition. For example: `nvim_set_hl(0, 'Visual', {})` will - clear the highlight group 'Visual'. + Note: + Unlike the `:highlight` command which can update a + highlight group, this function completely replaces the + definition. For example: `nvim_set_hl(0, 'Visual', {})` + will clear the highlight group 'Visual'. + + Note: + The fg and bg keys also accept the string values `"fg"` or + `"bg"` which act as aliases to the corresponding + foreground and background values of the Normal group. If + the Normal group has not been defined, using these values + results in an error. Parameters: ~ {ns_id} Namespace id for this highlight |nvim_create_namespace()|. Use 0 to set a highlight group globally |:highlight|. {name} Highlight group name, e.g. "ErrorMsg" - {val} Highlight definition map, like |synIDattr()|. In - addition, the following keys are recognized: + {val} Highlight definition map, accepts the following + keys: + • fg (or foreground): color name or "#RRGGBB", + see note. + • bg (or background): color name or "#RRGGBB", + see note. + • sp (or special): color name or "#RRGGBB" + • blend: integer between 0 and 100 + • bold: boolean + • standout: boolean + • underline: boolean + • underlineline: boolean + • undercurl: boolean + • underdot: boolean + • underdash: boolean + • strikethrough: boolean + • italic: boolean + • reverse: boolean + • nocombine: boolean + • link: name of another highlight group to link + to, see |:hi-link|. Additionally, the following + keys are recognized: • default: Don't override existing definition |:hi-default| • ctermfg: Sets foreground of cterm color @@ -1589,8 +1617,9 @@ nvim_set_hl({ns_id}, {name}, {*val}) *nvim_set_hl()* • ctermbg: Sets background of cterm color |highlight-ctermbg| • cterm: cterm attribute map, like - |highlight-args|. Note: Attributes default to - those set for `gui` if not set. + |highlight-args|. If not set, cterm attributes + will match those from the attribute map + documented above. nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts}) *nvim_set_keymap()* Sets a global |mapping| for the given mode. diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index fca86fe440..a257dd6478 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -126,22 +126,43 @@ Dictionary nvim__get_hl_defs(Integer ns_id, Error *err) /// Sets a highlight group. /// -/// Note: Unlike the `:highlight` command which can update a highlight group, -/// this function completely replaces the definition. For example: -/// ``nvim_set_hl(0, 'Visual', {})`` will clear the highlight group 'Visual'. +/// @note Unlike the `:highlight` command which can update a highlight group, +/// this function completely replaces the definition. For example: +/// ``nvim_set_hl(0, 'Visual', {})`` will clear the highlight group +/// 'Visual'. +/// +/// @note The fg and bg keys also accept the string values `"fg"` or `"bg"` +/// which act as aliases to the corresponding foreground and background +/// values of the Normal group. If the Normal group has not been defined, +/// using these values results in an error. /// /// @param ns_id Namespace id for this highlight |nvim_create_namespace()|. /// Use 0 to set a highlight group globally |:highlight|. /// @param name Highlight group name, e.g. "ErrorMsg" -/// @param val Highlight definition map, like |synIDattr()|. In -/// addition, the following keys are recognized: +/// @param val Highlight definition map, accepts the following keys: +/// - fg (or foreground): color name or "#RRGGBB", see note. +/// - bg (or background): color name or "#RRGGBB", see note. +/// - sp (or special): color name or "#RRGGBB" +/// - blend: integer between 0 and 100 +/// - bold: boolean +/// - standout: boolean +/// - underline: boolean +/// - underlineline: boolean +/// - undercurl: boolean +/// - underdot: boolean +/// - underdash: boolean +/// - strikethrough: boolean +/// - italic: boolean +/// - reverse: boolean +/// - nocombine: boolean +/// - link: name of another highlight group to link to, see |:hi-link|. +/// Additionally, the following keys are recognized: /// - default: Don't override existing definition |:hi-default| /// - ctermfg: Sets foreground of cterm color |highlight-ctermfg| /// - ctermbg: Sets background of cterm color |highlight-ctermbg| -/// - cterm: cterm attribute map, like -/// |highlight-args|. -/// Note: Attributes default to those set for `gui` -/// if not set. +/// - cterm: cterm attribute map, like |highlight-args|. If not set, +/// cterm attributes will match those from the attribute map +/// documented above. /// @param[out] err Error details, if any /// // TODO(bfredl): val should take update vs reset flag |