NAME

       notcurses_tree - high-level hierarchical line-based data

SYNOPSIS

       #include <notcurses/notcurses.h>

              struct nctree;
              struct ncplane;

              typedef struct nctree_item {
                void* curry;
                struct nctree_item* subs;
                unsigned subcount;
              } nctree_item;

              typedef struct nctree_options {
                const nctree_item* items; // top-level nctree_item array
                unsigned count;           // size of |items|
                int (*nctreecb)(struct ncplane*, void*, int); // item callback
                int indentcols;           // columns to indent per hierarchy
                uint64_t flags;           // bitfield of NCTREE_OPTION_*
              } nctree_options;

       struct nctree* nctree_create(struct ncplane* n, const nctree_options* opts);

       struct ncplane* nctree_plane(struct nctree* n);

       int nctree_redraw(struct nctree* n);

       bool nctree_offer_input(struct nctree* n, const ncinput* ni);

       void* nctree_focused(struct nctree* n);

       void* nctree_next(struct nctree* n);

       void* nctree_prev(struct nctree* n);

       void* nctree_goto(struct nctree* n, const int* path, int* failpath);

       int nctree_add(struct nctree* n, const unsigned* path, const nctree_item* add);

       int nctree_del(struct nctree* n, const unsigned* path);

       void nctree_destroy(struct nctree* n);

DESCRIPTION

       nctrees  organize  hierarchical  items,  and  allow  them  to  be  browsed.  Each item can have arbitrary
       subitems.  Items can be collapsed and expanded.  The display supports scrolling and searching.

       An nctree cannot be empty.  count must be non-zero, and items must not be NULL.   The  callback  function
       nctreecb must also be non-NULL.

       The  callback  function  nctreecb is called on tree items when the tree is redrawn.  It will be called on
       each visible item, and any item which has become hidden.  If the item is newly hidden, the ncplane  argu‐
       ment  will  be  NULL.  If the item is newly visible, the ncplane argument will be an empty plane.  If the
       item was already visible, the ncplane argument will be the same plane passed before.  If the item has not
       changed since the last time the callback was invoked, there is no need to change the plane, and the call‐
       back can return immediately.  Otherwise, the plane ought be drawn by the callback.  Any unused rows ought
       be trimmed away using ncplane_resize.  If the plane is expanded in the callback, it will be  shrunk  back
       down  by  the  widget.   The int parameter indicates distance from the focused item.  If the parameter is
       negative, the item is before the focused item; a positive parameter implies that the item follows the fo‐
       cused item; the focused item itself is passed zero.

       nctree_goto, nctree_add, and nctree_del all use the concept of a path.  A path is an  array  of  unsigned
       values,  terminated  by  UINT_MAX,  with each successive value indexing into the hierarchy thus far.  The
       root node of the nctree thus always has a 2-element path of [0, UINT_MAX].

RETURN VALUES

       nctree_create returns NULL for invalid options.  This includes a NULL items or nctreecb field, or a  zero
       count field.

       nctree_next  and  nctree_prev  both return the curry pointer from the newly-focused item.  nctree_focused
       returns the curry pointer from the already-focused item.

       nctree_goto returns the curry pointer from the newly-focused item.  If path is invalid, the first invalid
       hierarchy level is written to failpath, and NULL is returned.  If path is valid, the value -1 is  written
       to  failpath.   Since it is possible for a curry pointer to be NULL, one should check failpath before as‐
       suming the operation failed.

       nctree_add and nctree_del both return -1 for an invalid path, and 0 otherwise.

NOTES

       nctree shares many properties with notcurses_reel.  Unlike the latter, nctrees support arbitrary  hierar‐
       chical levels.

       nctree used to only handle static data, but nctree_add and nctree_del were added in Notcurses 3.0.1.

SEE ALSO

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

AUTHORS

       nick black <nickblack@linux.com>.

                                                     v3.0.7                                    notcurses_tree(3)