diff options
Diffstat (limited to '')
| -rw-r--r-- | runtime/doc/textprop.txt | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/runtime/doc/textprop.txt b/runtime/doc/textprop.txt new file mode 100644 index 0000000..3752551 --- /dev/null +++ b/runtime/doc/textprop.txt @@ -0,0 +1,138 @@ +*textprop.txt* For Vim version 8.1. Last change: 2019 Jan 08 + + + 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| +3. When text changes |text-prop-changes| + + +{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 in this text: > + 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'}) + +Try inserting or deleting lines above the text, you will see that the text +properties stick to the text, thus the line number is adjusted as needed. + +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 asynchronously. + +============================================================================== +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 + +============================================================================== +3. When text changes *text-prop-changes* + +Vim will do its best to keep the text properties on the text where it was +attached. When inserting or deleting text the properties after the change +will move accordingly. + +When text is deleted and a text property no longer includes any text, it is +deleted. However, a text property that was defined as zero-width will remain, +unless the whole line is deleted. + +When using replace mode, the text properties stay on the same character +positions, even though the characters themselves change. + + +When text property columns are not updated ~ + +- When setting the line with |setline()| or through an interface, such as Lua, + Tcl or Python. + + + vim:tw=78:ts=8:noet:ft=help:norl: |