diff options
Diffstat (limited to 'runtime/doc/textprop.txt')
-rw-r--r-- | runtime/doc/textprop.txt | 198 |
1 files changed, 197 insertions, 1 deletions
diff --git a/runtime/doc/textprop.txt b/runtime/doc/textprop.txt index 8beae93556..185a60b2b2 100644 --- a/runtime/doc/textprop.txt +++ b/runtime/doc/textprop.txt @@ -1,4 +1,4 @@ -*textprop.txt* For Vim version 8.1. Last change: 2019 Jun 13 +*textprop.txt* For Vim version 8.1. Last change: 2019 Jul 20 VIM REFERENCE MANUAL by Bram Moolenaar @@ -116,6 +116,202 @@ prop_list({lnum} [, {props}) text properties in {lnum} prop_remove({props} [, {lnum} [, {lnum-end}]]) remove a text property + *prop_add()* *E965* +prop_add({lnum}, {col}, {props}) + Attach a text property at position {lnum}, {col}. {col} is + counted in bytes, 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 bytes, can only be used + for a property that does not continue in + another line; can be zero + end_lnum line number for the end of text + end_col column just after the text; not used when + "length" is present; when {col} and "end_col" + are equal, and "end_lnum" is omitted or equal + to {lnum}, this is a zero-width text property + 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 given. 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" nor "end_col" are given the property + will be zero-width. That means it will not be highlighted but + will move with the text, as a kind of mark. + The property can end exactly at the last character of the + text, or just after it. In the last case, if text is appended + to the line, the text property size will increase, also when + the property type does not have "end_incl" set. + + "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, one more if line break is + included + 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. + If buffer "bufnr" does not exist you get an error message. + If buffer "bufnr" is not loaded then nothing happens. + + 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 + combine when TRUE combine the highlight with any + syntax highlight; when omitted or FALSE syntax + highlight will not 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 + + 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. + + ============================================================================== 3. When text changes *text-prop-changes* |