From 09a37288853ca1af5b64976a95116b1bec687217 Mon Sep 17 00:00:00 2001 From: h-east Date: Wed, 11 Oct 2023 21:44:21 +0900 Subject: [PATCH 1/5] Update textprop.{txt,jax} --- doc/textprop.jax | 130 ++++++++++++++++++++++++++++++++++++++++------ en/textprop.txt | 131 ++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 226 insertions(+), 35 deletions(-) diff --git a/doc/textprop.jax b/doc/textprop.jax index 1d0149877..2833ce9fc 100644 --- a/doc/textprop.jax +++ b/doc/textprop.jax @@ -1,4 +1,4 @@ -*textprop.txt* For Vim バージョン 9.0. Last change: 2021 Nov 23 +*textprop.txt* For Vim バージョン 9.0. Last change: 2023 Apr 23 VIMリファレンスマニュアル by Bram Moolenaar @@ -55,7 +55,7 @@ す。 "start_incl" TRUEの場合、開始位置の挿入はテキストプロパティに含まれ ます。 - "end_incl" TRUEの場合、終了位置の挿入はテキストプロパティに含まれ + "end_incl" TRUEの場合、終了位置の挿入はテキストプロパティに含まれ ます。 @@ -107,13 +107,13 @@ prop_type_list([{props}]) プロパティタイプ一覧を取得 テキストプロパティの操作: -prop_add({lnum}, {col}, {props}) テキストプロパティを追加 -prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) +prop_add({lnum}, {col}, {props}) テキストプロパティを追加 +prop_add_list({props}, [{item}, ...]) 複数位置にテキストプロパティを追加 prop_clear({lnum} [, {lnum-end} [, {bufnr}]]) 全てのテキストプロパティを削除 prop_find({props} [, {direction}]) テキストプロパティを検索 -prop_list({lnum} [, {props}]) 行番号{lnum}のテキストプロパティを取得 +prop_list({lnum} [, {props}]) 行番号{lnum}のテキストプロパティを取得 prop_remove({props} [, {lnum} [, {lnum-end}]]) テキストプロパティを削除 @@ -125,6 +125,7 @@ prop_add({lnum}, {col}, {props}) {col}が無効な場合、エラーが発生する。 *E964* {props}は次のフィールドを持つ辞書である: + type テキストプロパティタイプ名 length テキストの長さ(バイト)。別の行に続かないプロパ ティに対してのみ使用できる。0指定可能。 end_lnum テキスト終端(内包的)の行番号 @@ -135,9 +136,42 @@ prop_add({lnum}, {col}, {props}) る。 bufnr プロパティを追加するバッファ。省略された場合、 カレントバッファが使用される - id プロパティのユーザー定義ID。数字でなければなら - ない。省略時は0が使われる - type テキストプロパティ名 + id プロパティのユーザー定義 ID。数値かつ正の値で + ある必要がある。"text" を使用する場合、"id" は + 存在してはならず、自動的に負の数値に設定され + る。それ以外の場合はゼロが使用される。 + *E1305* + text {col} の前、または {col} がゼロの場合は行の上/ + 下に表示されるテキスト。ハイライトによるパディ + ング用のスペースを先頭および/または末尾に追加 + する。"length", "end_lnum"および "end_col" と + 一緒に使用することはできない。 + 詳細については |virtual-text| を参照。 + *E1294* + text_align "text" が存在し、{col} がゼロの場合; テキスト + を表示する場所を指定する: + after 行末の後ろ + right ウィンドウ内で右揃え (テキストが画 + 面の次の行に折り返されない限り) + below 次のスクリーン行 + above 行のすぐ上 + 省略した場合は "after" が使用される。各行に収 + まる "right" プロパティは 1 つだけだが、2 つ以 + 上ある場合は別の行に配置される (右揃えのまま + で)。 + text_padding_left *E1296* + "text" が存在し、{col} がゼロの場合に使用され + る。テキスト行末 ("above" と "below" の左端の + 桁) とハイライトされていない仮想テキストの間の + パディング + text_wrap "text" が存在し、{col} がゼロの場合、テキスト + がぴったり合わない場合に何が起こるかを指定する: + wrap テキストを次の行に折り返す + truncate テキストを切り捨てて収める + 省略時は "truncate" が使用される。 + Note これは個々のテキストプロパティに適用され、 + 'wrap' オプションは全体の動作を設定することに + 注意。 "type" を除くすべてのフィールドは任意である。 "length" と "end_lnum" または "end_col" の両方が与えられるとエ @@ -156,12 +190,45 @@ prop_add({lnum}, {col}, {props}) プロパティが追加されたバッファで、"type" が最初に検索される。 見つからない場合は、グローバルプロパティタイプが使用される。見 つからなければエラーになる。 + *virtual-text* + "text" が使用され、桁が非ゼロの場合、このテキストはテキストプ + ロパティの指定された開始位置に表示される。バッファ行のテキスト + は、スペースを確保するためにシフトされる。これを "virtual text" + (仮想テキスト) と呼ぶ。 + 桁がゼロの場合、仮想テキストはバッファテキストの上、後ろ、また + は下に表示される。"text_align" および "text_wrap" 引数によっ + て、どのように表示されるかが決定される。 + 仮想テキストをバッファテキストから分離するには、"text" フィー + ルドにスペースを追加するか、"text_padding_left" を使用する。 + + これが仮想テキストであることがユーザーに明確に分かるように必ず + ハイライトを使用すること。そうしないと、テキストが編集できない + ため非常に混乱することになる。"above" を使用する場合は、このテ + キストがその下のテキスト行に属していることを明確にする必要があ + り、"below" を使用する場合は、そのテキストがその上のテキスト行 + に属していることを確認する必要があります。 + + テキストは表示されるが、実際のバッファ行の一部ではないので、 + カーソルをその上に置くことはできない。テキスト内でマウスをク + リックすると、カーソルはテキストの後の最初の文字か、行の最後の + 文字に移動する。 + テキスト中のタブやその他の制御文字はスペースに変更される (理由: + そうしないとテキストのサイズ計算が困難になる)。 + 負の "id" が選択され、返される。 + + テキストを含むテキストプロパティがサポートされる前は、非常にま + れではあるが、負の "id" を使用することができた。負の "id" はテ + キストを含むテキストプロパティ用に予約されているため、負の "id" + を使用するとエラーが発生する。テキストを含むテキストプロパティ + が既に存在する場合、負の "id" を使用すると *E1293* が発生する。 + 負の "id" が使用され、後でテキストを含むテキストプロパティが追 + 加されると、*E1339* が発生する。 |method| としても使用できる: > GetLnum()->prop_add(col, props) < *prop_add_list()* -prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) +prop_add_list({props}, [{item}, ...]) prop_add() に似ているが、バッファ内の複数位置にテキストプロパ ティが付加される。 @@ -174,16 +241,31 @@ prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) "type" を除くすべてのフィールドは任意である。 第2引数はリストのリストで、各リストはテキストの開始と終了の位 - 置を示す。最初の2つの項目{lnum}と{col}はプロパティを付加する開 - 始位置を、最後の2つの項目{end-lnum}と{end-col}は付加される位置 - の直後を示す。 - - 例: + 置を示す。最初の2つの項目 {lnum} と {col} はプロパティを付加す + る開始位置を、最後の2つの項目 {end-lnum} と {end-col} は付加さ + れる位置の直後を示す。 + 第 2 引数は項目のリストで、各 {item} はテキストの開始位置と終 + 了位置を指定するリストである: + [{lnum}, {col}, {end-lnum}, {end-col}] + または: [{lnum}, {col}, {end-lnum}, {end-col}, {id}] + + 最初の 2 つの項目 {lnum} と {col} は、プロパティが付加されるテ + キストの開始位置を指定する。 + 次の 2 つの項目 {end-lnum} と {end-col} は、テキストの直後の位 + 置を指定する。 + オプションの 5 番目の項目 {id} を使用して、プロパティに別の ID + を与えることができる。省略すると、{props} の ID が使用され、何 + も存在しない場合はセロにフォールバックする。 + + ここで "text" フィールドを含むテキストプロパティを追加すること + はできない。 + + 例: > call prop_add_list(#{type: 'MyProp', id: 2}, \ [[1, 4, 1, 7], \ [1, 15, 1, 20], \ [2, 30, 3, 30]] - +< |method| としても使用できる: > GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]]) @@ -245,6 +327,12 @@ prop_list({lnum} [, {props}]) *prop_list()* col 開始桁 length バイト長。改行が含まれる場合は1以上。 id プロパティID + text {col} の前に表示されるテキスト。|virtual-text| + プロパティにのみ存在する。 + text_align |virtual-text| の配置プロパティ。 + text_padding_left + 仮想テキストに使用される左パディング。 + text_wrap |virtual-text| を折り返すかどうかを指定する。 type プロパティタイプ名。タイプが削除された場合は省 略される type_bufnr プロパティタイプが定義されたバッファ番号。 @@ -300,12 +388,18 @@ prop_remove({props} [, {lnum} [, {lnum-end}]]) {props}は次のフィールドを持つ辞書である: id このIDを持つテキストプロパティを削除する type このタイプ名を持つテキストプロパティを削除する - both "id" と "type" の両方が一致しなければならない + types このリスト内の型名を持つテキスト プロパティを + 削除する + both "id" と "type"/"types" の両方が一致しなければ + ならない bufnr カレントバッファの代わりにこのバッファを使う all TRUEの場合、最初のテキストプロパティだけでな く、一致するテキストプロパティをすべて削除す る。 - "id" または "type" のどちらかが一致するとプロパティが一致する。 + "type" と "types" のいずれか 1 つだけを指定できる。 *E1295* + + プロパティは、"id" または指定されたタイプのいずれかが一致する + 場合に一致する。 バッファ "bufnr" が存在しない場合はエラーメッセージが表示され る。 バッファ "bufnr" がロードされていなければ、何も起こらない。 @@ -330,6 +424,8 @@ prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970* combine 省略されるかTRUEの場合、ハイライトを任意の構文 ハイライトと結び付ける。FALSEの場合は構文ハイ ライトは使用されない + override TRUE の場合、ハイライトは 'cursorline' やビジュ + アルを含む他のハイライトをオーバーライドする start_incl TRUEの場合、開始位置の挿入はテキストプロパティ に含まれる end_incl TRUEの場合、終了位置の挿入はテキストプロパティ diff --git a/en/textprop.txt b/en/textprop.txt index fc71bb4c2..14fe2977a 100644 --- a/en/textprop.txt +++ b/en/textprop.txt @@ -1,4 +1,4 @@ -*textprop.txt* For Vim version 9.0. Last change: 2021 Nov 23 +*textprop.txt* For Vim version 9.0. Last change: 2023 Apr 23 VIM REFERENCE MANUAL by Bram Moolenaar @@ -56,7 +56,7 @@ how to highlight the text. The property type can have these entries: priority will be used. "start_incl" when TRUE inserts at the start position will be included in the text property - "end_incl" when TRUE inserts at the end position will be + "end_incl" when TRUE inserts at the end position will be included in the text property @@ -107,14 +107,14 @@ prop_type_list([{props}]) get list of property types Manipulating text properties: -prop_add({lnum}, {col}, {props}) add a text property -prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) +prop_add({lnum}, {col}, {props}) add a text property +prop_add_list({props}, [{item}, ...]) add a text property at multiple positions. prop_clear({lnum} [, {lnum-end} [, {bufnr}]]) remove all text properties prop_find({props} [, {direction}]) search for a text property -prop_list({lnum} [, {props}]) text properties in {lnum} +prop_list({lnum} [, {props}]) text properties in {lnum} prop_remove({props} [, {lnum} [, {lnum-end}]]) remove a text property @@ -126,6 +126,7 @@ prop_add({lnum}, {col}, {props}) If {col} is invalid an error is given. *E964* {props} is a dictionary with these fields: + type name of the text property type length length of text in bytes, can only be used for a property that does not continue in another line; can be zero @@ -137,8 +138,44 @@ prop_add({lnum}, {col}, {props}) bufnr buffer to add the property to; when omitted the current buffer is used id user defined ID for the property; must be a - number; when omitted zero is used - type name of the text property type + number, should be positive; when using "text" + then "id" must not be present and will be set + automatically to a negative number; otherwise + zero is used + *E1305* + text text to be displayed before {col}, or + above/below the line if {col} is zero; prepend + and/or append spaces for padding with + highlighting; cannot be used with "length", + "end_lnum" and "end_col" + See |virtual-text| for more information. + *E1294* + text_align when "text" is present and {col} is zero; + specifies where to display the text: + after after the end of the line + right right aligned in the window (unless + the text wraps to the next screen + line) + below in the next screen line + above just above the line + When omitted "after" is used. Only one + "right" property can fit in each line, if + there are two or more these will go in a + separate line (still right aligned). + text_padding_left *E1296* + used when "text" is present and {col} is zero; + padding between the end of the text line + (leftmost column for "above" and "below") and + the virtual text, not highlighted + text_wrap when "text" is present and {col} is zero, + specifies what happens if the text doesn't + fit: + wrap wrap the text to the next line + truncate truncate the text to make it fit + When omitted "truncate" is used. + Note that this applies to the individual text + property, the 'wrap' option sets the overall + behavior All fields except "type" are optional. It is an error when both "length" and "end_lnum" or "end_col" @@ -157,12 +194,48 @@ prop_add({lnum}, {col}, {props}) "type" will first be looked up in the buffer the property is added to. When not found, the global property types are used. If not found an error is given. + *virtual-text* + When "text" is used and the column is non-zero then this text + will be displayed at the specified start location of the text + property. The text of the buffer line will be shifted to make + room. This is called "virtual text". + When the column is zero the virtual text will appear above, + after or below the buffer text. The "text_align" and + "text_wrap" arguments determine how it is displayed. + To separate the virtual text from the buffer text prepend + and/or append spaces to the "text" field or use the + "text_padding_left" value. + + Make sure to use a highlight that makes clear to the user that + this is virtual text, otherwise it will be very confusing that + the text cannot be edited. When using "above" you need to + make clear this text belongs to the text line below it, when + using "below" you need to make sure it belongs to the text + line above it. + + The text will be displayed but it is not part of the actual + buffer line, the cursor cannot be placed on it. A mouse click + in the text will move the cursor to the first character after + the text, or the last character of the line. + Any Tab and other control character in the text will be + changed to a space (Rationale: otherwise the size of the text + is difficult to compute). + A negative "id" will be chosen and is returned. + + Before text properties with text were supported it was + possible to use a negative "id", even though this was very + rare. Now that negative "id"s are reserved for text + properties with text an error is given when using a negative + "id". When a text property with text already exists using a + negative "id" results in *E1293* . If a negative "id" was + used and later a text property with text is added results in + *E1339* . Can also be used as a |method|: > GetLnum()->prop_add(col, props) < *prop_add_list()* -prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) +prop_add_list({props}, [{item}, ...]) Similar to prop_add(), but attaches a text property at multiple positions in a buffer. @@ -174,19 +247,28 @@ prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) type name of the text property type All fields except "type" are optional. - The second argument is a List of Lists where each list - specifies the starting and ending position of the text. The - first two items {lnum} and {col} specify the starting position - of the text where the property will be attached and the last - two items {end-lnum} and {end-col} specify the position just - after the text. + The second argument is a List of items, where each {item} is a + list that specifies the starting and ending position of the + text: [{lnum}, {col}, {end-lnum}, {end-col}] + or: [{lnum}, {col}, {end-lnum}, {end-col}, {id}] + + The first two items {lnum} and {col} specify the starting + position of the text where the property will be attached. + The next two items {end-lnum} and {end-col} specify the + position just after the text. + An optional fifth item {id} can be used to give a different ID + to a property. When omitted the ID from {props} is used, + falling back to zero if none are present. + + It is not possible to add a text property with a "text" field + here. - Example: + Example: > call prop_add_list(#{type: 'MyProp', id: 2}, \ [[1, 4, 1, 7], \ [1, 15, 1, 20], \ [2, 30, 3, 30]] - +< Can also be used as a |method|: > GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]]) @@ -253,6 +335,12 @@ prop_list({lnum} [, {props}]) *prop_list()* length length in bytes, one more if line break is included id property ID + text text to be displayed before {col}. Only + present for |virtual-text| properties. + text_align alignment property of |virtual-text|. + text_padding_left + left padding used for virtual text. + text_wrap specifies whether |virtual-text| is wrapped. type name of the property type, omitted if the type was deleted type_bufnr buffer number for which this type was defined; @@ -304,11 +392,16 @@ prop_remove({props} [, {lnum} [, {lnum-end}]]) {props} is a dictionary with these fields: id remove text properties with this ID type remove text properties with this type name - both "id" and "type" must both match + types remove text properties with type names in this + List + both "id" and "type"/"types" must both match bufnr use this buffer instead of the current one all when TRUE remove all matching text properties, not just the first one - A property matches when either "id" or "type" matches. + Only one of "type" and "types" may be supplied. *E1295* + + A property matches when either "id" or one of the supplied + types matches. If buffer "bufnr" does not exist you get an error message. If buffer "bufnr" is not loaded then nothing happens. @@ -334,6 +427,8 @@ prop_type_add({name}, {props}) *prop_type_add()* *E969* *E970* combine when omitted or TRUE combine the highlight with any syntax highlight; when FALSE syntax highlight will not be used + override when TRUE the highlight overrides any other, + including 'cursorline' and Visual start_incl when TRUE inserts at the start position will be included in the text property end_incl when TRUE inserts at the end position will be From ea5c0090ffbc45d02c8d11fcc83a88f1b1626cfa Mon Sep 17 00:00:00 2001 From: h_east Date: Wed, 11 Oct 2023 22:32:58 +0900 Subject: [PATCH 2/5] Update doc/textprop.jax Co-authored-by: K.Takata --- doc/textprop.jax | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/textprop.jax b/doc/textprop.jax index 2833ce9fc..4c0c7f787 100644 --- a/doc/textprop.jax +++ b/doc/textprop.jax @@ -206,7 +206,7 @@ prop_add({lnum}, {col}, {props}) ため非常に混乱することになる。"above" を使用する場合は、このテ キストがその下のテキスト行に属していることを明確にする必要があ り、"below" を使用する場合は、そのテキストがその上のテキスト行 - に属していることを確認する必要があります。 + に属していることを確認する必要がある。 テキストは表示されるが、実際のバッファ行の一部ではないので、 カーソルをその上に置くことはできない。テキスト内でマウスをク From c0b8fd02ae195a39d13d1277dbac77e83105e96d Mon Sep 17 00:00:00 2001 From: h_east Date: Wed, 11 Oct 2023 22:33:40 +0900 Subject: [PATCH 3/5] Update doc/textprop.jax Co-authored-by: K.Takata --- doc/textprop.jax | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/textprop.jax b/doc/textprop.jax index 4c0c7f787..5949229a7 100644 --- a/doc/textprop.jax +++ b/doc/textprop.jax @@ -144,7 +144,7 @@ prop_add({lnum}, {col}, {props}) text {col} の前、または {col} がゼロの場合は行の上/ 下に表示されるテキスト。ハイライトによるパディ ング用のスペースを先頭および/または末尾に追加 - する。"length", "end_lnum"および "end_col" と + する。"length", "end_lnum" および "end_col" と 一緒に使用することはできない。 詳細については |virtual-text| を参照。 *E1294* From 8a911a9b3b0d67e195e10cac6fec4299ddbf68f1 Mon Sep 17 00:00:00 2001 From: h_east Date: Fri, 13 Oct 2023 01:08:05 +0900 Subject: [PATCH 4/5] Update doc/textprop.jax Co-authored-by: K.Takata --- doc/textprop.jax | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/textprop.jax b/doc/textprop.jax index 5949229a7..db26860f4 100644 --- a/doc/textprop.jax +++ b/doc/textprop.jax @@ -255,7 +255,7 @@ prop_add_list({props}, [{item}, ...]) 置を指定する。 オプションの 5 番目の項目 {id} を使用して、プロパティに別の ID を与えることができる。省略すると、{props} の ID が使用され、何 - も存在しない場合はセロにフォールバックする。 + も存在しない場合はゼロにフォールバックする。 ここで "text" フィールドを含むテキストプロパティを追加すること はできない。 From 7b5f2670b03a92d525292cc5ef68e43710af001e Mon Sep 17 00:00:00 2001 From: h-east Date: Sat, 14 Oct 2023 18:46:50 +0900 Subject: [PATCH 5/5] Fix review point --- doc/textprop.jax | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/textprop.jax b/doc/textprop.jax index db26860f4..53d8149dc 100644 --- a/doc/textprop.jax +++ b/doc/textprop.jax @@ -206,7 +206,7 @@ prop_add({lnum}, {col}, {props}) ため非常に混乱することになる。"above" を使用する場合は、このテ キストがその下のテキスト行に属していることを明確にする必要があ り、"below" を使用する場合は、そのテキストがその上のテキスト行 - に属していることを確認する必要がある。 + に属していることを明確にする必要がある。 テキストは表示されるが、実際のバッファ行の一部ではないので、 カーソルをその上に置くことはできない。テキスト内でマウスをク