vim: runtime/doc/textprop.txt annotate

annotate runtime/doc/textprop.txt @ 16545:7a563ee902b6 v8.1.1276

patch 8.1.1276: cannot combine text properties with syntax highlighting commit https://github.com/vim/vim/commit/de24a8701328b1cce7cad0ee11b415369b482420 Author: Bram Moolenaar <Bram@vim.org> Date: Sun May 5 15:48:00 2019 +0200 patch 8.1.1276: cannot combine text properties with syntax highlighting Problem: Cannot combine text properties with syntax highlighting. Solution: Add the "combine" field to prop_type_add(). (closes https://github.com/vim/vim/issues/4343)

author	Bram Moolenaar <Bram@vim.org>
date	Sun, 05 May 2019 16:00:05 +0200
parents	f0f06837a699
children	0e473e9e70c2

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

Mercurial > vim

annotate runtime/doc/textprop.txt @ 16545:7a563ee902b6 v8.1.1276