1notcurses_tree(3)                                            notcurses_tree(3)
2
3
4

NAME

6       notcurses_tree - high-level hierarchical line-based data
7

SYNOPSIS

9       #include <notcurses/notcurses.h>
10
11              struct nctree;
12              struct ncplane;
13
14              typedef struct nctree_item {
15                void* curry;
16                struct nctree_item* subs;
17                unsigned subcount;
18              } nctree_item;
19
20              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
28       struct  nctree*  nctree_create(struct ncplane* n, const nctree_options*
29       opts);
30
31       struct ncplane* nctree_plane(struct nctree* n);
32
33       int nctree_redraw(struct nctree* n);
34
35       bool nctree_offer_input(struct nctree* n, const ncinput* ni);
36
37       void* nctree_focused(struct nctree* n);
38
39       void* nctree_next(struct nctree* n);
40
41       void* nctree_prev(struct nctree* n);
42
43       void* nctree_goto(struct nctree* n, const int* spec, size_t  specdepth,
44       int* failspec);
45
46       void nctree_destroy(struct nctree* n);
47

DESCRIPTION

49       nctrees  organize  static  hierarchical  items,  and  allow  them to be
50       browsed.  Each item can have arbitrary subitems.   Items  can  be  col‐
51       lapsed  and  expanded.   The  display supports scrolling and searching.
52       Items cannot be added or removed, however; they  must  be  provided  in
53       their entirety at creation time.
54
55       An  nctree cannot be empty.  count must be non-zero, and items must not
56       be NULL.  The callback function nctreecb must also be non-NULL.
57
58       The callback function nctreecb is called on tree items when the tree is
59       redrawn.   It  will  be called on each visible item, and any item which
60       has become hidden.  If the item is newly hidden, the  ncplane  argument
61       will  be NULL.  If the item is newly visible, the ncplane argument will
62       be an empty plane.  If the item was already visible, the ncplane  argu‐
63       ment will be the same plane passed before.  If the item has not changed
64       since the last time the callback was  invoked,  there  is  no  need  to
65       change  the plane, and the callback can return immediately.  Otherwise,
66       the plane ought be drawn by the callback.  Any  unused  rows  ought  be
67       trimmed  away  using  ncplane_resize.   If the plane is expanded in the
68       callback, it will be shrunk back down by the widget.  The int parameter
69       indicates  distance  from  the focused item.  If the parameter is nega‐
70       tive, the item is before the focused item; a positive parameter implies
71       that  the  item  follows  the  focused item; the focused item itself is
72       passed zero.
73

RETURN VALUES

75       nctree_create returns NULL for invalid options.  This includes  a  NULL
76       items or nctreecb field, or a zero count field.
77
78       nctree_next and nctree_prev both return the curry pointer from the new‐
79       ly-focused item.  nctree_focused returns the curry pointer from the al‐
80       ready-focused item.
81

NOTES

83       nctree  shares many properties with notcurses_reel.  Unlike the latter,
84       nctrees support arbitrary hierarchical levels, but they  do  not  allow
85       elements to come and go across the lifetime of the widget.
86

SEE ALSO

88       notcurses(3), notcurses_input(3), notcurses_plane(3), notcurses_reel(3)
89

AUTHORS

91       nick black <nickblack@linux.com>.
92
93
94
95                                    v2.3.1                   notcurses_tree(3)
Impressum