1notcurses_tree(3) notcurses_tree(3)
2
6 notcurses_tree - high-level hierarchical line-based data
7
9 #include <notcurses/notcurses.h>
10 struct nctree;
12 struct ncplane;
13 typedef struct nctree_item {
15 void* curry;
16 struct nctree_item* subs;
17 unsigned subcount;
18 } nctree_item;
19 typedef struct nctree_options {
21 const nctree_item* items; // top-level nctree_item array
22 unsigned count; // size of |items|
23 int (*nctreecb)(struct ncplane*, void*, int); // item callback
24 int indentcols; // columns to indent per hierarchy
25 uint64_t flags; // bitfield of NCTREE_OPTION_*
26 } nctree_options;
27 struct nctree* nctree_create(struct ncplane* n, const nctree_options*
29 opts);
30 struct ncplane* nctree_plane(struct nctree* n);
32 int nctree_redraw(struct nctree* n);
34 bool nctree_offer_input(struct nctree* n, const ncinput* ni);
36 void* nctree_focused(struct nctree* n);
38 void* nctree_next(struct nctree* n);
40 void* nctree_prev(struct nctree* n);
42 void* nctree_goto(struct nctree* n, const int* path, int* failpath);
44 int nctree_add(struct nctree* n, const unsigned* path, const nc‐
46 tree_item* add);
47 int nctree_del(struct nctree* n, const unsigned* path);
49 void nctree_destroy(struct nctree* n);
51
53 nctrees organize hierarchical items, and allow them to be browsed.
54 Each item can have arbitrary subitems. Items can be collapsed and ex‐
55 panded. The display supports scrolling and searching.
56 An nctree cannot be empty. count must be non-zero, and items must not
58 be NULL. The callback function nctreecb must also be non-NULL.
59 The callback function nctreecb is called on tree items when the tree is
61 redrawn. It will be called on each visible item, and any item which
62 has become hidden. If the item is newly hidden, the ncplane argument
63 will be NULL. If the item is newly visible, the ncplane argument will
64 be an empty plane. If the item was already visible, the ncplane argu‐
65 ment will be the same plane passed before. If the item has not changed
66 since the last time the callback was invoked, there is no need to
67 change the plane, and the callback can return immediately. Otherwise,
68 the plane ought be drawn by the callback. Any unused rows ought be
69 trimmed away using ncplane_resize. If the plane is expanded in the
70 callback, it will be shrunk back down by the widget. The int parameter
71 indicates distance from the focused item. If the parameter is nega‐
72 tive, the item is before the focused item; a positive parameter implies
73 that the item follows the focused item; the focused item itself is
74 passed zero.
75 nctree_goto, nctree_add, and nctree_del all use the concept of a path.
77 A path is an array of unsigned values, terminated by UINT_MAX, with
78 each successive value indexing into the hierarchy thus far. The root
79 node of the nctree thus always has a 2-element path of [0, UINT_MAX].
80
82 nctree_create returns NULL for invalid options. This includes a NULL
83 items or nctreecb field, or a zero count field.
84 nctree_next and nctree_prev both return the curry pointer from the new‐
86 ly-focused item. nctree_focused returns the curry pointer from the al‐
87 ready-focused item.
88 nctree_goto returns the curry pointer from the newly-focused item. If
90 path is invalid, the first invalid hierarchy level is written to fail‐
91 path, and NULL is returned. If path is valid, the value -1 is written
92 to failpath. Since it is possible for a curry pointer to be NULL, one
93 should check failpath before assuming the operation failed.
94 nctree_add and nctree_del both return -1 for an invalid path, and 0
96 otherwise.
97
99 nctree shares many properties with notcurses_reel. Unlike the latter,
100 nctrees support arbitrary hierarchical levels.
101 nctree used to only handle static data, but nctree_add and nctree_del
103 were added in Notcurses 3.0.1.
104
106 notcurses(3), notcurses_input(3), notcurses_plane(3), notcurses_reel(3)
107
109 nick black <nickblack@linux.com>.
110 v3.0.8 notcurses_tree(3)