Bram Moolenaar | 68e6560 | 2019-05-26 21:33:31 +0200 | [diff] [blame] | 1 | *textprop.txt* For Vim version 8.1. Last change: 2019 May 12 |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 2 | |
| 3 | |
| 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
| 5 | |
| 6 | |
Bram Moolenaar | a6c27c4 | 2019-05-09 19:16:22 +0200 | [diff] [blame] | 7 | Displaying text with properties attached. *textprop* *text-properties* |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 8 | |
| 9 | THIS IS UNDER DEVELOPMENT - ANYTHING MAY STILL CHANGE *E967* |
| 10 | |
| 11 | What is not working yet: |
| 12 | - Adjusting column/length when inserting text |
| 13 | - Text properties spanning more than one line |
| 14 | - prop_find() |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 15 | |
| 16 | |
| 17 | 1. Introduction |text-prop-intro| |
| 18 | 2. Functions |text-prop-functions| |
Bram Moolenaar | d09091d | 2019-01-17 16:07:22 +0100 | [diff] [blame] | 19 | 3. When text changes |text-prop-changes| |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 20 | |
| 21 | |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 22 | {not able to use text properties when the |+textprop| feature was |
| 23 | disabled at compile time} |
| 24 | |
| 25 | ============================================================================== |
| 26 | 1. Introduction *text-prop-intro* |
| 27 | |
| 28 | Text properties can be attached to text in a buffer. They will move with the |
| 29 | text: If lines are deleted or inserted the properties move with the text they |
| 30 | are attached to. Also when inserting/deleting text in the line before the |
| 31 | text property. And when inserting/deleting text inside the text property, it |
| 32 | will increase/decrease in size. |
| 33 | |
| 34 | The main use for text properties is to highlight text. This can be seen as a |
| 35 | replacement for syntax highlighting. Instead of defining patterns to match |
| 36 | the text, the highlighting is set by a script, possibly using the output of an |
| 37 | external parser. This only needs to be done once, not every time when |
| 38 | redrawing the screen, thus can be much faster, after the initial cost of |
| 39 | attaching the text properties. |
| 40 | |
| 41 | Text properties can also be used for other purposes to identify text. For |
| 42 | example, add a text property on a function name, so that a search can be |
| 43 | defined to jump to the next/previous function. |
| 44 | |
| 45 | A text property is attached at a specific line and column, and has a specified |
| 46 | length. The property can span multiple lines. |
| 47 | |
| 48 | A text property has these fields: |
| 49 | "id" a number to be used as desired |
| 50 | "type" the name of a property type |
| 51 | |
| 52 | |
| 53 | Property Types ~ |
| 54 | *E971* |
| 55 | A text property normally has the name of a property type, which defines |
| 56 | how to highlight the text. The property type can have these entries: |
| 57 | "highlight" name of the highlight group to use |
Bram Moolenaar | de24a87 | 2019-05-05 15:48:00 +0200 | [diff] [blame] | 58 | "combine" when TRUE the text property highlighting is combined |
| 59 | with any syntax highligting, when omitted or FALSE the |
| 60 | text property highlighting replaces the syntax |
| 61 | highlighting |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 62 | "priority" when properties overlap, the one with the highest |
| 63 | priority will be used. |
| 64 | "start_incl" when TRUE inserts at the start position will be |
| 65 | included in the text property |
| 66 | "end_incl" when TRUE inserts at the end position will be |
| 67 | included in the text property |
| 68 | |
| 69 | |
| 70 | Example ~ |
| 71 | |
| 72 | Suppose line 11 in a buffer has this text (excluding the indent): |
| 73 | |
| 74 | The number 123 is smaller than 4567. |
| 75 | |
Bram Moolenaar | 4c05fa0 | 2019-01-01 15:32:17 +0100 | [diff] [blame] | 76 | To highlight the numbers in this text: > |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 77 | call prop_type_add('number', {'highlight': 'Constant'}) |
Bram Moolenaar | 9d87a37 | 2018-12-18 21:41:50 +0100 | [diff] [blame] | 78 | call prop_add(11, 12, {'length': 3, 'type': 'number'}) |
| 79 | call prop_add(11, 32, {'length': 4, 'type': 'number'}) |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 80 | |
Bram Moolenaar | 4c05fa0 | 2019-01-01 15:32:17 +0100 | [diff] [blame] | 81 | Try inserting or deleting lines above the text, you will see that the text |
| 82 | properties stick to the text, thus the line number is adjusted as needed. |
| 83 | |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 84 | Setting "start_incl" and "end_incl" is useful when white space surrounds the |
| 85 | text, e.g. for a function name. Using false is useful when the text starts |
| 86 | and/or ends with a specific character, such as the quote surrounding a string. |
| 87 | |
| 88 | func FuncName(arg) ~ |
| 89 | ^^^^^^^^ property with start_incl and end_incl set |
| 90 | |
| 91 | var = "text"; ~ |
| 92 | ^^^^^^ property with start_incl and end_incl not set |
| 93 | |
| 94 | Nevertheless, when text is inserted or deleted the text may need to be parsed |
Bram Moolenaar | 9d87a37 | 2018-12-18 21:41:50 +0100 | [diff] [blame] | 95 | and the text properties updated. But this can be done asynchronously. |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 96 | |
| 97 | ============================================================================== |
| 98 | 2. Functions *text-prop-functions* |
| 99 | |
| 100 | Manipulating text property types: |
| 101 | |
| 102 | prop_type_add({name}, {props}) define a new property type |
| 103 | prop_type_change({name}, {props}) change an existing property type |
| 104 | prop_type_delete({name} [, {props}]) delete a property type |
| 105 | prop_type_get([{name} [, {props}]) get property type values |
| 106 | prop_type_list([{props}]) get list of property types |
| 107 | |
| 108 | |
| 109 | Manipulating text properties: |
| 110 | |
| 111 | prop_add({lnum}, {col}, {props}) add a text property |
Bram Moolenaar | c8c8849 | 2018-12-27 23:59:26 +0100 | [diff] [blame] | 112 | prop_clear({lnum} [, {lnum-end} [, {bufnr}]]) |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 113 | remove all text properties |
| 114 | prop_find({props} [, {direction}]) search for a text property |
| 115 | prop_list({lnum} [, {props}) text properties in {lnum} |
Bram Moolenaar | c8c8849 | 2018-12-27 23:59:26 +0100 | [diff] [blame] | 116 | prop_remove({props} [, {lnum} [, {lnum-end}]]) |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 117 | remove a text property |
| 118 | |
Bram Moolenaar | d09091d | 2019-01-17 16:07:22 +0100 | [diff] [blame] | 119 | ============================================================================== |
| 120 | 3. When text changes *text-prop-changes* |
| 121 | |
| 122 | Vim will do its best to keep the text properties on the text where it was |
| 123 | attached. When inserting or deleting text the properties after the change |
| 124 | will move accordingly. |
| 125 | |
| 126 | When text is deleted and a text property no longer includes any text, it is |
| 127 | deleted. However, a text property that was defined as zero-width will remain, |
| 128 | unless the whole line is deleted. |
| 129 | |
| 130 | When using replace mode, the text properties stay on the same character |
| 131 | positions, even though the characters themselves change. |
| 132 | |
Bram Moolenaar | 68e6560 | 2019-05-26 21:33:31 +0200 | [diff] [blame] | 133 | To update text properties after the text was changed, install a callback with |
| 134 | `listener_add()`. E.g, if your plugin does spell checking, you can have the |
| 135 | callback update spelling mistakes in the changed text. Vim will move the |
| 136 | properties below the changed text, so that they still highlight the same text, |
| 137 | thus you don't need to update these. |
| 138 | |
Bram Moolenaar | d09091d | 2019-01-17 16:07:22 +0100 | [diff] [blame] | 139 | |
Bram Moolenaar | a6c27c4 | 2019-05-09 19:16:22 +0200 | [diff] [blame] | 140 | Text property columns are not updated: ~ |
Bram Moolenaar | d09091d | 2019-01-17 16:07:22 +0100 | [diff] [blame] | 141 | |
| 142 | - When setting the line with |setline()| or through an interface, such as Lua, |
Bram Moolenaar | a6c27c4 | 2019-05-09 19:16:22 +0200 | [diff] [blame] | 143 | Tcl or Python. Vim does not know what text got inserted or deleted. |
Bram Moolenaar | d09091d | 2019-01-17 16:07:22 +0100 | [diff] [blame] | 144 | |
Bram Moolenaar | 98aefe7 | 2018-12-13 22:20:09 +0100 | [diff] [blame] | 145 | |
| 146 | vim:tw=78:ts=8:noet:ft=help:norl: |