"Fossies" - the Fresh Open Source Software Archive

Member "vim-8.2.1354/runtime/doc/textprop.txt" (2 Aug 2020, 13406 Bytes) of package /linux/misc/vim-8.2.1354.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "textprop.txt" see the Fossies "Dox" file reference documentation and the last Fossies "Diffs" side-by-side code changes report: 8.2.1174_vs_8.2.1181.

    1 *textprop.txt*  For Vim version 8.2.  Last change: 2020 Mar 05
    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_clear({lnum} [, {lnum-end} [, {bufnr}]])
  112 					remove all text properties
  113 prop_find({props} [, {direction}])	search for a text property
  114 prop_list({lnum} [, {props}])  		text properties in {lnum}
  115 prop_remove({props} [, {lnum} [, {lnum-end}]])
  116 					remove a text property
  117 
  118 						*prop_add()* *E965*
  119 prop_add({lnum}, {col}, {props})
  120 		Attach a text property at position {lnum}, {col}.  {col} is
  121 		counted in bytes, use one for the first column.
  122 		If {lnum} is invalid an error is given. *E966*
  123 		If {col} is invalid an error is given. *E964*
  124 
  125 		{props} is a dictionary with these fields:
  126 		   length	length of text in bytes, can only be used
  127 				for a property that does not continue in
  128 				another line; can be zero
  129 		   end_lnum	line number for the end of text
  130 		   end_col	column just after the text; not used when
  131 				"length" is present; when {col} and "end_col"
  132 				are equal, and "end_lnum" is omitted or equal
  133 				to {lnum}, this is a zero-width text property
  134 		   bufnr	buffer to add the property to; when omitted
  135 				the current buffer is used
  136 		   id		user defined ID for the property; must be a
  137 				number; when omitted zero is used
  138 		   type		name of the text property type
  139 		All fields except "type" are optional.
  140 
  141 		It is an error when both "length" and "end_lnum" or "end_col"
  142 		are given.  Either use "length" or "end_col" for a property
  143 		within one line, or use "end_lnum" and "end_col" for a
  144 		property that spans more than one line.
  145 		When neither "length" nor "end_col" are given the property
  146 		will be zero-width.  That means it will move with the text, as
  147 		a kind of mark.  One character will be highlighted, if the
  148 		type specifies highlighting.
  149 		The property can end exactly at the last character of the
  150 		text, or just after it.  In the last case, if text is appended
  151 		to the line, the text property size will increase, also when
  152 		the property type does not have "end_incl" set.
  153 
  154 		"type" will first be looked up in the buffer the property is
  155 		added to. When not found, the global property types are used.
  156 		If not found an error is given.
  157 
  158 		Can also be used as a |method|: >
  159 			GetLnum()->prop_add(col, props)
  160 
  161 
  162 prop_clear({lnum} [, {lnum-end} [, {props}]])		*prop_clear()*
  163 		Remove all text properties from line {lnum}.
  164 		When {lnum-end} is given, remove all text properties from line
  165 		{lnum} to {lnum-end} (inclusive).
  166 
  167 		When {props} contains a "bufnr" item use this buffer,
  168 		otherwise use the current buffer.
  169 
  170 		Can also be used as a |method|: >
  171 			GetLnum()->prop_clear()
  172 <
  173 							*prop_find()*
  174 prop_find({props} [, {direction}])
  175 		Search for a text property as specified with {props}:
  176 		   id		property with this ID
  177 		   type		property with this type name
  178 		   bufnr	buffer to search in; when present a
  179 				start position with "lnum" and "col"
  180 				must be given; when omitted the
  181 				current buffer is used
  182 		   lnum		start in this line (when omitted start
  183 				at the cursor)
  184 		   col		start at this column (when omitted
  185 				and "lnum" is given: use column 1,
  186 				otherwise start at the cursor)
  187 		   skipstart	do not look for a match at the start
  188 				position
  189 
  190 		{direction} can be "f" for forward and "b" for backward.  When
  191 		omitted forward search is performed.
  192 
  193 		If a match is found then a Dict is returned with the entries
  194 		as with prop_list(), and additionally an "lnum" entry.
  195 		If no match is found then an empty Dict is returned.
  196 
  197 
  198 prop_list({lnum} [, {props}])				*prop_list()*
  199 		Return a List with all text properties in line {lnum}.
  200 
  201 		When {props} contains a "bufnr" item, use this buffer instead
  202 		of the current buffer.
  203 
  204 		The properties are ordered by starting column and priority.
  205 		Each property is a Dict with these entries:
  206 		   col		starting column
  207 		   length	length in bytes, one more if line break is
  208 				included
  209 		   id		property ID
  210 		   type		name of the property type, omitted if
  211 				the type was deleted
  212 		   start	when TRUE property starts in this line
  213 		   end		when TRUE property ends in this line
  214 
  215 		When "start" is zero the property started in a previous line,
  216 		the current one is a continuation.
  217 		When "end" is zero the property continues in the next line.
  218 		The line break after this line is included.
  219 
  220 		Can also be used as a |method|: >
  221 			GetLnum()->prop_list()
  222 <
  223 						*prop_remove()* *E968* *E860*
  224 prop_remove({props} [, {lnum} [, {lnum-end}]])
  225 		Remove a matching text property from line {lnum}.  When
  226 		{lnum-end} is given, remove matching text properties from line
  227 		{lnum} to {lnum-end} (inclusive).
  228 		When {lnum} is omitted remove matching text properties from
  229 		all lines.
  230 
  231 		{props} is a dictionary with these fields:
  232 		   id		remove text properties with this ID
  233 		   type		remove text properties with this type name
  234 		   both		"id" and "type" must both match
  235 		   bufnr	use this buffer instead of the current one
  236 		   all		when TRUE remove all matching text properties,
  237 				not just the first one
  238 		A property matches when either "id" or "type" matches.
  239 		If buffer "bufnr" does not exist you get an error message.
  240 		If buffer "bufnr" is not loaded then nothing happens.
  241 
  242 		Returns the number of properties that were removed.
  243 
  244 		Can also be used as a |method|: >
  245 			GetProps()->prop_remove()
  246 
  247 
  248 prop_type_add({name}, {props})		*prop_type_add()* *E969* *E970*
  249 		Add a text property type {name}.  If a property type with this
  250 		name already exists an error is given.  Nothing is returned.
  251 		{props} is a dictionary with these optional fields:
  252 		   bufnr	define the property only for this buffer; this
  253 				avoids name collisions and automatically
  254 				clears the property types when the buffer is
  255 				deleted.
  256 		   highlight	name of highlight group to use
  257 		   priority	when a character has multiple text
  258 				properties the one with the highest priority
  259 				will be used; negative values can be used, the
  260 				default priority is zero
  261 		   combine	when TRUE combine the highlight with any
  262 				syntax highlight; when omitted or FALSE syntax
  263 				highlight will not be used
  264 		   start_incl	when TRUE inserts at the start position will
  265 				be included in the text property
  266 		   end_incl	when TRUE inserts at the end position will be
  267 				included in the text property
  268 
  269 		Can also be used as a |method|: >
  270 			GetPropName()->prop_type_add(props)
  271 
  272 prop_type_change({name}, {props})			*prop_type_change()*
  273 		Change properties of an existing text property type.  If a
  274 		property with this name does not exist an error is given.
  275 		The {props} argument is just like |prop_type_add()|.
  276 
  277 		Can also be used as a |method|: >
  278 			GetPropName()->prop_type_change(props)
  279 
  280 prop_type_delete({name} [, {props}])			*prop_type_delete()*
  281 		Remove the text property type {name}.  When text properties
  282 		using the type {name} are still in place, they will not have
  283 		an effect and can no longer be removed by name.
  284 
  285 		{props} can contain a "bufnr" item.  When it is given, delete
  286 		a property type from this buffer instead of from the global
  287 		property types.
  288 
  289 		When text property type {name} is not found there is no error.
  290 
  291 		Can also be used as a |method|: >
  292 			GetPropName()->prop_type_delete()
  293 
  294 prop_type_get([{name} [, {props}]])			*prop_type_get()*
  295 		Returns the properties of property type {name}.  This is a
  296 		dictionary with the same fields as was given to
  297 		prop_type_add().
  298 		When the property type {name} does not exist, an empty
  299 		dictionary is returned.
  300 
  301 		{props} can contain a "bufnr" item.  When it is given, use
  302 		this buffer instead of the global property types.
  303 
  304 		Can also be used as a |method|: >
  305 			GetPropName()->prop_type_get()
  306 
  307 prop_type_list([{props}])				*prop_type_list()*
  308 		Returns a list with all property type names.
  309 
  310 		{props} can contain a "bufnr" item.  When it is given, use
  311 		this buffer instead of the global property types.
  312 
  313 
  314 ==============================================================================
  315 3. When text changes				*text-prop-changes*
  316 
  317 Vim will do its best to keep the text properties on the text where it was
  318 attached.  When inserting or deleting text the properties after the change
  319 will move accordingly.
  320 
  321 When text is deleted and a text property no longer includes any text, it is
  322 deleted.  However, a text property that was defined as zero-width will remain,
  323 unless the whole line is deleted.
  324 								*E275*
  325 When a buffer is unloaded, all the text properties are gone.  There is no way
  326 to store the properties in a file.  You can only re-create them.  When a
  327 buffer is hidden the text is preserved and so are the text properties.  It is
  328 not possible to add text properties to an unloaded buffer.
  329 
  330 When using replace mode, the text properties stay on the same character
  331 positions, even though the characters themselves change.
  332 
  333 To update text properties after the text was changed, install a callback with
  334 `listener_add()`.  E.g, if your plugin does spell checking, you can have the
  335 callback update spelling mistakes in the changed text.  Vim will move the
  336 properties below the changed text, so that they still highlight the same text,
  337 thus you don't need to update these.
  338 
  339 
  340 Text property columns are not updated or copied: ~
  341 
  342 - When setting the line with |setline()| or through an interface, such as Lua,
  343   Tcl or Python.  Vim does not know what text got inserted or deleted.
  344 - With a command like `:move`, which takes a line of text out of context.
  345 
  346 
  347  vim:tw=78:ts=8:noet:ft=help:norl: