Mercurial > vim

annotate runtime/doc/textprop.txt @ 15257:31639f035d76 v8.1.0637

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
patch 8.1.0637: nsis file no longer used commit https://github.com/vim/vim/commit/4604fbbbff9e1f924e76a6b4695626b519bd4030 Author: Bram Moolenaar <Bram@vim.org> Date: Tue Dec 25 23:37:02 2018 +0100 patch 8.1.0637: nsis file no longer used Problem: Nsis file no longer used. Solution: Remove the file. (Ken Takata)
author Bram Moolenaar <Bram@vim.org>
date Tue, 25 Dec 2018 23:45:04 +0100
parents 8b334e4cb97f
children 97b40b4c6911
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
15194
8b334e4cb97f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 15138
diff changeset
1 *textprop.txt* For Vim version 8.1. Last change: 2018 Dec 14
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|
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
20
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 {Vi does not have text properties}
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
23 {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
24 disabled at compile time}
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
25
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 1. Introduction *text-prop-intro*
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
28
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
29 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
30 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
31 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
32 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
33 will increase/decrease in size.
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
34
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
35 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
36 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
37 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
38 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
39 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
40 attaching the text properties.
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
41
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
42 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
43 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
44 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
45
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
46 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
47 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
48
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
49 A text property has these fields:
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
50 "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
51 "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
52
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 Property Types ~
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
55 *E971*
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
56 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
57 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
58 "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
59 "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
60 priority will be used.
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
61 "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
62 included in the text property
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
63 "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
64 included in the text property
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
65
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 Example ~
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
68
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
69 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
70
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
71 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
72
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
73 To highlight the numbers: >
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
74 call prop_type_add('number', {'highlight': 'Constant'})
15194
8b334e4cb97f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 15138
diff changeset
75 call prop_add(11, 12, {'length': 3, 'type': 'number'})
8b334e4cb97f Update runtime files.
Bram Moolenaar <Bram@vim.org>
parents: 15138
diff changeset
76 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
77
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
78 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
79 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
80 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
81
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
82 func FuncName(arg) ~
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
83 ^^^^^^^^ 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
84
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
85 var = "text"; ~
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
86 ^^^^^^ 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
87
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
88 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
89 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
90
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 2. Functions *text-prop-functions*
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
93
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
94 Manipulating text property types:
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 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
97 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
98 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
99 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
100 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
101
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
102
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
103 Manipulating text properties:
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
104
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
105 prop_add({lnum}, {col}, {props}) add a text property
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
106 prop_clear({lnum} [, {lnum_end} [, {bufnr}]])
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
107 remove all text properties
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
108 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
109 prop_list({lnum} [, {props}) text properties in {lnum}
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
110 prop_remove({props} [, {lnum} [, {lnum_end}]])
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
111 remove a text property
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
9df130fd5e0d patch 8.1.0579: cannot attach properties to text
Bram Moolenaar <Bram@vim.org>
parents:
diff changeset
114 vim:tw=78:ts=8:noet:ft=help:norl: