summaryrefslogtreecommitdiffstats
path: root/runtime/doc/textprop.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/textprop.txt')
-rw-r--r--runtime/doc/textprop.txt515
1 files changed, 515 insertions, 0 deletions
diff --git a/runtime/doc/textprop.txt b/runtime/doc/textprop.txt
new file mode 100644
index 0000000..bf7fd16
--- /dev/null
+++ b/runtime/doc/textprop.txt
@@ -0,0 +1,515 @@
+*textprop.txt* For Vim version 9.1. Last change: 2023 Apr 23
+
+
+ VIM REFERENCE MANUAL by Bram Moolenaar
+
+
+Displaying text with properties attached. *textprop* *text-properties*
+
+
+1. Introduction |text-prop-intro|
+2. Functions |text-prop-functions|
+3. When text changes |text-prop-changes|
+
+
+{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
+ "combine" when omitted or TRUE the text property highlighting is
+ combined with any syntax highlighting; when FALSE the
+ text property highlighting replaces the syntax
+ highlighting
+ "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.
+
+
+Internal error *E967*
+
+If you see E967, please report the bug. You can do this at Github:
+https://github.com/vim/vim/issues/new
+
+==============================================================================
+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_add_list({props}, [{item}, ...])
+ add a text property at multiple
+ positions.
+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
+
+ *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:
+ type name of the text property type
+ 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 (inclusive)
+ 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; must be a
+ number, should be positive; when using "text"
+ then "id" must not be present and will be set
+ automatically to a negative number; otherwise
+ zero is used
+ *E1305*
+ text text to be displayed before {col}, or
+ above/below the line if {col} is zero; prepend
+ and/or append spaces for padding with
+ highlighting; cannot be used with "length",
+ "end_lnum" and "end_col"
+ See |virtual-text| for more information.
+ *E1294*
+ text_align when "text" is present and {col} is zero;
+ specifies where to display the text:
+ after after the end of the line
+ right right aligned in the window (unless
+ the text wraps to the next screen
+ line)
+ below in the next screen line
+ above just above the line
+ When omitted "after" is used. Only one
+ "right" property can fit in each line, if
+ there are two or more these will go in a
+ separate line (still right aligned).
+ text_padding_left *E1296*
+ used when "text" is present and {col} is zero;
+ padding between the end of the text line
+ (leftmost column for "above" and "below") and
+ the virtual text, not highlighted
+ text_wrap when "text" is present and {col} is zero,
+ specifies what happens if the text doesn't
+ fit:
+ wrap wrap the text to the next line
+ truncate truncate the text to make it fit
+ When omitted "truncate" is used.
+ Note that this applies to the individual text
+ property, the 'wrap' option sets the overall
+ behavior
+ 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 move with the text, as
+ a kind of mark. One character will be highlighted, if the
+ type specifies highlighting.
+ 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.
+ *virtual-text*
+ When "text" is used and the column is non-zero then this text
+ will be displayed at the specified start location of the text
+ property. The text of the buffer line will be shifted to make
+ room. This is called "virtual text".
+ When the column is zero the virtual text will appear above,
+ after or below the buffer text. The "text_align" and
+ "text_wrap" arguments determine how it is displayed.
+ To separate the virtual text from the buffer text prepend
+ and/or append spaces to the "text" field or use the
+ "text_padding_left" value.
+
+ Make sure to use a highlight that makes clear to the user that
+ this is virtual text, otherwise it will be very confusing that
+ the text cannot be edited. When using "above" you need to
+ make clear this text belongs to the text line below it, when
+ using "below" you need to make sure it belongs to the text
+ line above it.
+
+ The text will be displayed but it is not part of the actual
+ buffer line, the cursor cannot be placed on it. A mouse click
+ in the text will move the cursor to the first character after
+ the text, or the last character of the line.
+ Any Tab and other control character in the text will be
+ changed to a space (Rationale: otherwise the size of the text
+ is difficult to compute).
+ A negative "id" will be chosen and is returned.
+
+ Before text properties with text were supported it was
+ possible to use a negative "id", even though this was very
+ rare. Now that negative "id"s are reserved for text
+ properties with text an error is given when using a negative
+ "id". When a text property with text already exists using a
+ negative "id" results in *E1293* . If a negative "id" was
+ used and later a text property with text is added results in
+ *E1339* .
+
+ Can also be used as a |method|: >
+ GetLnum()->prop_add(col, props)
+<
+ *prop_add_list()*
+prop_add_list({props}, [{item}, ...])
+ Similar to prop_add(), but attaches a text property at
+ multiple positions in a buffer.
+
+ {props} is a dictionary with these fields:
+ bufnr buffer to add the property to; when omitted
+ the current buffer is used
+ id user defined ID for the property; must be a
+ number; when omitted zero is used
+ type name of the text property type
+ All fields except "type" are optional.
+
+ The second argument is a List of items, where each {item} is a
+ list that specifies the starting and ending position of the
+ text: [{lnum}, {col}, {end-lnum}, {end-col}]
+ or: [{lnum}, {col}, {end-lnum}, {end-col}, {id}]
+
+ The first two items {lnum} and {col} specify the starting
+ position of the text where the property will be attached.
+ The next two items {end-lnum} and {end-col} specify the
+ position just after the text.
+ An optional fifth item {id} can be used to give a different ID
+ to a property. When omitted the ID from {props} is used,
+ falling back to zero if none are present.
+
+ It is not possible to add a text property with a "text" field
+ here.
+
+ Example: >
+ call prop_add_list(#{type: 'MyProp', id: 2},
+ \ [[1, 4, 1, 7],
+ \ [1, 15, 1, 20],
+ \ [2, 30, 3, 30]]
+<
+ Can also be used as a |method|: >
+ GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]])
+
+
+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.
+
+ Can also be used as a |method|: >
+ GetLnum()->prop_clear()
+<
+ *prop_find()*
+prop_find({props} [, {direction}])
+ Search for a text property as specified with {props}:
+ id property with this ID
+ type property with this type name
+ both "id" and "type" must both match
+ 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
+
+ A property matches when either "id" or "type" matches.
+ {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.
+
+
+prop_list({lnum} [, {props}]) *prop_list()*
+ Returns a List with all the text properties in line {lnum}.
+
+ The following optional items are supported in {props}:
+ bufnr use this buffer instead of the current buffer
+ end_lnum return text properties in all the lines
+ between {lnum} and {end_lnum} (inclusive).
+ A negative value is used as an offset from the
+ last buffer line; -1 refers to the last buffer
+ line.
+ types List of property type names. Return only text
+ properties that match one of the type names.
+ ids List of property identifiers. Return only text
+ properties with one of these identifiers.
+
+ The properties are ordered by starting column and priority.
+ Each property is a Dict with these entries:
+ lnum starting line number. Present only when
+ returning text properties between {lnum} and
+ {end_lnum}.
+ col starting column
+ length length in bytes, one more if line break is
+ included
+ id property ID
+ text text to be displayed before {col}. Only
+ present for |virtual-text| properties.
+ text_align alignment property of |virtual-text|.
+ text_padding_left
+ left padding used for virtual text.
+ text_wrap specifies whether |virtual-text| is wrapped.
+ type name of the property type, omitted if
+ the type was deleted
+ type_bufnr buffer number for which this type was defined;
+ 0 if the type is global
+ 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.
+
+ Returns an empty list on error.
+
+ Examples:
+ " get text properties placed in line 5
+ echo prop_list(5)
+ " get text properties placed in line 20 in buffer 4
+ echo prop_list(20, {'bufnr': 4})
+ " get all the text properties between line 1 and 20
+ echo prop_list(1, {'end_lnum': 20})
+ " get all the text properties of type 'myprop'
+ echo prop_list(1, {'types': ['myprop'],
+ \ 'end_lnum': -1})
+ " get all the text properties of type 'prop1' or 'prop2'
+ echo prop_list(1, {'types': ['prop1', 'prop2'],
+ \ 'end_lnum': -1})
+ " get all the text properties with ID 8
+ echo prop_list(1, {'ids': [8], 'end_lnum': line('$')})
+ " get all the text properties with ID 10 and 20
+ echo prop_list(1, {'ids': [10, 20], 'end_lnum': -1})
+ " get text properties with type 'myprop' and ID 100
+ " in buffer 4.
+ echo prop_list(1, {'bufnr': 4, 'types': ['myprop'],
+ \ 'ids': [100], 'end_lnum': -1})
+
+ Can also be used as a |method|: >
+ GetLnum()->prop_list()
+<
+ *prop_remove()* *E968* *E860*
+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 (this requires going over all lines, thus will be a
+ bit slow for a buffer with many lines).
+
+ {props} is a dictionary with these fields:
+ id remove text properties with this ID
+ type remove text properties with this type name
+ types remove text properties with type names in this
+ List
+ both "id" and "type"/"types" must both match
+ bufnr use this buffer instead of the current one
+ all when TRUE remove all matching text properties,
+ not just the first one
+ Only one of "type" and "types" may be supplied. *E1295*
+
+ A property matches when either "id" or one of the supplied
+ types 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.
+
+ Can also be used as a |method|: >
+ GetProps()->prop_remove()
+
+
+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. Nothing is returned.
+ {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 omitted or TRUE combine the highlight
+ with any syntax highlight; when FALSE syntax
+ highlight will not be used
+ override when TRUE the highlight overrides any other,
+ including 'cursorline' and Visual
+ 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
+
+ Can also be used as a |method|: >
+ GetPropName()->prop_type_add(props)
+
+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()|.
+
+ Can also be used as a |method|: >
+ GetPropName()->prop_type_change(props)
+
+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.
+
+ Can also be used as a |method|: >
+ GetPropName()->prop_type_delete()
+
+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.
+
+ Can also be used as a |method|: >
+ GetPropName()->prop_type_get()
+
+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.
+
+
+==============================================================================
+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.
+ *E275*
+When a buffer is unloaded, all the text properties are gone. There is no way
+to store the properties in a file. You can only re-create them. When a
+buffer is hidden the text is preserved and so are the text properties. It is
+not possible to add text properties to an unloaded buffer.
+
+When using replace mode, the text properties stay on the same character
+positions, even though the characters themselves change.
+
+To update text properties after the text was changed, install a callback with
+`listener_add()`. E.g, if your plugin does spell checking, you can have the
+callback update spelling mistakes in the changed text. Vim will move the
+properties below the changed text, so that they still highlight the same text,
+thus you don't need to update these.
+
+
+Text property columns are not updated or copied: ~
+
+- When setting the line with |setline()| or through an interface, such as Lua,
+ Tcl or Python. Vim does not know what text got inserted or deleted.
+- With a command like `:move`, which takes a line of text out of context.
+
+
+ vim:tw=78:ts=8:noet:ft=help:norl:
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-02 20:10:24 +0000