Skip to content

Commit c2d266e

Browse files
alex-courtisalex-courtis
committed
docs(#3241): add nvim-tree-class-decorator-example
1 parent 958feb0 commit c2d266e

4 files changed

Lines changed: 204 additions & 116 deletions

File tree

‎doc/nvim-tree-lua.txt‎

Lines changed: 102 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -850,117 +850,6 @@ configurations for different types of prompts.
850850
- `nvimtree_bulk_trash`
851851
send all bookmarked to trash during |nvim_tree.api.marks.bulk.trash()|
852852

853-
==============================================================================
854-
Decorators *nvim-tree-decorators*
855-
856-
Highlighting and icons for nodes are provided by Decorators. You may provide
857-
your own in addition to the builtin decorators.
858-
859-
Decorators may:
860-
- Add icons
861-
- Set highlight group for the name or icons
862-
- Override node icon
863-
864-
Create a `nvim_tree.api.decorator.UserDecorator` class and register it with
865-
precedence via |nvim_tree.config.renderer| {decorators}
866-
867-
See |nvim-tree-decorator-example|
868-
869-
==============================================================================
870-
Decorators: Example *nvim-tree-decorator-example*
871-
872-
A decorator class for nodes named "example", overridind all builtin decorators
873-
except for Cut.
874-
875-
- Highlights node name with `IncSearch`
876-
- Creates two icons `"1"` and `"2"` placed after the node name, highlighted with
877-
`DiffAdd` and `DiffText`
878-
- Replaces the node icon with `"N"`, highlighted with `Error `
879-
880-
Create a class file `~/.config/nvim/lua/my-decorator.lua`
881-
882-
Require and register it during |nvim-tree-setup|:
883-
>lua
884-
local MyDecorator = require("my-decorator")
885-
886-
require("nvim-tree").setup({
887-
renderer = {
888-
decorators = {
889-
"Git",
890-
"Open",
891-
"Hidden",
892-
"Modified",
893-
"Bookmark",
894-
"Diagnostics",
895-
"Copied",
896-
MyDecorator,
897-
"Cut",
898-
},
899-
},
900-
})
901-
<
902-
Contents of `my-decorator.lua`:
903-
>lua
904-
---@class (exact) MyDecorator: nvim_tree.api.Decorator
905-
---@field private my_icon1 nvim_tree.api.highlighted_string
906-
---@field private my_icon2 nvim_tree.api.highlighted_string
907-
---@field private my_icon_node nvim_tree.api.highlighted_string
908-
---@field private my_highlight_group string
909-
local MyDecorator = require("nvim-tree.api").Decorator:extend()
910-
911-
---Mandatory constructor :new() will be called once per tree render, with no arguments.
912-
function MyDecorator:new()
913-
self.enabled = true
914-
self.highlight_range = "name"
915-
self.icon_placement = "after"
916-
917-
-- create your icons and highlights once, applied to every node
918-
self.my_icon1 = { str = "1", hl = { "DiffAdd" } }
919-
self.my_icon2 = { str = "2", hl = { "DiffText" } }
920-
self.my_icon_node = { str = "N", hl = { "Error" } }
921-
self.my_highlight_group = "IncSearch"
922-
923-
-- Define the icon signs only once
924-
-- Only needed if you are using icon_placement = "signcolumn"
925-
-- self:define_sign(self.my_icon1)
926-
-- self:define_sign(self.my_icon2)
927-
end
928-
929-
---Override node icon
930-
---@param node nvim_tree.api.Node
931-
---@return nvim_tree.api.highlighted_string? icon_node
932-
function MyDecorator:icon_node(node)
933-
if node.name == "example" then
934-
return self.my_icon_node
935-
else
936-
return nil
937-
end
938-
end
939-
940-
---Return two icons for DecoratorIconPlacement "after"
941-
---@param node nvim_tree.api.Node
942-
---@return nvim_tree.api.highlighted_string[]? icons
943-
function MyDecorator:icons(node)
944-
if node.name == "example" then
945-
return { self.my_icon1, self.my_icon2, }
946-
else
947-
return nil
948-
end
949-
end
950-
951-
---Exactly one highlight group for DecoratorHighlightRange "name"
952-
---@param node nvim_tree.api.Node
953-
---@return string? highlight_group
954-
function MyDecorator:highlight_group(node)
955-
if node.name == "example" then
956-
return self.my_highlight_group
957-
else
958-
return nil
959-
end
960-
end
961-
962-
return MyDecorator
963-
<
964853
==============================================================================
965854
OS Specific Restrictions *nvim-tree-os-specific*
966855

@@ -3273,12 +3162,14 @@ Class:nop({...}) *nvim_tree.Class:nop()*
32733162
Class: Decorator *nvim-tree-class-decorator*
32743163

32753164
Highlighting and icons for nodes are provided by Decorators, see
3276-
|nvim-tree-icons-highlighting| for an overview. You may provide your own in
3277-
addition to the builtin decorators.
3165+
|nvim-tree-icons-highlighting| for an overview.
32783166

32793167
Decorators are rendered in |nvim_tree.config.renderer| {decorators} order of
32803168
precedence, with later decorators applying additively over earlier.
32813169

3170+
You may provide your own in addition to the builtin decorators, see
3171+
|nvim-tree-class-decorator-example|.
3172+
32823173
Decorators may:
32833174
• Add icons
32843175
• Set a highlight group name for the name or icons
@@ -3387,4 +3278,102 @@ Decorator:icons({node}) *nvim_tree.api.Decorator:icons()*
33873278
is `"signcolumn"`
33883279

33893280

3281+
==============================================================================
3282+
Class: Decorator: example *nvim-tree-class-decorator-example*
3283+
3284+
A decorator class for nodes named "example", overriding all builtin decorators
3285+
except for Cut.
3286+
• Highlights node name with `IncSearch`
3287+
• Creates two icons `"1"` and `"2"` placed after the node name, highlighted
3288+
with `DiffAdd` and `DiffText`
3289+
• Replaces the node icon with `"N"`, highlighted with `Error `
3290+
3291+
Create a class file `~/.config/nvim/lua/my-decorator.lua`
3292+
3293+
Require and register it during |nvim-tree-setup|: >lua
3294+
3295+
local MyDecorator = require("my-decorator")
3296+
3297+
require("nvim-tree").setup({
3298+
renderer = {
3299+
decorators = {
3300+
"Git",
3301+
"Open",
3302+
"Hidden",
3303+
"Modified",
3304+
"Bookmark",
3305+
"Diagnostics",
3306+
"Copied",
3307+
MyDecorator,
3308+
"Cut",
3309+
},
3310+
},
3311+
})
3312+
<
3313+
3314+
Contents of `my-decorator.lua`: >lua
3315+
3316+
---@class (exact) MyDecorator: nvim_tree.api.Decorator
3317+
---@field private my_icon1 nvim_tree.api.highlighted_string
3318+
---@field private my_icon2 nvim_tree.api.highlighted_string
3319+
---@field private my_icon_node nvim_tree.api.highlighted_string
3320+
---@field private my_highlight_group string
3321+
local MyDecorator = require("nvim-tree.api").Decorator:extend()
3322+
3323+
---Mandatory constructor :new() will be called once per tree render, with no arguments.
3324+
function MyDecorator:new()
3325+
self.enabled = true
3326+
self.highlight_range = "name"
3327+
self.icon_placement = "after"
3328+
3329+
-- create your icons and highlights once, applied to every node
3330+
self.my_icon1 = { str = "1", hl = { "DiffAdd" } }
3331+
self.my_icon2 = { str = "2", hl = { "DiffText" } }
3332+
self.my_icon_node = { str = "N", hl = { "Error" } }
3333+
self.my_highlight_group = "IncSearch"
3334+
3335+
-- Define the icon signs only once
3336+
-- Only needed if you are using icon_placement = "signcolumn"
3337+
-- self:define_sign(self.my_icon1)
3338+
-- self:define_sign(self.my_icon2)
3339+
end
3340+
3341+
---Override node icon
3342+
---@param node nvim_tree.api.Node
3343+
---@return nvim_tree.api.highlighted_string? icon_node
3344+
function MyDecorator:icon_node(node)
3345+
if node.name == "example" then
3346+
return self.my_icon_node
3347+
else
3348+
return nil
3349+
end
3350+
end
3351+
3352+
---Return two icons for DecoratorIconPlacement "after"
3353+
---@param node nvim_tree.api.Node
3354+
---@return nvim_tree.api.highlighted_string[]? icons
3355+
function MyDecorator:icons(node)
3356+
if node.name == "example" then
3357+
return { self.my_icon1, self.my_icon2, }
3358+
else
3359+
return nil
3360+
end
3361+
end
3362+
3363+
---Exactly one highlight group for DecoratorHighlightRange "name"
3364+
---@param node nvim_tree.api.Node
3365+
---@return string? highlight_group
3366+
function MyDecorator:highlight_group(node)
3367+
if node.name == "example" then
3368+
return self.my_highlight_group
3369+
else
3370+
return nil
3371+
end
3372+
end
3373+
3374+
return MyDecorator
3375+
<
3376+
3377+
3378+
33903379
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:

‎lua/nvim-tree/_meta/api/decorator.lua‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,12 @@
33
---#TODO 3241 maybe rename to UserDecorator
44

55
---@brief
6-
---Highlighting and icons for nodes are provided by Decorators, see [nvim-tree-icons-highlighting] for an overview. You may provide your own in addition to the builtin decorators.
6+
---Highlighting and icons for nodes are provided by Decorators, see [nvim-tree-icons-highlighting] for an overview.
77
---
88
---Decorators are rendered in [nvim_tree.config.renderer] {decorators} order of precedence, with later decorators applying additively over earlier.
99
---
10+
---You may provide your own in addition to the builtin decorators, see |nvim-tree-class-decorator-example|.
11+
---
1012
---Decorators may:
1113
---- Add icons
1214
---- Set a highlight group name for the name or icons

‎lua/nvim-tree/_meta/api/decorator_example.lua‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---@meta
2+
error("Cannot require a meta file")
3+
4+
---@brief
5+
---
6+
---A decorator class for nodes named "example", overriding all builtin decorators except for Cut.
7+
---- Highlights node name with `IncSearch`
8+
---- Creates two icons `"1"` and `"2"` placed after the node name, highlighted with `DiffAdd` and `DiffText`
9+
---- Replaces the node icon with `"N"`, highlighted with `Error `
10+
---
11+
---Create a class file `~/.config/nvim/lua/my-decorator.lua`
12+
---
13+
---Require and register it during |nvim-tree-setup|:
14+
---```lua
15+
---
16+
---local MyDecorator = require("my-decorator")
17+
---
18+
---require("nvim-tree").setup({
19+
--- renderer = {
20+
--- decorators = {
21+
--- "Git",
22+
--- "Open",
23+
--- "Hidden",
24+
--- "Modified",
25+
--- "Bookmark",
26+
--- "Diagnostics",
27+
--- "Copied",
28+
--- MyDecorator,
29+
--- "Cut",
30+
--- },
31+
--- },
32+
---})
33+
---```
34+
---Contents of `my-decorator.lua`:
35+
---```lua
36+
---
37+
------@class (exact) MyDecorator: nvim_tree.api.Decorator
38+
------@field private my_icon1 nvim_tree.api.highlighted_string
39+
------@field private my_icon2 nvim_tree.api.highlighted_string
40+
------@field private my_icon_node nvim_tree.api.highlighted_string
41+
------@field private my_highlight_group string
42+
---local MyDecorator = require("nvim-tree.api").Decorator:extend()
43+
---
44+
------Mandatory constructor :new() will be called once per tree render, with no arguments.
45+
---function MyDecorator:new()
46+
--- self.enabled = true
47+
--- self.highlight_range = "name"
48+
--- self.icon_placement = "after"
49+
---
50+
--- -- create your icons and highlights once, applied to every node
51+
--- self.my_icon1 = { str = "1", hl = { "DiffAdd" } }
52+
--- self.my_icon2 = { str = "2", hl = { "DiffText" } }
53+
--- self.my_icon_node = { str = "N", hl = { "Error" } }
54+
--- self.my_highlight_group = "IncSearch"
55+
---
56+
--- -- Define the icon signs only once
57+
--- -- Only needed if you are using icon_placement = "signcolumn"
58+
--- -- self:define_sign(self.my_icon1)
59+
--- -- self:define_sign(self.my_icon2)
60+
---end
61+
---
62+
------Override node icon
63+
------@param node nvim_tree.api.Node
64+
------@return nvim_tree.api.highlighted_string? icon_node
65+
---function MyDecorator:icon_node(node)
66+
--- if node.name == "example" then
67+
--- return self.my_icon_node
68+
--- else
69+
--- return nil
70+
--- end
71+
---end
72+
---
73+
------Return two icons for DecoratorIconPlacement "after"
74+
------@param node nvim_tree.api.Node
75+
------@return nvim_tree.api.highlighted_string[]? icons
76+
---function MyDecorator:icons(node)
77+
--- if node.name == "example" then
78+
--- return { self.my_icon1, self.my_icon2, }
79+
--- else
80+
--- return nil
81+
--- end
82+
---end
83+
---
84+
------Exactly one highlight group for DecoratorHighlightRange "name"
85+
------@param node nvim_tree.api.Node
86+
------@return string? highlight_group
87+
---function MyDecorator:highlight_group(node)
88+
--- if node.name == "example" then
89+
--- return self.my_highlight_group
90+
--- else
91+
--- return nil
92+
--- end
93+
---end
94+
---
95+
---return MyDecorator
96+
---```

‎scripts/vimdoc_config.lua‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,9 @@ local srcs_api = {
6363

6464
---@type Src[]
6565
local srcs_class = {
66-
{ helptag = "nvim-tree-class", section = "Class", path = pre .. "classic.lua", },
67-
{ helptag = "nvim-tree-class-decorator", section = "Class: Decorator", path = pre .. "_meta/api/decorator.lua", },
66+
{ helptag = "nvim-tree-class", section = "Class", path = pre .. "classic.lua", },
67+
{ helptag = "nvim-tree-class-decorator", section = "Class: Decorator", path = pre .. "_meta/api/decorator.lua", },
68+
{ helptag = "nvim-tree-class-decorator-example", section = "Class: Decorator: example", path = pre .. "_meta/api/decorator_example.lua", },
6869
}
6970

7071
---Map paths to file names

0 commit comments

Comments
 (0)