diff options
author | Yegappan Lakshmanan <yegappan@yahoo.com> | 2021-11-03 21:56:45 +0000 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2021-11-03 21:56:45 +0000 |
commit | d1a8d658e1b16cf8579fc72cf7aa6a29a57ff5ef (patch) | |
tree | 76bdb7aa3e539c8f3c35fa288386243511f8c5ed /runtime | |
parent | 0f0044125c2a5dcde2c4605efc39d2e237eed024 (diff) |
patch 8.2.3578: manipulating highlighting is complicatedv8.2.3578
Problem: Manipulating highlighting is complicated.
Solution: Add the hlget() and hlset() functions. (Yegappan Lakshmanan,
closes #9039)
Diffstat (limited to 'runtime')
-rw-r--r-- | runtime/doc/eval.txt | 89 | ||||
-rw-r--r-- | runtime/doc/syntax.txt | 1 | ||||
-rw-r--r-- | runtime/doc/usr_41.txt | 2 | ||||
-rw-r--r-- | runtime/doc/windows.txt | 1 |
4 files changed, 93 insertions, 0 deletions
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 418aee9ceb..2bd953a430 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -2718,6 +2718,8 @@ histget({history} [, {index}]) String get the item {index} from a history histnr({history}) Number highest index of a history hlID({name}) Number syntax ID of highlight group {name} hlexists({name}) Number |TRUE| if highlight group {name} exists +hlget([{name} [, {resolve}]]) List get highlight group attributes +hlset({list}) Number set highlight group attributes hostname() String name of the machine Vim is running on iconv({expr}, {from}, {to}) String convert encoding of {expr} indent({lnum}) Number indent of line {lnum} @@ -6717,6 +6719,93 @@ hlexists({name}) *hlexists()* Can also be used as a |method|: > GetName()->hlexists() < +hlget([{name} [, {resolve}]]) *hlget()* + Returns a List of all the highlight group attributes. If the + optional {name} is specified, then returns a List with only + the attributes of the specified highlight group. Returns an + empty List if the highlight group {name} is not present. + + If the optional {resolve} argument is set to v:true and the + highlight group {name} is linked to another group, then the + link is resolved recursively and the attributes of the + resolved highlight group are returned. + + Each entry in the returned List is a Dictionary with the + following items: + cleared Boolean flag, set to v:true if the highlight + group attributes are cleared or not yet + specified. See |highlight-clear|. + cterm cterm attributes. See |highlight-cterm|. + ctermbg cterm background color. + See |highlight-ctermbg|. + ctermfg cterm foreground color. + See |highlight-ctermfg|. + ctermul cterm underline color. See |highlight-ctermul|. + font highlight group font. See |highlight-font|. + gui gui attributes. See |highlight-gui|. + guibg gui background color. See |highlight-guibg|. + guifg gui foreground color. See |highlight-guifg|. + guisp gui special color. See |highlight-guisp|. + id highlight group ID. + linksto linked highlight group name. + See |:highlight-link|. + name highlight group name. See |group-name|. + start start terminal keycode. See |highlight-start|. + stop stop terminal keycode. See |highlight-stop|. + term term attributes. See |highlight-term|. + + The 'term', 'cterm' and 'gui' items in the above Dictionary + have a dictionary value with the following optional boolean + items: 'bold', 'standout', 'underline', 'undercurl', 'italic', + 'reverse', 'inverse' and 'strikethrough'. + + Example(s): > + :echo hlget() + :echo hlget('ModeMsg') + :echo hlget('Number', v:true) +< + Can also be used as a |method|: > + GetName()->hlget() +< +hlset({list}) *hlset()* + Creates or modifies the attributes of a List of highlight + groups. Each item in {list} is a dictionary containing the + attributes of a highlight group. See |hlget()| for the list of + supported items in this dictionary. + + The highlight group is identified using the 'name' item and + the 'id' item (if supplied) is ignored. If a highlight group + with a specified name doesn't exist, then it is created. + Otherwise the attributes of an existing highlight group are + modified. + + If an empty dictionary value is used for the 'term' or 'cterm' + or 'gui' entries, then the corresponding attributes are + cleared. If the 'cleared' item is set to v:true, then all the + attributes of the highlight group are cleared. + + The 'linksto' item can be used to link a highlight group to + another highlight group. See |:highlight-link|. + + Returns zero for success, -1 for failure. + + Example(s): > + " add bold attribute to the Visual highlight group + :call hlset([#{name: 'Visual', + \ term: #{reverse: 1 , bold: 1}}]) + :call hlset([#{name: 'Type', guifg: 'DarkGreen'}]) + :let l = hlget() + :call hlset(l) + " clear the Search highlight group + :call hlset([#{name: 'Search', cleared: v:true}]) + " clear the 'term' attributes for a highlight group + :call hlset([#{name: 'Title', term: {}}]) + " create the MyHlg group linking it to DiffAdd + :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}]) +< + Can also be used as a |method|: > + GetAttrList()->hlset() +< *hlID()* hlID({name}) The result is a Number, which is the ID of the highlight group with name {name}. When the highlight group doesn't exist, diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt index 1c20659acf..9d4ea39ec7 100644 --- a/runtime/doc/syntax.txt +++ b/runtime/doc/syntax.txt @@ -4849,6 +4849,7 @@ in their own color. :hi[ghlight] {group-name} List one highlight group. + *highlight-clear* :hi[ghlight] clear Reset all highlighting to the defaults. Removes all highlighting for groups added by the user! Uses the current value of 'background' to decide which diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt index 4ea51f986c..89bd542825 100644 --- a/runtime/doc/usr_41.txt +++ b/runtime/doc/usr_41.txt @@ -925,6 +925,8 @@ Syntax and highlighting: *syntax-functions* *highlighting-functions* getmatches() get all matches defined by |matchadd()| and the |:match| commands hlexists() check if a highlight group exists + hlget() get highlight group attributes + hlset() set highlight group attributes hlID() get ID of a highlight group synID() get syntax ID at a specific position synIDattr() get a specific attribute of a syntax ID diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index cd39dac975..c288377caa 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -1358,6 +1358,7 @@ directory Displays directory contents. Can be used by a file explorer < The buffer name is the name of the directory and is adjusted when using the |:cd| command. + *scratch-buffer* scratch Contains text that can be discarded at any time. It is kept when closing the window, it must be deleted explicitly. Settings: > |