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 argument 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 callback 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 focused 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 assuming 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 hierarchical 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)