vim: runtime/doc/textprop.txt annotate

annotate runtime/doc/textprop.txt @ 15335:18c20ceee4b5 v8.1.0675

patch 8.1.0675: text property column in screen columns is not practical commit https://github.com/vim/vim/commit/b9c67a51c15481d9257e5c26581d17780e9808d5 Author: Bram Moolenaar <Bram@vim.org> Date: Tue Jan 1 19:49:20 2019 +0100 patch 8.1.0675: text property column in screen columns is not practical Problem: Text property column is screen columns is not practical. Solution: Use byte values for the column.

author	Bram Moolenaar <Bram@vim.org>
date	Tue, 01 Jan 2019 20:00:07 +0100
parents	9d3d7b0f4861
children	f0f06837a699

rev	line source
15334 9d3d7b0f4861 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 15281 diff changeset	1 textprop.txt For Vim version 8.1. Last change: 2018 Dec 30
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
15334 9d3d7b0f4861 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 15281 diff changeset	73 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	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
15334 9d3d7b0f4861 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 15281 diff changeset	78 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	79 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	80
15138 9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	81 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	82 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	83 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	84
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	85 func FuncName(arg) ~
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 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 var = "text"; ~
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	89 ^^^^^^ 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	90
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	91 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	92 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	93
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 2. Functions text-prop-functions
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	96
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	97 Manipulating text property types:
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 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	100 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	101 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	102 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	103 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	104
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 Manipulating text properties:
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	107
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	108 prop_add({lnum}, {col}, {props}) add a text property
15281 97b40b4c6911 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15194 diff changeset	109 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	110 remove all text properties
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	111 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	112 prop_list({lnum} [, {props}) text properties in {lnum}
15281 97b40b4c6911 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15194 diff changeset	113 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	114 remove a text property
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	115
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	116
9df130fd5e0d patch 8.1.0579: cannot attach properties to text Bram Moolenaar <Bram@vim.org> parents: diff changeset	117 vim:tw=78:ts=8:noet:ft=help:norl:

Mercurial > vim

annotate runtime/doc/textprop.txt @ 15335:18c20ceee4b5 v8.1.0675