vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

textprop.txt (20834B)


      1 *textprop.txt*	For Vim version 9.2.  Last change: 2026 May 31
      2 
      3 
      4 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
      5 
      6 
      7 Displaying text with properties attached.	*textprop* *text-properties*
      8 
      9 
     10 1. Introduction			|text-prop-intro|
     11 2. Functions			|text-prop-functions|
     12 3. When text changes		|text-prop-changes|
     13 
     14 
     15 {not able to use text properties when the |+textprop| feature was
     16 disabled at compile time}
     17 
     18 ==============================================================================
     19 1. Introduction						*text-prop-intro*
     20 
     21 Text properties can be attached to text in a buffer.  They will move with the
     22 text: If lines are deleted or inserted the properties move with the text they
     23 are attached to.  Also when inserting/deleting text in the line before the
     24 text property.  And when inserting/deleting text inside the text property, it
     25 will increase/decrease in size.
     26 
     27 The main use for text properties is to highlight text.  This can be seen as a
     28 replacement for syntax highlighting.  Instead of defining patterns to match
     29 the text, the highlighting is set by a script, possibly using the output of an
     30 external parser.  This only needs to be done once, not every time when
     31 redrawing the screen, thus can be much faster, after the initial cost of
     32 attaching the text properties.
     33 
     34 Text properties can also be used for other purposes to identify text.  For
     35 example, add a text property on a function name, so that a search can be
     36 defined to jump to the next/previous function.
     37 
     38 A text property is attached at a specific line and column, and has a specified
     39 length.  The property can span multiple lines.
     40 
     41 A text property has these fields:
     42 	"id"		a number to be used as desired
     43 	"type"		the name of a property type
     44 
     45 
     46 Property Types ~
     47 							*E971*
     48 A text property normally has the name of a property type, which defines
     49 how to highlight the text.  The property type can have these entries:
     50 	"highlight"	name of the highlight group to use
     51 	"combine"	when omitted or TRUE the text property highlighting is
     52 			combined with any syntax highlighting; when FALSE the
     53 			text property highlighting replaces the syntax
     54 			highlighting
     55 	"priority"	when properties overlap, the one with the highest
     56 			priority will be used.
     57 	"start_incl"	when TRUE inserts at the start position will be
     58 			included in the text property
     59 	"end_incl"	when TRUE inserts at the end position will be
     60 			included in the text property
     61 
     62 
     63 Example ~
     64 
     65 Suppose line 11 in a buffer has this text (excluding the indent):
     66 
     67 	The number 123 is smaller than 4567.
     68 
     69 To highlight the numbers in this text: >
     70 	call prop_type_add('number', {'highlight': 'Constant'})
     71 	call prop_add(11, 12, {'length': 3, 'type': 'number'})
     72 	call prop_add(11, 32, {'length': 4, 'type': 'number'})
     73 
     74 Try inserting or deleting lines above the text, you will see that the text
     75 properties stick to the text, thus the line number is adjusted as needed.
     76 
     77 Setting "start_incl" and "end_incl" is useful when white space surrounds the
     78 text, e.g. for a function name.  Using false is useful when the text starts
     79 and/or ends with a specific character, such as the quote surrounding a string.
     80 
     81 	func FuncName(arg) ~
     82 	     ^^^^^^^^        property with start_incl and end_incl set
     83 
     84 	var = "text"; ~
     85 	      ^^^^^^	     property with start_incl and end_incl not set
     86 
     87 Nevertheless, when text is inserted or deleted the text may need to be parsed
     88 and the text properties updated.  But this can be done asynchronously.
     89 
     90 
     91 Internal error *E967*
     92 
     93 If you see E967, please report the bug.  You can do this at Github:
     94 https://github.com/vim/vim/issues/new
     95 
     96 ==============================================================================
     97 2. Functions						*text-prop-functions*
     98 
     99 Manipulating text property types:
    100 
    101 prop_type_add({name}, {props})		define a new property type
    102 prop_type_change({name}, {props})	change an existing property type
    103 prop_type_delete({name} [, {props}])	delete a property type
    104 prop_type_get({name} [, {props}])	get property type values
    105 prop_type_list([{props}])		get list of property types
    106 
    107 
    108 Manipulating text properties:
    109 
    110 prop_add({lnum}, {col}, {props})	add a text property
    111 prop_add_list({props}, [{item}, ...])
    112 					add a text property at multiple
    113 					positions.
    114 prop_clear({lnum} [, {lnum-end} [, {bufnr}]])
    115 					remove all text properties
    116 prop_find({props} [, {direction}])	search for a text property
    117 prop_list({lnum} [, {props}])		text properties in {lnum}
    118 prop_remove({props} [, {lnum} [, {lnum-end}]])
    119 					remove a text property
    120 
    121 						*text-prop-functions-details*
    122 
    123 						*prop_add()* *E965*
    124 prop_add({lnum}, {col}, {props})
    125 		Attach a text property at position {lnum}, {col}.  {col} is
    126 		counted in bytes, use one for the first column.
    127 		If {lnum} is invalid an error is given. *E966*
    128 		If {col} is invalid an error is given. *E964*
    129 
    130 		{props} is a dictionary with these fields:
    131 		   type		name of the text property type
    132 		   length	length of text in bytes, can only be used
    133 				for a property that does not continue in
    134 				another line; can be zero
    135 		   end_lnum	line number for the end of text (inclusive)
    136 		   end_col	column just after the text; not used when
    137 				"length" is present; when {col} and "end_col"
    138 				are equal, and "end_lnum" is omitted or equal
    139 				to {lnum}, this is a zero-width text property
    140 		   bufnr	buffer to add the property to; when omitted
    141 				the current buffer is used
    142 		   id		user defined ID for the property; must be a
    143 				number, should be positive |E1510|;
    144 				when using "text" then any "id" value is
    145 				ignored and a negative number is assigned
    146 				automatically; otherwise zero is used
    147 							*E1305*
    148 		   text		text to be displayed before {col}, or
    149 				above/below the line if {col} is zero; prepend
    150 				and/or append spaces for padding with
    151 				highlighting; cannot be used with "length",
    152 				"end_lnum" and "end_col"
    153 				See |virtual-text| for more information.
    154 							*E1294*
    155 		   text_align	when "text" is present and {col} is zero;
    156 				specifies where to display the text:
    157 				   after   after the end of the line
    158 				   right   right aligned in the window (unless
    159 					   the text wraps to the next screen
    160 					   line)
    161 				   below   in the next screen line
    162 				   above   just above the line
    163 				When omitted "after" is used.  Only one
    164 				"right" property can fit in each line, if
    165 				there are two or more these will go in a
    166 				separate line (still right aligned).
    167 		   text_padding_left				*E1296*
    168 				used when "text" is present and {col} is zero;
    169 				padding between the end of the text line
    170 				(leftmost column for "above" and "below") and
    171 				the virtual text, not highlighted
    172 		   text_wrap	when "text" is present and {col} is zero,
    173 				specifies what happens if the text doesn't
    174 				fit:
    175 				   wrap      wrap the text to the next line
    176 				   truncate  truncate the text to make it fit
    177 				When omitted "truncate" is used.
    178 				Note that this applies to the individual text
    179 				property, the 'wrap' option sets the overall
    180 				behavior.  "wrap" only takes effect when the
    181 				'wrap' option is set; with 'nowrap' the text
    182 				is truncated at the right edge of the window.
    183 		All fields except "type" are optional.
    184 
    185 		It is an error when both "length" and "end_lnum" or "end_col"
    186 		are given.  Either use "length" or "end_col" for a property
    187 		within one line, or use "end_lnum" and "end_col" for a
    188 		property that spans more than one line.
    189 		When neither "length" nor "end_col" are given the property
    190 		will be zero-width.  That means it will move with the text, as
    191 		a kind of mark.  One character will be highlighted, if the
    192 		type specifies highlighting.
    193 		The property can end exactly at the last character of the
    194 		text, or just after it.  In the last case, if text is appended
    195 		to the line, the text property size will increase, also when
    196 		the property type does not have "end_incl" set.
    197 
    198 		"type" will first be looked up in the buffer the property is
    199 		added to.  When not found, the global property types are used.
    200 		If not found an error is given.
    201 							*virtual-text*
    202 		When "text" is used and the column is non-zero then this text
    203 		will be displayed at the specified start location of the text
    204 		property.  The text of the buffer line will be shifted to make
    205 		room.  This is called "virtual text".
    206 		When the column is zero the virtual text will appear above,
    207 		after or below the buffer text.  The "text_align" and
    208 		"text_wrap" arguments determine how it is displayed.
    209 		To separate the virtual text from the buffer text prepend
    210 		and/or append spaces to the "text" field or use the
    211 		"text_padding_left" value.
    212 
    213 		Make sure to use a highlight that makes clear to the user that
    214 		this is virtual text, otherwise it will be very confusing that
    215 		the text cannot be edited.  When using "above" you need to
    216 		make clear this text belongs to the text line below it, when
    217 		using "below" you need to make sure it belongs to the text
    218 		line above it.
    219 
    220 		The text will be displayed but it is not part of the actual
    221 		buffer line, the cursor cannot be placed on it.  A mouse click
    222 		in the text will move the cursor to the first character after
    223 		the text, or the last character of the line.
    224 		Any Tab and other control character in the text will be
    225 		changed to a space (Rationale: otherwise the size of the text
    226 		is difficult to compute).
    227 		A negative "id" will be chosen and is returned.
    228 
    229 		Negative "id"s are reserved for text properties with "text"
    230 		and cannot be used otherwise.  Using a negative "id" results
    231 		in *E1293* .
    232 
    233 		Can also be used as a |method|: >
    234 			GetLnum()->prop_add(col, props)
    235 <
    236 		Return type: |Number|
    237 
    238 
    239 prop_add_list({props}, [{item}, ...])			*prop_add_list()*
    240 		Similar to prop_add(), but attaches a text property at
    241 		multiple positions in a buffer.
    242 
    243 		{props} is a dictionary with these fields:
    244 		   bufnr	buffer to add the property to; when omitted
    245 				the current buffer is used
    246 		   id		user defined ID for the property; must be a
    247 				number; when omitted zero is used
    248 		   type		name of the text property type
    249 		All fields except "type" are optional.
    250 
    251 		The second argument is a List of items, where each {item} is a
    252 		list that specifies the starting and ending position of the
    253 		text: [{lnum}, {col}, {end-lnum}, {end-col}]
    254 		or:   [{lnum}, {col}, {end-lnum}, {end-col}, {id}]
    255 
    256 		The first two items {lnum} and {col} specify the starting
    257 		position of the text where the property will be attached.
    258 		The next two items {end-lnum} and {end-col} specify the
    259 		position just after the text.
    260 		An optional fifth item {id} can be used to give a different ID
    261 		to a property.  When omitted the ID from {props} is used,
    262 		falling back to zero if none are present.
    263 
    264 		It is not possible to add a text property with a "text" field
    265 		here.
    266 
    267 		Example: >
    268 			call prop_add_list(#{type: 'MyProp', id: 2},
    269 					\ [[1, 4, 1, 7],
    270 					\  [1, 15, 1, 20],
    271 					\  [2, 30, 3, 30]])
    272 <
    273 		Can also be used as a |method|: >
    274 			GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]])
    275 <
    276 		Return type: void
    277 
    278 
    279 prop_clear({lnum} [, {lnum-end} [, {props}]])		*prop_clear()*
    280 		Remove all text properties from line {lnum}.
    281 		When {lnum-end} is given, remove all text properties from line
    282 		{lnum} to {lnum-end} (inclusive).
    283 
    284 		When {props} contains a "bufnr" item use this buffer,
    285 		otherwise use the current buffer.
    286 
    287 		Can also be used as a |method|: >
    288 			GetLnum()->prop_clear()
    289 <
    290 		Return type: void
    291 
    292 
    293 prop_find({props} [, {direction}])			*prop_find()*
    294 		Search for a text property as specified with {props}:
    295 		   id		property with this ID
    296 		   type		property with this type name
    297 		   both		"id" and "type" must both match
    298 		   bufnr	buffer to search in; when present a
    299 				start position with "lnum" and "col"
    300 				must be given; when omitted the
    301 				current buffer is used
    302 		   lnum		start in this line (when omitted start
    303 				at the cursor)
    304 		   col		start at this column (when omitted
    305 				and "lnum" is given: use column 1,
    306 				otherwise start at the cursor)
    307 		   skipstart	do not look for a match at the start
    308 				position
    309 
    310 		A property matches when either "id" or "type" matches.
    311 		{direction} can be "f" for forward and "b" for backward.  When
    312 		omitted forward search is performed.
    313 
    314 		If a match is found then a Dict is returned with the entries
    315 		as with prop_list(), and additionally an "lnum" entry.
    316 		If no match is found then an empty Dict is returned.
    317 
    318 		Return type: dict<any>
    319 
    320 
    321 prop_list({lnum} [, {props}])				*prop_list()*
    322 		Returns a List with all the text properties in line {lnum}.
    323 
    324 		The following optional items are supported in {props}:
    325 		   bufnr	use this buffer instead of the current buffer
    326 		   end_lnum	return text properties in all the lines
    327 				between {lnum} and {end_lnum} (inclusive).
    328 				A negative value is used as an offset from the
    329 				last buffer line; -1 refers to the last buffer
    330 				line.
    331 		   types	List of property type names.  Return only text
    332 				properties that match one of the type names.
    333 		   ids		List of property identifiers.  Return only
    334 				text properties with one of these identifiers.
    335 
    336 		The properties are ordered by starting column and priority.
    337 		Each property is a Dict with these entries:
    338 		   lnum		starting line number.  Present only when
    339 				returning text properties between {lnum} and
    340 				{end_lnum}.
    341 		   col		starting column
    342 		   length	length in bytes, one more if line break is
    343 				included
    344 		   id		property ID
    345 		   text		text to be displayed before {col}.  Only
    346 				present for |virtual-text| properties.
    347 		   text_align	alignment property of |virtual-text|.
    348 		   text_padding_left
    349 				left padding used for virtual text.
    350 		   text_wrap	specifies whether |virtual-text| is wrapped.
    351 		   type		name of the property type, omitted if
    352 				the type was deleted
    353 		   type_bufnr	buffer number for which this type was defined;
    354 				0 if the type is global
    355 		   start	when TRUE property starts in this line
    356 		   end		when TRUE property ends in this line
    357 
    358 		When "start" is zero the property started in a previous line,
    359 		the current one is a continuation.
    360 		When "end" is zero the property continues in the next line.
    361 		The line break after this line is included.
    362 
    363 		Returns an empty list on error.
    364 
    365 		Examples: >
    366 		   " get text properties placed in line 5
    367 		   echo prop_list(5)
    368 		   " get text properties placed in line 20 in buffer 4
    369 		   echo prop_list(20, {'bufnr': 4})
    370 		   " get all the text properties between line 1 and 20
    371 		   echo prop_list(1, {'end_lnum': 20})
    372 		   " get all the text properties of type 'myprop'
    373 		   echo prop_list(1, {'types': ['myprop'],
    374 						\ 'end_lnum': -1})
    375 		   " get all the text properties of type 'prop1' or 'prop2'
    376 		   echo prop_list(1, {'types': ['prop1', 'prop2'],
    377 						\ 'end_lnum': -1})
    378 		   " get all the text properties with ID 8
    379 		   echo prop_list(1, {'ids': [8], 'end_lnum': line('$')})
    380 		   " get all the text properties with ID 10 and 20
    381 		   echo prop_list(1, {'ids': [10, 20], 'end_lnum': -1})
    382 		   " get text properties with type 'myprop' and ID 100
    383 		   " in buffer 4.
    384 		   echo prop_list(1, {'bufnr': 4, 'types': ['myprop'],
    385 					\ 'ids': [100], 'end_lnum': -1})
    386 <
    387 		Can also be used as a |method|: >
    388 			GetLnum()->prop_list()
    389 <
    390 		Return type: list<dict<any>> or list<any>
    391 
    392 						*prop_remove()* *E968* *E860*
    393 prop_remove({props} [, {lnum} [, {lnum-end}]])
    394 		Remove a matching text property from line {lnum}.  When
    395 		{lnum-end} is given, remove matching text properties from line
    396 		{lnum} to {lnum-end} (inclusive).
    397 		When {lnum} is omitted remove matching text properties from
    398 		all lines (this requires going over all lines, thus will be a
    399 		bit slow for a buffer with many lines).
    400 
    401 		{props} is a dictionary with these fields:
    402 		   id		remove text properties with this ID
    403 		   type		remove text properties with this type name
    404 		   types	remove text properties with type names in this
    405 				List
    406 		   both		"id" and "type"/"types" must both match
    407 		   bufnr	use this buffer instead of the current one
    408 		   all		when TRUE remove all matching text properties,
    409 				not just the first one
    410 		Only one of "type" and "types" may be supplied. *E1295*
    411 
    412 		A property matches when either "id" or one of the supplied
    413 		types matches.
    414 		If buffer "bufnr" does not exist you get an error message.
    415 		If buffer "bufnr" is not loaded then nothing happens.
    416 
    417 		Returns the number of properties that were removed.
    418 
    419 		Can also be used as a |method|: >
    420 			GetProps()->prop_remove()
    421 <
    422 		Return type: |Number|
    423 
    424 
    425 prop_type_add({name}, {props})		*prop_type_add()* *E969* *E970*
    426 		Add a text property type {name}.  If a property type with this
    427 		name already exists an error is given.  Nothing is returned.
    428 		{props} is a dictionary with these optional fields:
    429 		   bufnr	define the property only for this buffer; this
    430 				avoids name collisions and automatically
    431 				clears the property types when the buffer is
    432 				deleted.
    433 		   highlight	name of highlight group to use
    434 		   priority	when a character has multiple text
    435 				properties the one with the highest priority
    436 				will be used; negative values can be used, the
    437 				default priority is zero
    438 		   combine	when omitted or TRUE combine the highlight
    439 				with any syntax highlight; when FALSE syntax
    440 				highlight will not be used
    441 		   override	when TRUE the highlight overrides any other,
    442 				including 'cursorline' and Visual
    443 		   start_incl	when TRUE inserts at the start position will
    444 				be included in the text property
    445 		   end_incl	when TRUE inserts at the end position will be
    446 				included in the text property
    447 
    448 		Can also be used as a |method|: >
    449 			GetPropName()->prop_type_add(props)
    450 <
    451 		Return type: void
    452 
    453 
    454 prop_type_change({name}, {props})			*prop_type_change()*
    455 		Change properties of an existing text property type.  If a
    456 		property with this name does not exist an error is given.
    457 		The {props} argument is just like |prop_type_add()|.
    458 
    459 		Can also be used as a |method|: >
    460 			GetPropName()->prop_type_change(props)
    461 <
    462 		Return type: void
    463 
    464 
    465 prop_type_delete({name} [, {props}])			*prop_type_delete()*
    466 		Remove the text property type {name}.  When text properties
    467 		using the type {name} are still in place, they will not have
    468 		an effect and can no longer be removed by name.
    469 
    470 		{props} can contain a "bufnr" item.  When it is given, delete
    471 		a property type from this buffer instead of from the global
    472 		property types.
    473 
    474 		When text property type {name} is not found there is no error.
    475 
    476 		Can also be used as a |method|: >
    477 			GetPropName()->prop_type_delete()
    478 <
    479 		Return type: void
    480 
    481 
    482 prop_type_get({name} [, {props}])			*prop_type_get()*
    483 		Returns the properties of property type {name}.  This is a
    484 		dictionary with the same fields as was given to
    485 		prop_type_add().
    486 		When the property type {name} does not exist, an empty
    487 		dictionary is returned.
    488 
    489 		{props} can contain a "bufnr" item.  When it is given, use
    490 		this buffer instead of the global property types.
    491 
    492 		Can also be used as a |method|: >
    493 			GetPropName()->prop_type_get()
    494 <
    495 		Return type: dict<any>
    496 
    497 
    498 prop_type_list([{props}])				*prop_type_list()*
    499 		Returns a list with all property type names.
    500 
    501 		{props} can contain a "bufnr" item.  When it is given, use
    502 		this buffer instead of the global property types.
    503 
    504 		Return type: list<string> or list<any>
    505 
    506 
    507 ==============================================================================
    508 3. When text changes				*text-prop-changes*
    509 
    510 Vim will do its best to keep the text properties on the text where it was
    511 attached.  When inserting or deleting text the properties after the change
    512 will move accordingly.
    513 
    514 When text is deleted and a text property no longer includes any text, it is
    515 deleted.  However, a text property that was defined as zero-width will remain,
    516 unless the whole line is deleted.  When lines are joined by a multi-line
    517 substitute command, virtual text properties on the deleted lines are moved to
    518 the resulting joined line.
    519 								*E275*
    520 When a buffer is unloaded, all the text properties are gone.  There is no way
    521 to store the properties in a file.  You can only re-create them.  When a
    522 buffer is hidden the text is preserved and so are the text properties.  It is
    523 not possible to add text properties to an unloaded buffer.
    524 
    525 When using replace mode, the text properties stay on the same character
    526 positions, even though the characters themselves change.
    527 
    528 To update text properties after the text was changed, install a callback with
    529 `listener_add()`.  E.g, if your plugin does spell checking, you can have the
    530 callback update spelling mistakes in the changed text.  Vim will move the
    531 properties below the changed text, so that they still highlight the same text,
    532 thus you don't need to update these.
    533 
    534 							*text-prop-cleared*
    535 Text property columns are not updated or copied: ~
    536 
    537 - When setting the line with |setline()| or through an interface, such as Lua,
    538   Tcl or Python.  Vim does not know what text got inserted or deleted.
    539 - With a command like `:move`, which takes a line of text out of context.
    540 
    541 
    542  vim:tw=78:ts=8:noet:ft=help:norl: