diff options
author | Bram Moolenaar <Bram@vim.org> | 2018-12-13 22:20:09 +0100 |
---|---|---|
committer | Bram Moolenaar <Bram@vim.org> | 2018-12-13 22:20:09 +0100 |
commit | 98aefe7c3250bb5d4153b994f878594d1745424e (patch) | |
tree | 262ae31c2dbf4ac0353f5564a2419a79267fa3ae /runtime/doc | |
parent | 5c5697f29829fc3b21fc5452fe8f239f6a4cb8e1 (diff) |
patch 8.1.0579: cannot attach properties to textv8.1.0579
Problem: Cannot attach properties to text.
Solution: First part of adding text properties.
Diffstat (limited to 'runtime/doc')
-rw-r--r-- | runtime/doc/Makefile | 2 | ||||
-rw-r--r-- | runtime/doc/eval.txt | 211 | ||||
-rw-r--r-- | runtime/doc/textprop.txt | 114 |
3 files changed, 323 insertions, 4 deletions
diff --git a/runtime/doc/Makefile b/runtime/doc/Makefile index e4b2b5b055..7dbb2bae1a 100644 --- a/runtime/doc/Makefile +++ b/runtime/doc/Makefile @@ -102,6 +102,7 @@ DOCS = \ tagsrch.txt \ term.txt \ terminal.txt \ + textprop.txt \ tips.txt \ todo.txt \ uganda.txt \ @@ -238,6 +239,7 @@ HTMLS = \ tagsrch.html \ term.html \ terminal.html \ + textprop.html \ tips.html \ todo.html \ uganda.html \ diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt index 21fc43aaae..4e80f4a971 100644 --- a/runtime/doc/eval.txt +++ b/runtime/doc/eval.txt @@ -1,4 +1,4 @@ -*eval.txt* For Vim version 8.1. Last change: 2018 Dec 09 +*eval.txt* For Vim version 8.1. Last change: 2018 Dec 13 VIM REFERENCE MANUAL by Bram Moolenaar @@ -1104,7 +1104,7 @@ Or, if you don't want to write them in as floating-point literals, you can also use functions, like the following: > :let pi = acos(-1.0) :let e = exp(1.0) - +< *floating-point-precision* The precision and range of floating points numbers depends on what "double" means in the library Vim was compiled with. There is no way to change this at @@ -2317,6 +2317,22 @@ printf({fmt}, {expr1}...) String format text prompt_setcallback({buf}, {expr}) none set prompt callback function prompt_setinterrupt({buf}, {text}) none set prompt interrupt function prompt_setprompt({buf}, {text}) none set prompt text +prop_add({lnum}, {col}, {props}) none add a text property +prop_clear({lnum} [, {lnum_end} [, {bufnr}]]) + none remove all text properties +prop_find({props} [, {direction}]) + Dict search for a text property +prop_list({lnum} [, {props}) List text properties in {lnum} +prop_remove({props} [, {lnum} [, {lnum_end}]]) + Number remove a text property +prop_type_add({name}, {props}) none define a new property type +prop_type_change({name}, {props}) + none change an existing property type +prop_type_delete({name} [, {props}]) + none delete a property type +prop_type_get([{name} [, {props}]) + Dict get property type values +prop_type_list([{props}]) List get list of property types pumvisible() Number whether popup menu is visible pyeval({expr}) any evaluate |Python| expression py3eval({expr}) any evaluate |python3| expression @@ -3142,8 +3158,9 @@ ch_logfile({fname} [, {mode}]) *ch_logfile()* When {mode} is omitted or "a" append to the file. When {mode} is "w" start with an empty file. - The file is flushed after every message, on Unix you can use - "tail -f" to see what is going on in real time. + Use |ch_log()| to write log messages. The file is flushed + after every message, on Unix you can use "tail -f" to see what + is going on in real time. This function is not available in the |sandbox|. NOTE: the channel communication is stored in the file, be @@ -6656,6 +6673,191 @@ prompt_setprompt({buf}, {text}) *prompt_setprompt()* The result is only visible if {buf} has 'buftype' set to "prompt". Example: > call prompt_setprompt(bufnr(''), 'command: ') +< + *prop_add()* *E965* +prop_add({lnum}, {col}, {props}) + Attach a text property at position {lnum}, {col}. Use one for + the first column. + If {lnum} is invalid an error is given. *E966* + If {col} is invalid an error is given. *E964* + + {props} is a dictionary with these fields: + "length" - length of text in characters, can only be + used for a property that does not + continue in another line + "end_lnum" - line number for end of text + "end_col" - column for end of text; not used when + "length" is present + "bufnr - buffer to add the property to; when + omitted the current buffer is used + "id" - user defined ID for the property; when + omitted zero is used + "type" - name of the text property type + All fields except "type" are optional. + + It is an error when both "length" and "end_lnum" or "end_col" + are passed. Either use "length" or "end_col" for a property + within one line, or use "end_lnum" and "end_col" for a + property that spans more than one line. + When neither "length" or "end_col" are passed the property + will apply to one character. + + "type" will first be looked up in the buffer the property is + added to. When not found, the global property types are used. + If not found an error is given. + + See |text-properties| for information about text properties. + + +prop_clear({lnum} [, {lnum_end} [, {props}]]) *prop_clear()* + Remove all text properties from line {lnum}. + When {lnum_end} is given, remove all text properties from line + {lnum} to {lnum_end} (inclusive). + + When {props} contains a "bufnr" item use this buffer, + otherwise use the current buffer. + + See |text-properties| for information about text properties. + + *prop_find()* +prop_find({props} [, {direction}]) + NOT IMPLEMENTED YET + Search for a text property as specified with {props}: + "id" property with this ID + "type" property with this type name + "bufnr buffer to search in; when present a + start position with "lnum" and "col" + must be given; when omitted the + current buffer is used + "lnum" start in this line (when omitted start + at the cursor) + "col" start at this column (when omitted + and "lnum" is given: use column 1, + otherwise start at the cursor) + "skipstart" do not look for a match at the start + position + + {direction} can be "f" for forward and "b" for backward. When + omitted forward search is performed. + + If a match is found then a Dict is returned with the entries + as with prop_list(), and additionally an "lnum" entry. + If no match is found then an empty Dict is returned. + + See |text-properties| for information about text properties. + + +prop_list({lnum} [, {props}]) *prop_list()* + Return a List with all text properties in line {lnum}. + + When {props} contains a "bufnr" item, use this buffer instead + of the current buffer. + + The properties are ordered by starting column and priority. + Each property is a Dict with these entries: + "col" starting column + "length" length in bytes + "id" property ID + "type" name of the property type, omitted if + the type was deleted + "start" when TRUE property starts in this line + "end" when TRUE property ends in this line + + When "start" is zero the property started in a previous line, + the current one is a continuation. + When "end" is zero the property continues in the next line. + The line break after this line is included. + + See |text-properties| for information about text properties. + + + *prop_remove()* *E968* +prop_remove({props} [, {lnum} [, {lnum_end}]]) + Remove a matching text property from line {lnum}. When + {lnum_end} is given, remove matching text properties from line + {lnum} to {lnum_end} (inclusive). + When {lnum} is omitted remove matching text properties from + all lines. + + {props} is a dictionary with these fields: + "id" - remove text properties with this ID + "type" - remove text properties with this type name + "bufnr" - use this buffer instead of the current one + "all" - when TRUE remove all matching text + properties, not just the first one + A property matches when either "id" or "type" matches. + + Returns the number of properties that were removed. + + See |text-properties| for information about text properties. + + +prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970* + Add a text property type {name}. If a property type with this + name already exists an error is given. + {props} is a dictionary with these optional fields: + "bufnr" - define the property only for this + buffer; this avoids name collisions and + automatically clears the property types + when the buffer is deleted. + "highlight" - name of highlight group to use + "priority" - when a character has multiple text + properties the one with the highest + priority will be used; negative values + can be used, the default priority is + zero + "start_incl" - when TRUE inserts at the start + position will be included in the text + property + "end_incl" - when TRUE inserts at the end + position will be included in the text + property + + See |text-properties| for information about text properties. + + +prop_type_change({name}, {props}) *prop_type_change()* + Change properties of an existing text property type. If a + property with this name does not exist an error is given. + The {props} argument is just like |prop_type_add()|. + + See |text-properties| for information about text properties. + + +prop_type_delete({name} [, {props}]) *prop_type_delete()* + Remove the text property type {name}. When text properties + using the type {name} are still in place, they will not have + an effect and can no longer be removed by name. + + {props} can contain a "bufnr" item. When it is given, delete + a property type from this buffer instead of from the global + property types. + + When text property type {name} is not found there is no error. + + See |text-properties| for information about text properties. + + +prop_type_get([{name} [, {props}]) *prop_type_get()* + Returns the properties of property type {name}. This is a + dictionary with the same fields as was given to + prop_type_add(). + When the property type {name} does not exist, an empty + dictionary is returned. + + {props} can contain a "bufnr" item. When it is given, use + this buffer instead of the global property types. + + See |text-properties| for information about text properties. + + +prop_type_list([{props}]) *prop_type_list()* + Returns a list with all property type names. + + {props} can contain a "bufnr" item. When it is given, use + this buffer instead of the global property types. + + See |text-properties| for information about text properties. pumvisible() *pumvisible()* @@ -9609,6 +9811,7 @@ terminal Compiled with |terminal| support. terminfo Compiled with terminfo instead of termcap. termresponse Compiled with support for |t_RV| and |v:termresponse|. textobjects Compiled with support for |text-objects|. +textprop Compiled with support for |text-properties|. tgetent Compiled with tgetent support, able to use a termcap or terminfo file. timers Compiled with |timer_start()| support. diff --git a/runtime/doc/textprop.txt b/runtime/doc/textprop.txt new file mode 100644 index 0000000000..c88ca37b8c --- /dev/null +++ b/runtime/doc/textprop.txt @@ -0,0 +1,114 @@ +*textprop.txt* For Vim version 8.1. Last change: 2018 Dec 13 + + + VIM REFERENCE MANUAL by Bram Moolenaar + + +Displaying text with properties attached. *text-properties* + +THIS IS UNDER DEVELOPMENT - ANYTHING MAY STILL CHANGE *E967* + +What is not working yet: +- Adjusting column/length when inserting text +- Text properties spanning more than one line +- prop_find() +- callbacks when text properties are outdated + + +1. Introduction |text-prop-intro| +2. Functions |text-prop-functions| + + +{Vi does not have text properties} +{not able to use text properties when the |+textprop| feature was +disabled at compile time} + +============================================================================== +1. Introduction *text-prop-intro* + +Text properties can be attached to text in a buffer. They will move with the +text: If lines are deleted or inserted the properties move with the text they +are attached to. Also when inserting/deleting text in the line before the +text property. And when inserting/deleting text inside the text property, it +will increase/decrease in size. + +The main use for text properties is to highlight text. This can be seen as a +replacement for syntax highlighting. Instead of defining patterns to match +the text, the highlighting is set by a script, possibly using the output of an +external parser. This only needs to be done once, not every time when +redrawing the screen, thus can be much faster, after the initial cost of +attaching the text properties. + +Text properties can also be used for other purposes to identify text. For +example, add a text property on a function name, so that a search can be +defined to jump to the next/previous function. + +A text property is attached at a specific line and column, and has a specified +length. The property can span multiple lines. + +A text property has these fields: + "id" a number to be used as desired + "type" the name of a property type + + +Property Types ~ + *E971* +A text property normally has the name of a property type, which defines +how to highlight the text. The property type can have these entries: + "highlight" name of the highlight group to use + "priority" when properties overlap, the one with the highest + priority will be used. + "start_incl" when TRUE inserts at the start position will be + included in the text property + "end_incl" when TRUE inserts at the end position will be + included in the text property + + +Example ~ + +Suppose line 11 in a buffer has this text (excluding the indent): + + The number 123 is smaller than 4567. + +To highlight the numbers: > + call prop_type_add('number', {'highlight': 'Constant'}) + call prop_add(11, 12, {'length': 3, 'type': 'number}) + call prop_add(11, 32, {'length': 4, 'type': 'number}) + +Setting "start_incl" and "end_incl" is useful when white space surrounds the +text, e.g. for a function name. Using false is useful when the text starts +and/or ends with a specific character, such as the quote surrounding a string. + + func FuncName(arg) ~ + ^^^^^^^^ property with start_incl and end_incl set + + var = "text"; ~ + ^^^^^^ property with start_incl and end_incl not set + +Nevertheless, when text is inserted or deleted the text may need to be parsed +and the text properties updated. But this can be done asynchrnously. + +============================================================================== +2. Functions *text-prop-functions* + +Manipulating text property types: + +prop_type_add({name}, {props}) define a new property type +prop_type_change({name}, {props}) change an existing property type +prop_type_delete({name} [, {props}]) delete a property type +prop_type_get([{name} [, {props}]) get property type values +prop_type_list([{props}]) get list of property types + + +Manipulating text properties: + +prop_add({lnum}, {col}, {props}) add a text property +prop_clear({lnum} [, {lnum_end} [, {bufnr}]]) + remove all text properties +prop_find({props} [, {direction}]) search for a text property +prop_list({lnum} [, {props}) text properties in {lnum} +prop_remove({props} [, {lnum} [, {lnum_end}]]) + remove a text property + + + vim:tw=78:ts=8:noet:ft=help:norl: |