vim: runtime/doc/textprop.txt annotate

annotate runtime/doc/textprop.txt @ 15512:f0f06837a699

Update runtime files. commit https://github.com/vim/vim/commit/d09091d4955c5f41de69928f2db85611ed54ed23 Author: Bram Moolenaar <Bram@vim.org> Date: Thu Jan 17 16:07:22 2019 +0100 Update runtime files.

author	Bram Moolenaar <Bram@vim.org>
date	Thu, 17 Jan 2019 16:15:08 +0100
parents	9d3d7b0f4861
children	7a563ee902b6

rev	line source
15512 f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	1 textprop.txt For Vim version 8.1. Last change: 2019 Jan 08
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
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	60 "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	61 priority will be used.
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	62 "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	63 included in the text property
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	64 "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	65 included in the text property
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	66
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	67
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	68 Example ~
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	69
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	70 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	71
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	72 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	73
15334 9d3d7b0f4861 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 15281 diff changeset	74 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	75 call prop_type_add('number', {'highlight': 'Constant'})
15194 8b334e4cb97f Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15138 diff changeset	76 call prop_add(11, 12, {'length': 3, 'type': 'number'})
8b334e4cb97f Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15138 diff changeset	77 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	78
15334 9d3d7b0f4861 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 15281 diff changeset	79 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	80 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	81
15138 9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	82 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	83 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	84 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	85
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	86 func FuncName(arg) ~
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	87 ^^^^^^^^ 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	88
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	89 var = "text"; ~
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	90 ^^^^^^ 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	91
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	92 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	93 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	94
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 2. Functions text-prop-functions
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	97
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	98 Manipulating text property types:
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 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	101 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	102 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	103 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	104 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	105
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	106
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	107 Manipulating text properties:
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	108
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	109 prop_add({lnum}, {col}, {props}) add a text property
15281 97b40b4c6911 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15194 diff changeset	110 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	111 remove all text properties
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	112 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	113 prop_list({lnum} [, {props}) text properties in {lnum}
15281 97b40b4c6911 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15194 diff changeset	114 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	115 remove a text property
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	116
15512 f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	117 ==============================================================================
f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	118 3. When text changes text-prop-changes
f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	119
f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	120 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	121 attached. When inserting or deleting text the properties after the change
f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	122 will move accordingly.
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 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	125 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	126 unless the whole line is deleted.
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 using replace mode, the text properties stay on the same character
f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	129 positions, even though the characters themselves change.
f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	130
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 text property columns are not updated ~
f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	133
f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	134 - 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	135 Tcl or Python.
f0f06837a699 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	136
15138 9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	137
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	138 vim:tw=78:ts=8:noet:ft=help:norl:

Mercurial > vim

annotate runtime/doc/textprop.txt @ 15512:f0f06837a699